In addition to the standard I/O facilities, os_file offers random access, record locking, and truncation. By default, a file is automatically closed upon destruction.

The locking and seeking interfaces use the whence parameter to indicate where to apply the offset. Following are valid values.

Conversions permit interchangeable use of os_file and os_desc_t (native operating system descriptor).

Interface

Constructor

os_file()

Constructs an uninitialized file.

Constructor

os_file( os_desc_t descriptor )

Constructs a file with descriptor descriptor (default OS_UNDEFINED_DESC ).

Destructor

~os_file()

Destroys the file, closing the descriptor if necessary.

bool operator<( const os_file& file ) const

Returns true if descriptor is less than file .

bool operator==( const os_file& file ) const

Returns true if descriptor is the same as file .

(os_adapter)

operator os_adapter() const

Returns an os_adapter to the file.

(os_desc_t)

operator os_desc_t() const

Returns the file descriptor.

add_lock

bool add_lock( const os_file_lock& lock , bool block )

Adds lock to the file. If block (default true ) is false , returns immediately if the lock cannot be made; otherwise, blocks until the lock can occur or a signal is received. Returns true if the lock is obtained.

Throws: os_file_toolkit_error

auto_close

bool auto_close() const

Returns true if the file closes descriptor on destruction.

auto_close

void auto_close( bool flag )

If flag is true , close the file descriptor on destruction.

clear

void clear()

Resets file state to good.

close

void close()

Closes the file descriptor and sets it to OS_UNDEFINED .

Throws: os_file_toolkit_error

descriptor

void descriptor( os_desc_t descriptor )

Sets the file descriptor to descriptor .

descriptor

os_desc_t descriptor() const

Returns the file descriptor.

eof

bool eof() const

Returns true if the file has reached end of input.

event_on_eof

bool event_on_eof() const

Returns true if the file will generate an event on EOF.

event_on_eof

void event_on_eof( bool flag )

If flag is true , file will generate an event on EOF.

good

bool good() const

Returns true if the file is in a good state and not at EOF.

is_open

bool is_open() const

Returns true if the file is open.

bool ok() const

Returns true if the file is in a good state.

open

void open( const string& path , os_open_t open , os_ioctl_t control , enum Encoding enc = Ascii )

Opens a file with name path using open flags open (default O_OPEN ) and control flags control (default O_RDONLY ). Default enc is Ascii. Valid value for enc can be Ascii or Utf8.

Throws: os_file_toolkit_error

print

void print( ostream& stream ) const

Prints the file to stream .

read

ssize_t read( void* buffer , size_t bytes )

Reads up to the specified number of bytes of data into buffer . Returns the number of bytes actually read or returns -1 on error.

Throws: os_file_toolkit_error

remove_all_locks

void remove_all_locks()

Removes all the file's locks.

Throws: os_file_toolkit_error

remove_lock

void remove_lock( const os_file_lock& lock )

Removes all locks for the region specified by lock.

Throws: os_file_toolkit_error

remove_lock

void remove_lock( os_off_t length , os_off_t offset , short whence )

Removes all locks in the region of length (default 0 ) bytes at offset offset (default 0 ) bytes from whence (default SEEK_SET ). A length of zero indicates the region extends to the end of the file.

Throws: os_file_toolkit_error

resize_to

void resize_to( os_off_t length )

Resizes the file length to length bytes. If the file is shorter than length , the resulting gap is set to zeros. Note that the file must be open for this function to work.

Throws: os_file_toolkit_error

rewind

void rewind()

Sets the file pointer to the beginning of the file.

Throws: os_file_toolkit_error

seek

void seek( os_off_t offset , short whence )

Seeks to offset bytes from whence (default SEEK_SET ). If successful, clears the file's state.

Throws: os_file_toolkit_error

sync

void sync()

Flushes all the file's modified buffers to permanent storage. When this function returns, all data has been written.

Throws: os_file_toolkit_error

sync_all

/* static */ void sync_all()

Schedules all "dirty" data in memory to be written to disk including modified super blocks, modified inodes , and delayed block I/O.

tell

os_off_t tell() const

Returns the file pointer as an offset, in bytes, from the file's first byte or returns -1 on error.

Throws: os_file_toolkit_error

write

ssize_t write( const void* buffer , size_t bytes )

Writes up to the specified number of bytes of data from buffer to the file. Returns the number of bytes actually written or returns -1 on error.

Throws: os_file_toolkit_error

UNIX-Specific Interface

Constructor

os_file( const string& name , os_open_t open_control , os_ioctl_t io_control , os_mode_t mode , enum Encoding enc = Ascii )

Constructs a file with name name and mode mode (default 0660 ) using open flags open_control (default O_OPEN ) and control flags io_control (default O_RDONLY ). Default enc is Ascii. Valid value for enc can be Ascii or Utf8.

Throws: os_file_toolkit_error

conflicting_lock

bool conflicting_lock( const os_file_lock& lock , os_file_lock& conflict )

Checks for locks that would block lock . If a conflicting lock exists, returns true and sets conflict to the conflicting lock; otherwise, returns false .

Throws: os_file_toolkit_error

io_control

void io_control( os_ioctl_t control )

Sets the file's I/O control setting to control .

Throws: os_file_toolkit_error

io_control

os_ioctl_t io_control() const

Returns the file's I/O control setting.

Throws: os_file_toolkit_error

open

void open( const string& path , os_open_t open , os_ioctl_t control , os_mode_t mode , enum Encoding enc = Ascii )

Opens a file with name path and mode mode (default 0660 ) using open flags open (default O_OPEN ) and control flags control (default O_RDONLY ). Default enc is Ascii. Valid value for enc can be Ascii or Utf8.

Throws: os_file_toolkit_error

status

os_io_status status() const

Returns the file's I/O status.

Throws: os_file_toolkit_error

file

Library

Declaration

Interface

UNIX-Specific Interface

Windows-Specific Interface

Non-Member Functions