Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes

base::FileBase Class Reference

Base File I/O (open, close, read, write chown, chmod, unlink ...). More...

#include <libppbase/base/File.h>

Inheritance diagram for base::FileBase:
base::FileT< sizeT, traits >

List of all members.

Public Types

enum  {
  ofReadOnly = 0x01, ofWriteOnly = 0x02, ofReadWrite = 0x03, ofAppend = 0x04,
  ofCreate = 0x08, ofTruncate = 0x10, ofExclusive = 0x20, ofWriteCreate = 0x0a,
  ofWriteCreateTruncate = 0x1a, ofReadWriteCreate = 0x0b, ofReadWriteCreateTruncate = 0x1b
}
 

file open flags

More...
enum  { tempDelNever = 0, tempDelOnClose = 1, tempDelOnDelete = 2 }
 

when to delete temp files

More...
typedef int handle_type
 data type for file handles
typedef size_t size_type
 data type for sizes

Public Member Functions

void close ()
 Closes the file.
void flush ()
 Flushes the internal write buffer.
int getFD () const
 Returns the file descriptor.
size_type getLineNo () const
 Returns current line number in file.
String getName () const
 Returns the file name.
bool isOpen () const
 Checks if the file is open.
bool lock (bool exclusive=true, bool block=true)
 Locks the file.
void open (const char *name, int flags=ofReadOnly, int mode=0666, bool temp=false, bool stayopen=false)
 Opens a file.
void open (const String &name, int flags=ofReadOnly, int mode=0666, bool temp=false, bool stayopen=false)
 Opens a file.
void open (handle_type fd, const String &name="", bool temp=false, bool stayopen=false, int allocbufs=3)
 Associates this file object with an already open file.
void openTemp (const String &name, const String &dir="", int tempdel=tempDelOnClose)
 Opens a temporary file.
size_type read (void *buf, size_type count, bool exact=false)
 Reads some bytes.
size_type read (String &rbuf, size_type count, bool exact=false)
 Reads some bytes.
bool readln (String &ret, bool strip=false)
 Reads a line.
bool readstr (String &ret)
 Reads a zero-terminated character string.
size_type readto (void *buf, size_type count, bool exact, unsigned timeout, bool *rtimedout)
 Reads some bytes with timeout.
void setBlocking (bool blocking)
 Sets or clears blocking flag.
void setReadBuffer (size_type size)
 Sets the read buffer size.
void setWriteBuffer (size_type size)
 Sets the write buffer size.
void unlock ()
 Unlocks the file.
size_type write (const void *buf, size_type count, bool exact=true)
 Writes some bytes.
size_type write (const String &buf, bool exact=true)
 Writes some bytes.
size_type writef (const char *fmt,...)
 Writes some bytes.
size_type writevf (const char *fmt, va_list ap)
 Writes some bytes.

Static Public Member Functions

static void chmod (const String &path, unsigned mode)
 Changes file access permissions.
static void chown (const String &path, unsigned uid, unsigned gid)
 Changes file ownership.
static void copy (const String &src, const String &dst)
 Copies a file.
static bool exists (const String &path)
 Checks if a file or directory exists.
static String getTempPath ()
 Gets the path for temporary files.
static bool isAbsoluteFileName (const String &name)
 Checks if a file name is an absolute file name.
static String makeFileName (const String &dname, const String &fname, bool fixdelim=true)
 Creates a file name out of a directory and file name part.
static void mkfifo (const String &name, unsigned mode)
 Creates a named pipe.
static void move (const String &oldpath, const String &newpath)
 Moves a file.
static void rename (const String &oldpath, const String &newpath)
 Renames a file.
template<class charT , class traits >
static void split (const StringT< charT, traits > &filename, StringT< charT, traits > &dirname, StringT< charT, traits > &basename)
 Split a full path name into directory and file parts.
static void symlink (const String &oldpath, const String &newpath, bool force=false)
 Creates a symbolic link.
static void touch (const String &path, bool parent=false, unsigned dmode=0755, unsigned fmode=0644, unsigned uid=(unsigned)-1, unsigned gid=(unsigned)-1)
 Touches a file. Sets its file dates to the current date & time, creating the file if it does not exist already.
static void unlink (const String &path, bool force=false)
 Unlinks a file.

