utils5ext::File Class Reference

#include <file.h>

Public Types
enum	OpenMode {   om_read = 0x0001 , om_write = 0x0002 , om_append = 0x0004 , om_read_write = 0x0008 ,   om_no_overwrite = 0x0010 , om_shared_read = 0x0100 , om_shared_write = 0x0200 , om_sequential_access = 0x0400 ,   om_temporary_file = 0x0800 , om_short_lived = 0x1000 , om_text_mode = 0x2000 , om_write_through = 0x4000 ,   om_disable_file_system_cache = 0x8000 }
	Several flags to open files. Can be combined with bitwise or. More...
enum	FilePosRef { fp_begin = 0 , fp_current = 1 , fp_end = 2 }
	File position reference. More...

Public Member Functions
	File () noexcept
	Constructor.
virtual	~File ()
	Destructor. If handling an open file, the file is closed.
void	open (const a_util::filesystem::Path &filename, uint32_t mode)
void	close ()
void	attach (File &file)
void	detach ()
void	setReadCache (size_t read_cache_size)
size_t	read (void *buffer, size_t buffer_size)
void	readAll (void *buffer, size_t buffer_size)
size_t	skip (size_t number_of_bytes)
size_t	write (const void *buffer, size_t buffer_size)
void	writeAll (const void *buffer, size_t buffer_size)
void	write (const std::string &string)
void	readLine (std::string &string)
void	writeLine (const std::string &string)
FileSize	getSize () const
FilePos	getFilePos () const
FilePos	setFilePos (FilePos offset, FilePosRef move_mode)
bool	isEof ()
bool	isValid () const
void	truncate (FilePos size)

Protected Member Functions
void	initialize ()
void	allocReadCache (size_t cache_size)
void	freeReadCache ()
void *	internalMalloc (size_t size, bool use_segment_size=false)
void	internalFree (void *memory, bool use_segment_size=false)

Protected Attributes
FileHandle	_file
	File handle.
uint8_t *	_read_cache
	File read cache.
size_t	_file_cache_usage
	File cache usage.
size_t	_file_cache_offset
	File cache offset.
size_t	_file_cache_size
	File cache size.
bool	_read_cache_enabled
	Read cache enabled.
bool	_reference
	File is reference.
bool	_system_cache_disabled
	System cache disabled.
int	_sector_size
	Sector size.
FilePos	_sector_bytes_to_skip
	Sector bytes that will be skipped.

Detailed Description

File class.

Member Enumeration Documentation

FilePosRef

enum utils5ext::File::FilePosRef

File position reference.

Enumerator
fp_begin	offsets are measured from the beginning of the file
fp_current	offsets are measured from the current file position
fp_end	offsets are measured from the end of the file

OpenMode

enum utils5ext::File::OpenMode

Several flags to open files. Can be combined with bitwise or.

Enumerator
om_read	Open existing file. Can be combined with OM_SharedRead under Windows. Under Windows, the file must exist. Under Linux, if the file doesn't exist it will be created.
om_write	Creates a new file or overwrites existing files. Can be combined with OM_SharedWrite under windows.
om_append	Append data to existing file. Sets seeking position to the end of the file stream.
om_read_write	Open file in read-write mode. Under Windows, the file must exist. Under Linux, if the file doesn't exist it will be created.
om_no_overwrite	No overwrite if file already exists.
om_shared_read	Allows shared read access, use in addition to flags above. Exclusive write/read permissions for a whole file are not supported under Linux platforms without any file locks. All files are readable!
om_shared_write	Allows shared write access, use in addition to flags above. Exclusive write/read permissions for a whole file are not supported under Linux platforms without any file locks
om_sequential_access	Optimized for sequential access, use in addition to flags above.
om_temporary_file	File is of temporary purpose and will be deleted after all handles on the file are closed. Use in addition to flags above
om_short_lived	Advices the OS not to flush any data to the disk. Just supported on POSIX platforms.
om_text_mode	Opens the file in text mode instead of binary mode. Just supported on POSIX platforms
om_write_through	Immediately flush file data to disk. Windows only.
om_disable_file_system_cache	Disable all file system caches. Windows only.

Member Function Documentation

allocReadCache()

void utils5ext::File::allocReadCache ( size_t  cache_size )

protected

Allocate read cache.

Parameters

cache_size

Size of cache.

attach()

void utils5ext::File::attach

(

File &

file

)

This function attaches an existing instance of a file class to another.

Parameters

file	Reference to an existing file object.

close()

void utils5ext::File::close

(

)

Close file.

detach()

void utils5ext::File::detach

(

)

This function detaches existing references to file objects.

Exceptions

exceptions::ErrorFileAccess

freeReadCache()

void utils5ext::File::freeReadCache ( )

protected

Free read cache.

getFilePos()

FilePos utils5ext::File::getFilePos

(

)

const

This function retrieves the file pointer offset.

Returns

The function returns the file pointer offset from the beginning.

getSize()

FileSize utils5ext::File::getSize

(

)

const

This function retrieves the file size.

Returns

The function returns the file size.

initialize()

void utils5ext::File::initialize ( )

protected

Initialization.

internalFree()

void utils5ext::File::internalFree ( void *  memory, bool  use_segment_size = false  )

protected

Internal free method.

Parameters

memory	Pointer to memory.
use_segment_size	Keep segment size in mind.

internalMalloc()

void* utils5ext::File::internalMalloc ( size_t  size, bool  use_segment_size = false  )

protected

Internal allocation method.

Parameters

size	Size of cache.
use_segment_size	Keep segment size in mind.

Returns

Void pointer to allocated memory.

isEof()

bool utils5ext::File::isEof

(

)

Checks whether or not the end of the file has been reached.

Returns

