QoreFile Class Reference

provides controlled access to file data through Qore data structures More...

#include <QoreFile.h>

List of all members.

Public Member Functions

DLLEXPORT QoreFile (const QoreEncoding *cs=QCS_DEFAULT)
 creates the object and sets the default encoding
DLLEXPORT ~QoreFile ()
 closes the file and frees all memory allocated to the object
DLLEXPORT int open (const char *fn, int flags=O_RDONLY, int mode=0777, const QoreEncoding *cs=QCS_DEFAULT)
 opens the file and returns 0 for success, non-zero for error
DLLEXPORT int open2 (ExceptionSink *xsink, const char *fn, int flags=O_RDONLY, int mode=0777, const QoreEncoding *cs=QCS_DEFAULT)
 opens the file and raises a Qore-language exception if an error occurs
DLLEXPORT int close ()
 closes the file
DLLEXPORT void setEncoding (const QoreEncoding *cs)
 sets the encoding for the file
DLLEXPORT const QoreEncodinggetEncoding () const
 returns the encoding used for the file
DLLEXPORT int sync ()
 flushes the write buffer to disk
DLLEXPORT QoreStringNodereadLine (ExceptionSink *xsink)
 reads string data from the file up to a terminating '\n' character and returns the string read
DLLEXPORT int write (const QoreString *str, ExceptionSink *xsink)
 writes string data to the file, character encoding is converted if necessary, and returns the number of bytes written
DLLEXPORT int write (const BinaryNode *b, ExceptionSink *xsink)
 writes binary data to the file and returns the number of bytes written
DLLEXPORT int write (const void *data, qore_size_t len, ExceptionSink *xsink)
 writes binary data to the file and returns the number of bytes written
DLLEXPORT int writei1 (char i, ExceptionSink *xsink)
 writes 1-byte binary integer data to the file and returns the number of bytes written (normally 1)
DLLEXPORT int writei2 (short i, ExceptionSink *xsink)
 writes 2-byte (16bit) binary integer data in MSB (Most Significant Byte first, big endian) format to the file and returns the number of bytes written (normally 2)
DLLEXPORT int writei4 (int i, ExceptionSink *xsink)
 writes 4-byte (32bit) binary integer data in MSB (Most Significant Byte first, big endian) format to the file and returns the number of bytes written (normally 4)
DLLEXPORT int writei8 (int64 i, ExceptionSink *xsink)
 writes 8-byte (64bit) binary integer data in MSB (Most Significant Byte first, big endian) format to the file and returns the number of bytes written (normally 8)
DLLEXPORT int writei2LSB (short i, ExceptionSink *xsink)
 writes 2-byte (16bit) binary integer data in LSB (Least Significant Byte first, little endian) format to the file and returns the number of bytes written (normally 2)
DLLEXPORT int writei4LSB (int i, ExceptionSink *xsink)
 writes 4-byte (32bit) binary integer data in LSB (Least Significant Byte first, little endian)format to the file and returns the number of bytes written (normally 4)
DLLEXPORT int writei8LSB (int64 i, ExceptionSink *xsink)
 writes 8-byte (64bit) binary integer data in LSB (Least Significant Byte first, little endian) format to the file and returns the number of bytes written (normally 8)
DLLEXPORT int readu1 (unsigned char *val, ExceptionSink *xsink)
 reads a 1-byte unsigned integer from the file and returns the value read as an output parameter
DLLEXPORT int readu2 (unsigned short *val, ExceptionSink *xsink)
 reads a 2-byte unsigned integer from the file in MSB (Most Significant Byte first, big endian) format and returns the value read as an output parameter
DLLEXPORT int readu4 (unsigned int *val, ExceptionSink *xsink)
 reads a 4-byte unsigned integer from the file in MSB (Most Significant Byte first, big endian) format and returns the value read as an output parameter
DLLEXPORT int readu2LSB (unsigned short *val, ExceptionSink *xsink)
 reads a 2-byte unsigned integer from the file in LSB (Least Significant Byte first, big endian) format and returns the value read as an output parameter