Protected Member Functions

 FileBase ()
 Constructor that does not open a file.
 FileBase (const char *name, int flags=ofReadOnly, int mode=0666)
 Constructor that opens a file.
 FileBase (const String &name, int flags=ofReadOnly, int mode=0666)
 Constructor that opens a file.
 FileBase (handle_type fd, const String &name="", bool temp=false, bool stayopen=false, int allocbufs=3)
 Constructor that creates a new file object with an already open file.
 ~FileBase ()
 Destructor.
 DISALLOW_COPY_CONSTRUCTOR_AND_ASSIGNMENT (FileBase)
 file objects cannot be duplicated

Protected Attributes

handle_type _fd
 file descriptor/handle
size_type _lineno
 current line in file
String _name
 file name
char * _rdbuf
 the read buffer
size_type _rdbufpos
 current position in the read buffer
size_type _rdbufsize
 size of the read buffer in bytes
size_type _rdbufused
 number of bytes in the read buffer
bool _stayopen
 flag: do not close file descriptor
bool _temp
 flag: this file is a temporary one
int _tempdel
 when to delete temp files
char * _wrbuf
 the write buffer
size_type _wrbufsize
 size of the write buffer in bytes
size_type _wrbufused
 number of bytes in the write buffer

Detailed Description

Base File I/O (open, close, read, write chown, chmod, unlink ...).

Author:
Christoph Schwarz
Version:
$Id: File.h 21 2010-09-05 04:18:17Z cschwarz1 $

Member Enumeration Documentation

anonymous enum

file open flags

Enumerator:
ofReadOnly 

open read-only

ofWriteOnly 

open write-only

ofReadWrite 

open read-write

ofAppend 

append to file

ofCreate 

create if it does not exist

ofTruncate 

truncate file

ofExclusive 

exclusive access

ofWriteCreate 

shortcut: open for write, create file

ofWriteCreateTruncate 

shortcut: open for write, create and truncate file

ofReadWriteCreate 

shortcut: open for read and write, create file

ofReadWriteCreateTruncate 

shortcut: open for read and write, create and truncate file

anonymous enum

when to delete temp files

Enumerator:
tempDelNever 

never delete temp files

tempDelOnClose 

delete on file close

tempDelOnDelete 

delete on object destruction

Constructor & Destructor Documentation

base::FileBase::FileBase ( const char *  name,
int  flags = ofReadOnly,
int  mode = 0666 
) [protected]

Constructor that opens a file.

Parameters:
name file name
flags open flags
mode open mode
Exceptions:
std::bad_alloc when out of memory
IOException on error
base::FileBase::FileBase ( const String &  name,
int  flags = ofReadOnly,
int  mode = 0666 
) [protected]

Constructor that opens a file.

Parameters:
name file name
flags open flags
mode open mode
Exceptions:
std::bad_alloc when out of memory
IOException on error
base::FileBase::FileBase ( handle_type  fd,
const String &  name = "",
bool  temp = false,
bool  stayopen = false,
int  allocbufs = 3 
) [protected]

Constructor that creates a new file object with an already open file.

Parameters:
fd the already open file descriptor
name the file name
temp flag: this is a temporary file
stayopen flag: keep file descriptor open
allocbufs bitlist: bit 0 = allocate read buffer, bit 1 = allocate write buffer
Exceptions:
std::bad_alloc when out of memory
IOException on error

Member Function Documentation

static void base::FileBase::chmod ( const String &  path,
unsigned  mode 
) [static]

Changes file access permissions.

Parameters:
path full file name
mode new access permissions
Exceptions:
IOException on error
static void base::FileBase::chown ( const String &  path,
unsigned  uid,
unsigned  gid 
) [static]

Changes file ownership.

Parameters:
path full file name
uid owner's user id
gid owner's group id
Exceptions:
IOException on error
void base::FileBase::close (  ) 

Closes the file.

Exceptions:
IOException on error
static void base::FileBase::copy ( const String &  src,
const String &  dst 
) [static]

Copies a file.

Parameters:
src the source file name
dst the destionation file name
static bool base::FileBase::exists ( const String &  path  )  [static]

Checks if a file or directory exists.

Parameters:
path file name to check
Exceptions:
IOException on error
void base::FileBase::flush (  ) 

Flushes the internal write buffer.

Exceptions:
IOException on error

Referenced by base::FileT< size_t >::seek(), and base::FileT< size_t >::seekEOF().

