Lean class for file access. More...

#include <file.hpp>

Public Types
enum	mode { reading , writing , readwrite }
	Files can be opened for reading, writing, or both.

enum	creation_flags { existing = 0x1 , empty = 0x2 , current_user_only = 0x4 , current_user_and_admins_only = 0x8 }
	Creation flags when opening file for writing. More...

enum	seek_mode { begin , current , end }
	Used by seek. More...

typedef HANDLE	file_t

Public Member Functions
	file (native_string const &f, mode m, creation_flags d=existing)

	file (file_t fd)
	Creates file from descriptor. More...

	file (file const &)=delete

file &	operator= (file const &)=delete

	file (file &&op) noexcept

file &	operator= (file &&op) noexcept

bool	opened () const

	operator bool () const

result	open (native_string const &f, mode m, creation_flags d=existing)

void	close ()

file_t	fd ()
	Returns the raw file descriptor, but retains ownership.

file_t	detach ()

int64_t	size () const
	Gets size of file. More...

int64_t	seek (int64_t offset, seek_mode m)
	Relative seek based on seek mode. More...

int64_t	position ()
	Get Current position in file.

bool	truncate ()
	Truncate the file to the current position of the file pointer. More...

int64_t	read (void *buf, int64_t count)
	Read data from file. More...

int64_t	write (void const *buf, int64_t count)
	Write data to file. More...

bool	fsync ()
	Ensure data is flushed to disk. More...

bool	set_modification_time (datetime const &t)
	Sets modification time to specified time. More...

Detailed Description

Lean class for file access.

This class uses the system's native file access functions. It is a less convoluted and much faster alternative to the almost useless std::fstream.

Supports large files exceeding the 32bit limits.

Member Enumeration Documentation

◆ creation_flags

enum creation_flags

Creation flags when opening file for writing.

Only evaluated when opening existing files for writing Non-existing files will always be created when writing. Opening for reading never creates files.

Enumerator
existing	Keep existing data if file exists, otherwise create new.
empty	Truncate file if already existing, otherwise create new.
current_user_only	If set and a file is created, its permissions will be so that it is only accessible by the current user. Does not modify permissions if the file already exists.
current_user_and_admins_only	If set and a file is created, its permissions will be so that it is only accessible by the current user and the system administrators. On *nix, system adminstrators are just root. On MSW it is the built-in Administrators group. Does not modify permissions if the file already exists.

◆ seek_mode

enum seek_mode

Used by seek.

Enumerator
begin	Seek from beginning of file.
current	Seek from current position in the file.
end	Seek from end of file.

Constructor & Destructor Documentation

◆ file()

file ( file_t fd )

explicit

Creates file from descriptor.

Takes ownership of descriptor/handle.

Member Function Documentation

◆ fsync()

bool fsync ( )

Ensure data is flushed to disk.

Returns: true Data has been flushed to disk.; false Data could not be flushed to disk.

◆ read()

int64_t read	(	void *	buf,
		int64_t	count
	)

Read data from file.

Reading from file advances the file pointer with the number of octets read.

Parameters

buf	The buffer that should receive the data. Must be large enough to hold at least `count` octets
count	The number of octets to read

Returns: >0 The number of octets read and placed into buf. It may be less than count.; 0 at EOF; -1 on error

Note: Reading less than count octets can happen at any time, it does not indicate EOF.

◆ seek()

int64_t seek	(	int64_t	offset,
		seek_mode	m
	)

Relative seek based on seek mode.

It is possible to seek past the end of the file. Doing so does not change the size of the file. It will only change on subsequent writes.

You can get the current position int the file by passing current as seek_mode with a 0 offset.

Returns: -1 on error, otherwise new absolute offset in file

Note: On failure, the new position in the file is undefined.

◆ set_modification_time()

bool set_modification_time ( datetime const & t )

Sets modification time to specified time.

File must be opened for writing, of the call will fail.

◆ size()

int64_t size ( ) const

Gets size of file.

Returns: Size of file or -1 on error

◆ truncate()

bool truncate ( )

Truncate the file to the current position of the file pointer.

Despite its name, this function can extend the size of the file if the current file pointer is past the end of the file.

◆ write()

int64_t write	(	void const *	buf,
		int64_t	count
	)

Write data to file.

Writing to file advances the file pointer with the number of octets written