DLLEXPORT int readu4LSB (unsigned int *val, ExceptionSink *xsink)
 reads a 4-byte unsigned integer from the file in LSB (Least Significant Byte first, big endian) format and returns the value read as an output parameter
DLLEXPORT int readi1 (char *val, ExceptionSink *xsink)
 reads a 1-byte signed integer from the file and returns the value read as an output parameter
DLLEXPORT int readi2 (short *val, ExceptionSink *xsink)
 reads a 2-byte signed integer from the file in MSB (Most Significant Byte first, big endian) format and returns the value read as an output parameter
DLLEXPORT int readi4 (int *val, ExceptionSink *xsink)
 reads a 4-byte signed integer from the file in MSB (Most Significant Byte first, big endian) format and returns the value read as an output parameter
DLLEXPORT int readi8 (int64 *val, ExceptionSink *xsink)
 reads an 8-byte signed integer from the file in MSB (Most Significant Byte first, big endian) format and returns the value read as an output parameter
DLLEXPORT int readi2LSB (short *val, ExceptionSink *xsink)
 reads a 2-byte signed integer from the file in LSB (Least Significant Byte first, big endian) format and returns the value read as an output parameter
DLLEXPORT int readi4LSB (int *val, ExceptionSink *xsink)
 reads a 4-byte signed integer from the file in LSB (Least Significant Byte first, big endian) format and returns the value read as an output parameter
DLLEXPORT int readi8LSB (int64 *val, ExceptionSink *xsink)
 reads an 8-byte signed integer from the file in LSB (Least Significant Byte first, big endian) format and returns the value read as an output parameter
DLLEXPORT QoreStringNoderead (qore_offset_t size, ExceptionSink *xsink)
 reads string data from the file and returns the string read (caller owns the reference count returned)
DLLEXPORT BinaryNodereadBinary (qore_offset_t size, ExceptionSink *xsink)
 reads binary data from the file and returns the data read (caller owns the reference count returned)
DLLEXPORT QoreStringNoderead (qore_offset_t size, int timeout_ms, ExceptionSink *xsink)
 reads string data from the file and returns the string read (caller owns the reference count returned)
DLLEXPORT BinaryNodereadBinary (qore_offset_t size, int timeout_ms, ExceptionSink *xsink)
 reads binary data from the file and returns the data read (caller owns the reference count returned)
DLLEXPORT qore_size_t setPos (qore_size_t pos)
 sets the absolute file position to "pos"
DLLEXPORT qore_size_t getPos ()
 returns the absolute byte position in the file
DLLEXPORT QoreStringNodegetchar ()
 reads a single character from the file and returns it as a new string, caller owns the reference count returned
DLLEXPORT QoreStringNodegetFileName () const
 returns the filename of the file being read
DLLEXPORT int chown (uid_t owner, gid_t group, ExceptionSink *xsink)
 changes ownership of the file (if possible)
DLLEXPORT int lockBlocking (struct flock &fl, ExceptionSink *xsink)
 perform a file lock operation
DLLEXPORT int lock (const struct flock &fl, ExceptionSink *xsink)
 perform a file lock operation, does not block
DLLEXPORT int getLockInfo (struct flock &fl, ExceptionSink *xsink)
 get lock info operation, does not block
DLLEXPORT bool isDataAvailable (int timeout_ms, ExceptionSink *xsink) const
 returns true if data is available for the file descriptor
DLLEXPORT int getFD () const
 get file descriptor
DLLLOCAL int setTerminalAttributes (int action, QoreTermIOS *ios, ExceptionSink *xsink) const
 sets terminal attributes
DLLLOCAL int getTerminalAttributes (QoreTermIOS *ios, ExceptionSink *xsink) const
 gets terminal attributes