int base::FileBase::getFD (  )  const

Returns the file descriptor.

Returns:
the file descriptor
static String base::FileBase::getTempPath (  )  [static]

Gets the path for temporary files.

Returns:
the path for temporary files
Exceptions:
IOException on error
static bool base::FileBase::isAbsoluteFileName ( const String &  name  )  [static]

Checks if a file name is an absolute file name.

Parameters:
name the file name to check
Returns:
true if it is an absolute file name, false if not
bool base::FileBase::isOpen (  )  const

Checks if the file is open.

Returns:
true if the file is open, false if not
bool base::FileBase::lock ( bool  exclusive = true,
bool  block = true 
)

Locks the file.

Parameters:
exclusive flag: true = exclusive lock, false = shared lock
block flag: true = block until lock has been acquired, false = return false if lock can not be acquired immediately
Returns:
true lock has been set
false lock could not be set (only in non-blocking mode)
Exceptions:
IOException on error
static String base::FileBase::makeFileName ( const String &  dname,
const String &  fname,
bool  fixdelim = true 
) [static]

Creates a file name out of a directory and file name part.

Parameters:
dname the directory name part
fname the file name part
fixdelim flag: fix directory delimiters (replace \ with / on UNIX, and / with \ on Windows)
Returns:
the resulting file name
static void base::FileBase::mkfifo ( const String &  name,
unsigned  mode 
) [static]

Creates a named pipe.

Parameters:
name the path name
mode the access permissions
Exceptions:
IOException on error
static void base::FileBase::move ( const String &  oldpath,
const String &  newpath 
) [static]

Moves a file.

Parameters:
oldpath old file name (full path)
newpath new file name (full path)
Exceptions:
IOException on error
void base::FileBase::open ( const char *  name,
int  flags = ofReadOnly,
int  mode = 0666,
bool  temp = false,
bool  stayopen = false 
)

Opens a file.

Parameters:
name file name
flags open flags
mode open mode
temp flag: this is a temporary file
stayopen flag: keep file descriptor open
Exceptions:
std::bad_alloc when out of memory
IOException on error
void base::FileBase::open ( const String &  name,
int  flags = ofReadOnly,
int  mode = 0666,
bool  temp = false,
bool  stayopen = false 
)

Opens a file.

Parameters:
name file name
flags open flags
mode open mode
temp flag: this is a temporary file
stayopen flag: keep file descriptor open
Exceptions:
std::bad_alloc when out of memory
IOException on error
void base::FileBase::open ( handle_type  fd,
const String &  name = "",
bool  temp = false,
bool  stayopen = false,
int  allocbufs = 3 
)

Associates this file object with an already open file.

Parameters:
fd the already open file descriptor
name the file name
temp flag: this is a temporary file
stayopen flag: keep file descriptor open
allocbufs bitlist: bit 0 = allocate read buffer, bit 1 = allocate write buffer
Exceptions:
std::bad_alloc when out of memory
IOException on error
void base::FileBase::openTemp ( const String &  name,
const String &  dir = "",
int  tempdel = tempDelOnClose 
)

Opens a temporary file.

Parameters:
name file base name
dir the directory to create the file in, if empty it uses the system's temporary directory
tempdel when to delete the temporary file
Exceptions:
std::bad_alloc when out of memory
IOException on error
size_type base::FileBase::read ( void *  buf,
size_type  count,
bool  exact = false 
)

Reads some bytes.

Parameters:
buf buffer
count number of bytes to read
exact read exactly count bytes, throw an exception if it is not possible to read this many bytes (because of EOF)
Returns:
number of bytes acutally read, 0=EOF
Exceptions:
IOException on error
size_type base::FileBase::read ( String &  rbuf,
size_type  count,
bool  exact = false 
)

Reads some bytes.

Parameters:
rbuf buffer
count number of bytes to read
exact read exactly count bytes, throw an exception if it is not possible to read this many bytes (because of EOF)
Returns:
number of bytes acutally read, 0=EOF
Exceptions:
IOException on error
bool base::FileBase::readln ( String &  ret,
bool  strip = false 
)

Reads a line.

Parameters:
ret returns the read line
strip flag: strip cr/lf from end of line
Returns:
success flag: true=line read, false=EOF
Exceptions:
IOException on error
bool base::FileBase::readstr ( String &  ret  ) 

