Scopira 20080306

scopira::tool::fileflow Class Reference

#include <fileflow.h>

Inheritance diagram for scopira::tool::fileflow:
scopira::tool::iflow_i scopira::tool::oflow_i scopira::tool::flow_i scopira::tool::flow_i scopira::tool::object scopira::tool::object

List of all members.

Public Types

enum  { append_c = 1024, trunc_c = 2048, linked_c = 4096, existing_c = 8192 }
 

access levels

More...
enum  { stdin_c = -1, stdout_c = -2, stderr_c = -3 }
 

special file descriptor (fd) numbers

More...
enum  seek_dir_t { seek_start_c = 0, seek_end_c = 1, seek_cur_c }
typedef ::off_t offset_t

Public Member Functions

 fileflow (void)
 fileflow (const std::string &filename, mode_t mode)
 fileflow (int fd, mode_t mode)
virtual bool failed (void) const
virtual size_t read (byte_t *_buf, size_t _maxsize)
virtual size_t write (const byte_t *_buf, size_t _size)
void open (const std::string &filename, mode_t mode)
void open (int fd, mode_t mode)
void close (void)
int get_os_handle (void) const
offset_t seek (offset_t howmuch, seek_dir_t dir=seek_start_c)
 seekers
void seek_reset (void)
 seeks to the start
offset_t tell (void) const
 tells the current location of the file pointer
bool resize (offset_t newsz)
void read_lock (void)
bool try_read_lock (void)
void write_lock (void)
bool try_write_lock (void)
void unlock (void)

Protected Attributes

mode_t dm_mode
 current modes, 0 for no-file
int dm_hand
 the file handle
bool dm_fail
 currently failed?

Detailed Description

The is a binary/raw flow stream object that reads and writes files to disk.

This class is often the base of many chains, and can also be used by itself for basic file reading and writing.

See also:
Input/output flows
Author:
Aleksander Demko

Member Enumeration Documentation

anonymous enum

access levels

Enumerator:
append_c 

append to any existing file

trunc_c 

this is the default, for output files

linked_c 

internal, you dont need to specifiy this

existing_c 

open an existinf file. do not trunc. do not append.

anonymous enum

special file descriptor (fd) numbers

Enumerator:
stdin_c 

this file descriptor represents the standard input stream, stdin

stdout_c 

this file descriptor represents the standard output stream, stdout

stderr_c 

this file descriptor represents the standard error stream, stderr


Constructor & Destructor Documentation

scopira::tool::fileflow::fileflow ( void  )

The default constructor.

You should then use open() to open a file.

Author:
Aleksander Demko
scopira::tool::fileflow::fileflow ( const std::string &  filename,
mode_t  mode 
)

A constructor that also opens a file. See the corresponding open() call for parameter information.

Author:
Aleksander Demko
scopira::tool::fileflow::fileflow ( int  fd,
mode_t  mode 
)

A constructor that also opens a file. See the corresponding open() call for parameter information.

Parameters:
fdthe file descriptor (OS specific)
modethe file mode to use
Author:
Aleksander Demko

Member Function Documentation

void scopira::tool::fileflow::close ( void  )

Close the currently opened file.

You normally do not need to call this as the file will be closed automatically if you:

  • try to open() another file
  • the fileflow object is destroyed
Author:
Aleksander Demko
virtual bool scopira::tool::fileflow::failed ( void  ) const [virtual]

Check if the file stream is in a failed state.

Returns:
true if the stream is in a failed state.
Author:
Aleksander Demko

Implements scopira::tool::flow_i.

Referenced by scopira::basekit::base_directio_slice::failed().

void scopira::tool::fileflow::open ( const std::string &  filename,
mode_t  mode 
)

Opens the given on disk file.

The mode is a bitmask (or-ed) of file modes.

It usually contains either (or both) of:

  • input_c (for reading from a file)
  • output_c (for writing to a file)

And possible some of:

  • append_c (append to any existing file)
  • trunc_c (truncate - delete - any existing file)
  • existing_c (open an existinf file, and fail if it doesn't exist)

Use failed() to check if the open was successfull.

Parameters:
filenameis the filename
modeis the file mode
Author:
Aleksander Demko
void scopira::tool::fileflow::open ( int  fd,
mode_t  mode 
)

Opens a file via an existing OS file descriptor. File descriptors are typically low level OS objects that you typically do not want to use. This method is provided for the few times users would want streams that reflect into standard OS file descriptors.

You can either pass it a file descriptor (fd) or one of the standard (std*_c) file descriptors. If you pass one of the standard streams (std*._c), mode is ignored)

Use failed() to check if the open was successfull.

Parameters:
fdthe file descriptor (OS specific)
modethe file mode to use
Author:
Aleksander Demko
virtual size_t scopira::tool::fileflow::read ( byte_t _buf,
size_t  _maxsize 
) [virtual]

Reads a raw array of bytes from the file.

Parameters:
_bufthe buffer to read into.
_maxsizethe maximum number of bytes to read
Returns:
the actual number of bytes read
Author:
Aleksander Demko

Implements scopira::tool::iflow_i.

void scopira::tool::fileflow::read_lock ( void  )

Locks the (whole) file for (shared) reading. Blocks until the lock is acquired. Don't forget to unlock! File must be open for reading!

Author:
Aleksander Demko

Referenced by scopira::tool::read_flocker::read_flocker().

bool scopira::tool::fileflow::resize ( offset_t  newsz)

Resize the file (see ftruncate).

Returns true on success.

Author:
Aleksander Demko
bool scopira::tool::fileflow::try_read_lock ( void  )

Checks if a read lock is doable, right now. Returns true if a read lock is doable. Never blocks. File must be open for reading!

Author:
Aleksander Demko
bool scopira::tool::fileflow::try_write_lock ( void  )

Checks if a write lock is doable, right now. Returns true if a write lock is doable. Never blocks. File must be open for writing!

Author:
Aleksander Demko
void scopira::tool::fileflow::unlock ( void  )

Unlocks the current write or read lock. File must be open!

Author:
Aleksander Demko

Referenced by scopira::tool::read_flocker::~read_flocker(), and scopira::tool::write_flocker::~write_flocker().

virtual size_t scopira::tool::fileflow::write ( const byte_t _buf,
size_t  _size 
) [virtual]

Writes a raw array of bytes from the file.

Parameters:
_bufthe buffer to write from.
_sizethe size of the buffer
Returns:
the actual number of bytes written
Author:
Aleksander Demko

Implements scopira::tool::oflow_i.

void scopira::tool::fileflow::write_lock ( void  )

Locks the (whole) file for (exclusive) writing. Blocks until the lock is acquired. Don't forget to unlock! File must be open for writing!

Author:
Aleksander Demko

Referenced by scopira::tool::write_flocker::write_flocker().


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