DLLLOCAL void setEventQueue (Queue *cbq, ExceptionSink *xsink)
 sets the event queue (not part of the library's pubilc API), must be already referenced before call
DLLLOCAL void cleanup (ExceptionSink *xsink)
 internal API, must be called before deleting the object if an event queue is set

Protected Member Functions

DLLLOCAL QoreFile (const QoreFile &)
 this function is not implemented; it is here as a private function in order to prohibit it from being used
DLLLOCAL QoreFileoperator= (const QoreFile &)
 this function is not implemented; it is here as a private function in order to prohibit it from being used


Detailed Description

provides controlled access to file data through Qore data structures

Each file has a default character encoding associated with it. String data read from the file will be tagged with this encoding. String data written to the file will be converted to this encoding if necessary before written.

See also:
QoreEncoding

Member Function Documentation

DLLEXPORT int QoreFile::open ( const char *  fn,
int  flags = O_RDONLY,
int  mode = 0777,
const QoreEncoding cs = QCS_DEFAULT 
)

opens the file and returns 0 for success, non-zero for error

Parameters:
fn the file name to open
flags the flags to use when opening the file
mode the mode mask to use when opening the file
cs the encoding to use for the file
Returns:
0 for success, non-zero for error
Note:
for a version that raises a Qore-language exception when an error occurs opening the file, see QoreFile::open2()
See also:
QoreFile::open2()

DLLEXPORT int QoreFile::open2 ( ExceptionSink xsink,
const char *  fn,
int  flags = O_RDONLY,
int  mode = 0777,
const QoreEncoding cs = QCS_DEFAULT 
)

opens the file and raises a Qore-language exception if an error occurs

Parameters:
xsink if an error occurs when opening the file, the Qore-language exception info will be added here
fn the file name to open
flags the flags to use when opening the file
mode the mode mask to use when opening the file
cs the encoding to use for the file
Returns:
0 for success, non-zero for error, meaning that an exception was raised
Note:
for a version that does not raise a Qore exception when errors occur, see QoreFile::open2()
See also:
QoreFile::open()

DLLEXPORT int QoreFile::close (  ) 

closes the file

Returns:
0 for success, non-zero for error

DLLEXPORT QoreStringNode* QoreFile::readLine ( ExceptionSink xsink  ) 

reads string data from the file up to a terminating '\n' character and returns the string read

if an error occurs (file is not open), a Qore-language exception is raised

Parameters:
xsink if an error occurs when opening the file, the Qore-language exception info will be added here
Returns:
the string read including the terminating '\n' (if any - if EOF is encountered then there may not be one) or 0 if there is an error or no data could be read. caller owns the reference count returned

DLLEXPORT int QoreFile::write ( const QoreString str,
ExceptionSink xsink 
)

writes string data to the file, character encoding is converted if necessary, and returns the number of bytes written

Qore-language exceptions can be thrown if the file is not opened or if encoding conversion fails

Parameters:
str the string to write to the file
xsink if an error occurs, the Qore-language exception info will be added here
Returns:
returns the number of bytes written (-1 if an exception was thrown)

DLLEXPORT int QoreFile::write ( const BinaryNode b,
ExceptionSink xsink 
)

writes binary data to the file and returns the number of bytes written

Qore-language exceptions can be thrown if the file is not opened

Parameters:
b the binary data to write the file
xsink if an error occurs, the Qore-language exception info will be added here
Returns:
returns the number of bytes written (-1 if an exception was thrown)

DLLEXPORT int QoreFile::write ( const void *  data,
qore_size_t  len,
ExceptionSink xsink 
)

writes binary data to the file and returns the number of bytes written

Qore-language exceptions can be thrown if the file is not opened

Parameters:
data the data to write to the file
len the length of data to write to the file
xsink if an error occurs, the Qore-language exception info will be added here
Returns:
returns the number of bytes written (-1 if an exception was thrown)

DLLEXPORT int QoreFile::writei1 ( char  i,
ExceptionSink xsink 
)

writes 1-byte binary integer data to the file and returns the number of bytes written (normally 1)

Qore-language exceptions can be thrown if the file is not opened

Parameters:
i the 1-byte integer to write to the file
xsink if an error occurs, the Qore-language exception info will be added here
Returns:
returns the number of bytes written (-1 if an exception was thrown)

DLLEXPORT int QoreFile::writei2 ( short  i,
ExceptionSink xsink 
)

writes 2-byte (16bit) binary integer data in MSB (Most Significant Byte first, big endian) format to the file and returns the number of bytes written (normally 2)

Qore-language exceptions can be thrown if the file is not opened

Parameters:
i the integer to write to the file
xsink if an error occurs, the Qore-language exception info will be added here
Returns:
returns the number of bytes written (-1 if an exception was thrown)
See also:
Qorefile::writei2LSB()

DLLEXPORT int QoreFile::writei4 ( int  i,
ExceptionSink xsink 
)

writes 4-byte (32bit) binary integer data in MSB (Most Significant Byte first, big endian) format to the file and returns the number of bytes written (normally 4)

Qore-language exceptions can be thrown if the file is not opened

Parameters:
i the integer to write to the file
xsink if an error occurs, the Qore-language exception info will be added here
Returns:
returns the number of bytes written (-1 if an exception was thrown)
See also:
Qorefile::writei4LSB()

DLLEXPORT int QoreFile::writei8 ( int64  i,
ExceptionSink xsink 
)

writes 8-byte (64bit) binary integer data in MSB (Most Significant Byte first, big endian) format to the file and returns the number of bytes written (normally 8)

Qore-language exceptions can be thrown if the file is not opened

Parameters:
i the integer to write to the file
xsink if an error occurs, the Qore-language exception info will be added here
Returns:
returns the number of bytes written (-1 if an exception was thrown)
See also:
Qorefile::writei4LSB()

DLLEXPORT int QoreFile::writei2LSB ( short  i,
ExceptionSink xsink 
)

writes 2-byte (16bit) binary integer data in LSB (Least Significant Byte first, little endian) format to the file and returns the number of bytes written (normally 2)

Qore-language exceptions can be thrown if the file is not opened

Parameters:
i the integer to write to the file
xsink if an error occurs, the Qore-language exception info will be added here
Returns:
returns the number of bytes written (-1 if an exception was thrown)
See also:
Qorefile::writei2()

DLLEXPORT int QoreFile::writei4LSB ( int  i,
ExceptionSink xsink 
)

writes 4-byte (32bit) binary integer data in LSB (Least Significant Byte first, little endian)format to the file and returns the number of bytes written (normally 4)

Qore-language exceptions can be thrown if the file is not opened

Parameters:
i the integer to write to the file
xsink if an error occurs, the Qore-language exception info will be added here
Returns:
returns the number of bytes written (-1 if an exception was thrown)
See also:
Qorefile::writei4()

DLLEXPORT int QoreFile::writei8LSB ( int64  i,
ExceptionSink xsink 
)

writes 8-byte (64bit) binary integer data in LSB (Least Significant Byte first, little endian) format to the file and returns the number of bytes written (normally 8)

Qore-language exceptions can be thrown if the file is not opened

Parameters:
i the integer to write to the file
xsink if an error occurs, the Qore-language exception info will be added here
Returns:
returns the number of bytes written (-1 if an exception was thrown)
See also:
Qorefile::writei4()

DLLEXPORT int QoreFile::readu1 ( unsigned char *  val,
ExceptionSink xsink 
)

reads a 1-byte unsigned integer from the file and returns the value read as an output parameter

A Qore-language exception can be thrown if the file is not opened

Parameters:
val output parameter: the integer value read from the file
xsink if an error occurs, the Qore-language exception info will be added here
Returns:
0 for OK, -1 for error
See also:
QoreFile::readi1()

DLLEXPORT int QoreFile::readu2 ( unsigned short *  val,
ExceptionSink xsink 
)

reads a 2-byte unsigned integer from the file in MSB (Most Significant Byte first, big endian) format and returns the value read as an output parameter

A Qore-language exception can be thrown if the file is not opened

Parameters:
val output parameter: the integer value read from the file
xsink if an error occurs, the Qore-language exception info will be added here
Returns:
0 for OK, -1 for error
See also:
QoreFile::readi2LSB()

QoreFile::readi2()

QoreFile::readi2LSB()

DLLEXPORT int QoreFile::readu4 ( unsigned int *  val,
ExceptionSink xsink 
)

reads a 4-byte unsigned integer from the file in MSB (Most Significant Byte first, big endian) format and returns the value read as an output parameter

A Qore-language exception can be thrown if the file is not opened

Parameters:
val output parameter: the integer value read from the file
xsink if an error occurs, the Qore-language exception info will be added here
Returns:
0 for OK, -1 for error
See also:
QoreFile::readu4LSB()

QoreFile::readi4LSB()

QoreFile::readi4()

DLLEXPORT int QoreFile::readu2LSB ( unsigned short *  val,
ExceptionSink xsink 
)

reads a 2-byte unsigned integer from the file in LSB (Least Significant Byte first, big endian) format and returns the value read as an output parameter

A Qore-language exception can be thrown if the file is not opened

Parameters:
val output parameter: the integer value read from the file
xsink if an error occurs, the Qore-language exception info will be added here
Returns:
0 for OK, -1 for error
See also:
QoreFile::readu2()

QoreFile::readi2()

QoreFile::readi2LSB()

DLLEXPORT int QoreFile::readu4LSB ( unsigned int *  val,
ExceptionSink xsink 
)

reads a 4-byte unsigned integer from the file in LSB (Least Significant Byte first, big endian) format and returns the value read as an output parameter

A Qore-language exception can be thrown if the file is not opened

Parameters:
val output parameter: the integer value read from the file
xsink if an error occurs, the Qore-language exception info will be added here
Returns:
0 for OK, -1 for error
See also:
QoreFile::readu4()

QoreFile::readi4LSB()

QoreFile::readi4()

DLLEXPORT int QoreFile::readi1 ( char *  val,
ExceptionSink xsink 
)

reads a 1-byte signed integer from the file and returns the value read as an output parameter

A Qore-language exception can be thrown if the file is not opened

Parameters:
val output parameter: the integer value read from the file
xsink if an error occurs, the Qore-language exception info will be added here
Returns:
0 for OK, -1 for error
See also:
QoreFile::readi1()

DLLEXPORT int QoreFile::readi2 ( short *  val,
ExceptionSink xsink 
)

reads a 2-byte signed integer from the file in MSB (Most Significant Byte first, big endian) format and returns the value read as an output parameter

A Qore-language exception can be thrown if the file is not opened

Parameters:
val output parameter: the integer value read from the file
xsink if an error occurs, the Qore-language exception info will be added here
Returns:
0 for OK, -1 for error
See also:
QoreFile::readi2LSB()

QoreFile::readu2()

QoreFile::readu2LSB()

DLLEXPORT int QoreFile::readi4 ( int *  val,
ExceptionSink xsink 
)

reads a 4-byte signed integer from the file in MSB (Most Significant Byte first, big endian) format and returns the value read as an output parameter

A Qore-language exception can be thrown if the file is not opened

Parameters:
val output parameter: the integer value read from the file
xsink if an error occurs, the Qore-language exception info will be added here
Returns:
0 for OK, -1 for error
See also:
QoreFile::readi4LSB()

QoreFile::readu4LSB()

QoreFile::readu4()

DLLEXPORT int QoreFile::readi8 ( int64 *  val,
ExceptionSink xsink 
)

reads an 8-byte signed integer from the file in MSB (Most Significant Byte first, big endian) format and returns the value read as an output parameter

A Qore-language exception can be thrown if the file is not opened

Parameters:
val output parameter: the integer value read from the file
xsink if an error occurs, the Qore-language exception info will be added here
Returns:
0 for OK, -1 for error
See also:
QoreFile::readi8LSB()

DLLEXPORT int QoreFile::readi2LSB ( short *  val,
ExceptionSink xsink 
)

reads a 2-byte signed integer from the file in LSB (Least Significant Byte first, big endian) format and returns the value read as an output parameter

A Qore-language exception can be thrown if the file is not opened

Parameters:
val output parameter: the integer value read from the file
xsink if an error occurs, the Qore-language exception info will be added here
Returns:
0 for OK, -1 for error
See also:
QoreFile::readi2()

QoreFile::readu2()

QoreFile::readu2LSB()

DLLEXPORT int QoreFile::readi4LSB ( int *  val,
ExceptionSink xsink 
)

reads a 4-byte signed integer from the file in LSB (Least Significant Byte first, big endian) format and returns the value read as an output parameter

A Qore-language exception can be thrown if the file is not opened

Parameters:
val output parameter: the integer value read from the file
xsink if an error occurs, the Qore-language exception info will be added here
Returns:
0 for OK, -1 for error
See also:
QoreFile::readi4()

QoreFile::readu4LSB()

QoreFile::readu4()

DLLEXPORT int QoreFile::readi8LSB ( int64 *  val,
ExceptionSink xsink 
)

reads an 8-byte signed integer from the file in LSB (Least Significant Byte first, big endian) format and returns the value read as an output parameter

A Qore-language exception can be thrown if the file is not opened

Parameters:
val output parameter: the integer value read from the file
xsink if an error occurs, the Qore-language exception info will be added here
Returns:
0 for OK, -1 for error
See also:
QoreFile::readi8()

DLLEXPORT QoreStringNode* QoreFile::read ( qore_offset_t  size,
ExceptionSink xsink 
)

reads string data from the file and returns the string read (caller owns the reference count returned)

A Qore-language exception can be thrown if the file is not opened

Parameters:
size the number of bytes to read from the file, use -1 to read all data from the file
xsink if an error occurs, the Qore-language exception info will be added here
Returns:
the string read (caller owns the reference count returned) or 0 if an error occured
Note:
the string will be tagged with the file's default encoding

DLLEXPORT BinaryNode* QoreFile::readBinary ( qore_offset_t  size,
ExceptionSink xsink 
)

reads binary data from the file and returns the data read (caller owns the reference count returned)

A Qore-language exception can be thrown if the file is not opened

Parameters:
size the number of bytes to read from the file, use -1 to read all data from the file
xsink if an error occurs, the Qore-language exception info will be added here
Returns:
the binary data read (caller owns the reference count returned) or 0 if an error occured

DLLEXPORT QoreStringNode* QoreFile::read ( qore_offset_t  size,
int  timeout_ms,
ExceptionSink xsink 
)

reads string data from the file and returns the string read (caller owns the reference count returned)

A Qore-language exception can be thrown if the file is not opened

Parameters:
size the number of bytes to read from the file, use -1 to read all data from the file
timeout_ms the maximum time to read a single block from the file; -1 = never timeout, 0 timeout immediately if no data is available
xsink if an error occurs, the Qore-language exception info will be added here
Returns:
the string read (caller owns the reference count returned) or 0 if an error occured
Note:
the string will be tagged with the file's default encoding

DLLEXPORT BinaryNode* QoreFile::readBinary ( qore_offset_t  size,
int  timeout_ms,
ExceptionSink xsink 
)

reads binary data from the file and returns the data read (caller owns the reference count returned)

A Qore-language exception can be thrown if the file is not opened

Parameters:
size the number of bytes to read from the file, use -1 to read all data from the file
timeout_ms the maximum time to read a single block from the file; -1 = never timeout, 0 timeout immediately if no data is available
xsink if an error occurs, the Qore-language exception info will be added here
Returns:
the binary data read (caller owns the reference count returned) or 0 if an error occured

DLLEXPORT qore_size_t QoreFile::setPos ( qore_size_t  pos  ) 

sets the absolute file position to "pos"

Parameters:
pos the file position in bytes to set (starting with byte position 0)

DLLEXPORT qore_size_t QoreFile::getPos (  ) 

returns the absolute byte position in the file

Returns:
the absolute byte position in the file

DLLEXPORT QoreStringNode* QoreFile::getchar (  ) 

reads a single character from the file and returns it as a new string, caller owns the reference count returned

can returns 0 if an error occurs FIXME: reads a single byte, not a character

Returns:
a new string consisting of the single character read from the file

DLLEXPORT bool QoreFile::isDataAvailable ( int  timeout_ms,
ExceptionSink xsink 
) const

returns true if data is available for the file descriptor

Parameters:
timeout_ms the maximum time to read a single block from the file; -1 = never timeout, 0 timeout immediately if no data is available
xsink if an error occurs, the Qore-language exception info will be added here
Returns:
true if data is available in the timeout period, false if not


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

Generated on Mon Oct 26 09:09:50 2009 for Qore Programming Language by  doxygen 1.5.6