Reads a zero-terminated character string.

Parameters:
ret returns the read string
Returns:
success flag: true=line read, false=EOF
Exceptions:
IOException on error
size_type base::FileBase::readto ( void *  buf,
size_type  count,
bool  exact,
unsigned  timeout,
bool *  rtimedout 
)

Reads some bytes with timeout.

Parameters:
buf buffer
count number of bytes to read
exact read exactly count bytes, throw an exception if it is not possible to read this many bytes (because of EOF)
timeout timeout in seconds
rtimedout if not NULL, returns true if a timeout occurred and false on EOF
Returns:
number of bytes acutally read, 0=EOF or timeout
Exceptions:
IOException on error
static void base::FileBase::rename ( const String &  oldpath,
const String &  newpath 
) [static]

Renames a file.

Parameters:
oldpath old file name (full path)
newpath new file name (full path)
Exceptions:
IOException on error
void base::FileBase::setBlocking ( bool  blocking  ) 

Sets or clears blocking flag.

Parameters:
blocking true=blocking, false=non-blocking
Exceptions:
IOException on error
void base::FileBase::setReadBuffer ( size_type  size  ) 

Sets the read buffer size.

For maximim efficency, set the buffer size before opening the file, because the buffer is allocated on opening. Nevertheless, the buffer size can be changed at any time. The default size is 4096 bytes.

Parameters:
size the read buffer size in bytes
Exceptions:
IOException on error
std::bad_alloc if out of memory
void base::FileBase::setWriteBuffer ( size_type  size  ) 

Sets the write buffer size.

For maximim efficency, set the buffer size before opening the file, because the buffer is allocated on opening. Nevertheless, the buffer size can be changed at any time. The default size is 4096 bytes.

Parameters:
size the write buffer size in bytes
Exceptions:
IOException on error
std::bad_alloc if out of memory
static void base::FileBase::symlink ( const String &  oldpath,
const String &  newpath,
bool  force = false 
) [static]

Creates a symbolic link.

Parameters:
oldpath where the symbolic link points to (=its contents)
newpath full path name of the symbolic link (=where it resides)
force flag: remove newpath if it already exists
Exceptions:
IOException on error
static void base::FileBase::touch ( const String &  path,
bool  parent = false,
unsigned  dmode = 0755,
unsigned  fmode = 0644,
unsigned  uid = (unsigned)-1,
unsigned  gid = (unsigned)-1 
) [static]

Touches a file. Sets its file dates to the current date & time, creating the file if it does not exist already.

Parameters:
path the full path name of the file to touch
parent flag: create parent directories if necessary
dmode access mode of the new directories
fmode access mode of the new file
uid owner (user id) of the new file (and new directories), (unsigned)-1 = current user
gid owner (group id) of the new file (and new directories), (unsigned)-1 = current group
Exceptions:
IOException on error
static void base::FileBase::unlink ( const String &  path,
bool  force = false 
) [static]

Unlinks a file.

Parameters:
path the full path name of the file to unlink
force flag: ignore "file does not exist" error
Exceptions:
IOException on error
void base::FileBase::unlock (  ) 

Unlocks the file.

Exceptions:
IOException on error
size_type base::FileBase::write ( const String &  buf,
bool  exact = true 
)

Writes some bytes.

Parameters:
buf buffer
exact write exactly count bytes, throw an exception if it is not possible to write this many bytes
Returns:
number of bytes acutally written
Exceptions:
IOException on error
size_type base::FileBase::write ( const void *  buf,
size_type  count,
bool  exact = true 
)

Writes some bytes.

Parameters:
buf buffer
count number of bytes to write
exact write exactly count bytes, throw an exception if it is not possible to write this many bytes
Returns:
number of bytes acutally written
Exceptions:
IOException on error
size_type base::FileBase::writef ( const char *  fmt,
  ... 
)

Writes some bytes.

Parameters:
fmt printf-like format string
... additional parameters
Returns:
number of bytes actually written
Exceptions:
IOException on error
size_type base::FileBase::writevf ( const char *  fmt,
va_list  ap 
)

Writes some bytes.

Parameters:
fmt printf-like format string
ap additional parameters
Returns:
number of bytes actually written
Exceptions:
IOException on error
The documentation for this class was generated from the following file:
Generated on Sun Sep 5 2010 21:01:38 for base_libraries by  doxygen 1.7.1