Whether or not the end of the file has been reached.

isValid()

bool utils5ext::File::isValid

(

)

const

This function checks if the file object has an valid file handle.

Returns

Returns true, if the file handle is valid, otherwise false.

open()

void utils5ext::File::open	(	const a_util::filesystem::Path &	filename,
		uint32_t	mode
	)

This function opens an existing or creates a new file.

Parameters

filename	string that is the path to the desired file. The path can be relative, absolute, or a network name (UNC). uint32_t Mode: A uint32_t that defines the file sharing and access mode. It specifies the action to take when opening the file. You can combine options by using the bitwise-OR ( | ) operator.
mode	File open mode. For valid flags see the OpenMode enum.

Exceptions

exceptions::ErrorFileAccess,exceptions::ErrorFileAlreadyExists

read()

size_t utils5ext::File::read	(	void *	buffer,
		size_t	buffer_size
	)

This function reads data into a buffer from the file associated with the File object.

Parameters

buffer	Pointer to the user-supplied buffer that is to receive the data read from the file.
buffer_size	The maximum number of bytes to be read from the file. For text-mode files, carriage return-linefeed pairs are counted as single characters.

Returns

The number of bytes transferred to the buffer. Note that the return value may be less than buffer_size, if the end of file was reached. If there was a severe error, the function returns -1.

Exceptions

exceptions::ErrorFileAccess,std::invalid_argument

readAll()

void utils5ext::File::readAll	(	void *	buffer,
		size_t	buffer_size
	)

This function reads data into a buffer from the file associated with the File object. It ensures that all requested bytes have been read.

Parameters

buffer	Pointer to the user-supplied buffer that is to receive the data read from the file.
buffer_size	The maximum number of bytes to be read from the file. For text-mode files, carriage return-linefeed pairs are counted as single characters.

Exceptions

exceptions::ErrorFileAccess,std::invalid_argument,exceptions::EndOfFile

readLine()

void utils5ext::File::readLine

(

std::string &

string

)

This function reads a line of text data into a String object.

Parameters

string

[inout] String object to be filled with character data.

Exceptions

exceptions::ErrorFileAccess

setFilePos()

FilePos utils5ext::File::setFilePos	(	FilePos	offset,
		FilePosRef	move_mode
	)

This function moves the file pointer.

Parameters

offset	Offset value for pointer movement, relative to MoveMode.
move_mode	Fixed reference point for movement.

Remarks

The file pointer may be set beyond the end of the File. The next write will increase the filesize accordingly.

Returns

Returns the file position which was set (must not be equal to offset) or -1 if any error occurred.

setReadCache()

void utils5ext::File::setReadCache

(

size_t

read_cache_size

)

This function sets the file read cache size (default after open a file =0).

By setting the read cache to zero it is deactivated if system cache is used. If system cache is disabled we need an internal cache anyway and the default hd sector size of 512 bytes is used for cache size.

See also

om_disable_file_system_cache

Parameters

read_cache_size

Number of bytes to be allocated as read buffer

skip()

size_t utils5ext::File::skip

(

size_t

number_of_bytes

)

This function reads data from a file but does not store it .

Parameters

number_of_bytes

The maximum number of bytes to be skipped.

Returns

The number of bytes skipped. Note that the return value may be less than numberOfBytes, if the end of file was reached. If there was a severe error or the maximum number of bytes to skip was negative, the function returns -1.

Exceptions

exceptions::ErrorFileAccess

truncate()

void utils5ext::File::truncate

(

FilePos

size

)

This method truncates the file at the given size.

If the file is larger than the given size, the extra data is lost. If it was smaller it is extended.

Parameters

size	the size in bytes

Exceptions

exceptions::ErrorFileAccess

write() [1/2]

void utils5ext::File::write

(

const std::string &

string

)

This function writes string data from a buffer to the file associated with the File object.

Parameters

string

String object to be written to the file.

Exceptions

exceptions::ErrorFileAccess

write() [2/2]

size_t utils5ext::File::write	(	const void *	buffer,
		size_t	buffer_size
	)

This function writes data from a buffer to the file associated with the File object.

Parameters

buffer	Pointer to the user-supplied buffer that is to receive the data read from the file.
buffer_size	The maximum number of bytes to be read from the file. For text-mode files, carriage return-linefeed pairs are counted as single characters. If buffer_size is 0, the return value is always 0 and nothing is written.

Returns

The number of bytes transferred to the buffer. If there was an error or buffer was nullptr or buffer_size was less than 0, -1 is returned.

Attention

On win32 platforms only: If the file was opened with OM_DisableFileSystemCache there is a limitation of the maximum buffer size of approx. 64MB on x86 / approx. 32MB on x86-64. For further details have a look at MSDN WriteFile.

Exceptions

exceptions::ErrorFileAccess,std::invalid_argument

writeAll()

void utils5ext::File::writeAll	(	const void *	buffer,
		size_t	buffer_size
	)

This function writes data from a buffer to the file associated with the File object. It ensures that all requested bytes have been written.

Parameters

buffer	Pointer to the user-supplied buffer that is to receive the data read from the file.
buffer_size	The maximum number of bytes to be read from the file. For text-mode files, carriage return-linefeed pairs are counted as single characters. If bufferSize is 0, the return value is always 0 and nothing is written.

Exceptions

exceptions::ErrorFileAccess,std::invalid_argument

writeLine()

void utils5ext::File::writeLine

(

const std::string &

string

)

This function writes string data from a buffer to the file associated with the File object. The string is followed by a carriage return-linefeed pair.

Parameters

string

String object to be written to the file.

Exceptions

exceptions::ErrorFileAccess

---

The documentation for this class was generated from the following file:

• include/utils5extension/file.h