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

#include <QoreFile.h>

Inherited by File.

Public Member Methods
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	chown (uid_t owner, gid_t group, ExceptionSink *xsink)
	changes ownership of the file (if possible)

DLLLOCAL void	cleanup (ExceptionSink *xsink)
	internal API, must be called before deleting the object if an event queue is set

DLLEXPORT int	close ()
	closes the file More...

DLLEXPORT int	detachFd ()
	detaches and returns the file descriptor More...

DLLEXPORT QoreStringNode *	getchar ()
	reads a single byte from the file and returns it as a new string, caller owns the reference count returned More...

DLLEXPORT QoreStringNode *	getchar (ExceptionSink *xsink)
	reads a single character from the file and returns it as a new string, caller owns the reference count returned More...

DLLEXPORT const QoreEncoding *	getEncoding () const
	returns the encoding used for the file

DLLEXPORT int	getFD () const
	get file descriptor More...

DLLEXPORT QoreStringNode *	getFileName () const
	returns the filename of the file being read (NULL if no file name is set); caller owns the reference count returned

DLLEXPORT std::string	getFileNameStr () const
	returns the filename of the file being read as a std::string (the string is empty if no file name is set)

DLLEXPORT int	getLockInfo (hashdecl flock &fl, ExceptionSink *xsink)
	get lock info operation, does not block

DLLEXPORT int	getPollableDescriptor () const
	Returns the underlying file descriptor; -1 if not open. More...

DLLEXPORT size_t	getPos ()
	returns the absolute byte position in the file More...

DLLEXPORT size_t	getPos () const
	returns the absolute byte position in the file More...

DLLLOCAL int	getTerminalAttributes (QoreTermIOS ios, ExceptionSink xsink) const
	gets terminal attributes

DLLEXPORT QoreHashNode *	hstat (ExceptionSink *xsink) const
	returns a QoreHashNode with file status information More...

DLLEXPORT bool	isDataAvailable (int timeout_ms, ExceptionSink *xsink) const
	returns true if data is available for the file descriptor More...

DLLEXPORT bool	isOpen () const
	returns true if the file is open, false if not

DLLEXPORT bool	isTty () const
	returns true if the file is a tty

DLLEXPORT int	lock (const hashdecl flock &fl, ExceptionSink *xsink)
	perform a file lock operation, does not block

DLLEXPORT int	lockBlocking (hashdecl flock &fl, ExceptionSink *xsink)
	perform a file lock operation

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 More...

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 More...

DLLEXPORT QoreStringNode *	read (qore_offset_t size, ExceptionSink *xsink)
	reads string data from the file and returns the string read (caller owns the reference count returned) More...

DLLEXPORT QoreStringNode *	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) More...

DLLEXPORT int	read (QoreString &str, qore_offset_t size, ExceptionSink *xsink)
	reads string data from the file into a QoreString object (or subclass, such as QoreStringNode) and returns 0 for OK or non-zero for error More...

DLLEXPORT size_t	read (void ptr, size_t limit, int timeout_ms, ExceptionSink xsink)
	reads data from the file More...

DLLEXPORT int	readBinary (BinaryNode &b, qore_offset_t size, ExceptionSink *xsink)
	reads binary data from the file into a BinaryNode object and returns 0 for OK or non-zero for error More...

DLLEXPORT BinaryNode *	readBinary (qore_offset_t size, ExceptionSink *xsink)
	reads binary data from the file and returns the data read (caller owns the reference count returned) More...

DLLEXPORT BinaryNode *	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) More...

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 More...

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 More...

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 More...

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 More...

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 More...

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 More...

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 More...

DLLEXPORT QoreStringNode *	readLine (bool incl_eol, ExceptionSink *xsink)
	reads string data from the file up to and optionally including the terminating EOL characters (can be `"\n"`, `"\r"` or `"\r\n"`) and returns the string read More...

DLLEXPORT QoreStringNode *	readLine (ExceptionSink *xsink)
	reads string data from the file up to and including the terminating EOL characters (can be `"\n"`, `"\r"` or `"\r\n"`) and returns the string read with the EOL characters More...

DLLEXPORT int	readLine (QoreString &str)
	clears the string passed, then reads string data from the file up to and including the terminating EOL characters (can be `"\n"`, `"\r"` or `"\r\n"`), returns 0 for no error, -1 for EOF, -2 for file not opened More...

DLLEXPORT int	readLine (QoreString &str, bool incl_eol)
	clears the string passed, then reads string data from the file up to and optionally including the terminating EOL characters (can be `"\n"`, `"\r"` or `"\r\n"`), returns 0 for no error, -1 for EOF, -2 for file not opened More...

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 More...

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 More...

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 More...

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 More...

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 More...

DLLEXPORT int	readUntil (char byte, QoreString &str, bool incl_bytes=true)
	clears the string passed, then reads string data from the file up to a terminating byte value, returns 0 for no error, -1 for EOF, -2 for file not opened More...

DLLEXPORT QoreStringNode *	readUntil (const char bytes, bool incl_bytes, ExceptionSink xsink)
	reads string data from the file up to and optionally including the terminating EOL characters passed as an argument and returns the string read More...

DLLEXPORT int	readUntil (const char *bytes, QoreString &str, bool incl_bytes=true)
	clears the string passed, then reads string data from the file up to the given byte string, returns 0 for no error, -1 for EOF, -2 for file not opened More...

DLLEXPORT int	redirect (QoreFile &file, ExceptionSink *xsink)
	redirects the current file (this) to the argument More...

DLLEXPORT void	setEncoding (const QoreEncoding *cs)
	sets the encoding for the file

DLLLOCAL void	setEventQueue (ExceptionSink xsink, Queue q, QoreValue arg, bool with_data)
	sets the event queue (not part of the library's pubilc API), must be already referenced before call

DLLEXPORT size_t	setPos (size_t pos)
	sets the absolute file position to "pos" More...

DLLLOCAL int	setTerminalAttributes (int action, QoreTermIOS ios, ExceptionSink xsink) const
	sets terminal attributes

DLLEXPORT QoreListNode *	stat (ExceptionSink *xsink) const
	returns a QoreListNode with file status information More...

DLLEXPORT QoreHashNode *	statvfs (ExceptionSink *xsink) const
	returns a QoreHashNode with filesystem status information More...

DLLEXPORT int	sync ()
	flushes the write buffer to disk

DLLEXPORT int	write (const BinaryNode b, ExceptionSink xsink)
	writes binary data to the file and returns the number of bytes written More...

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 More...

DLLEXPORT int	write (const void data, size_t len, ExceptionSink xsink)
	writes binary data to the file and returns the number of bytes written More...

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) More...

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) More...

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) More...

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) More...

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) More...

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) More...

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) More...

Private Member Methods
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 QoreFile &	operator= (const QoreFile &)
	this function is not implemented; it is here as a private function in order to prohibit it from being used

Private Attributes
struct qore_qf_private *	priv
	private implementation

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

◆ close()

DLLEXPORT int QoreFile::close ( )

closes the file

Returns: 0 for success, non-zero for error

Referenced by FileOutputStream::close().

◆ detachFd()

DLLEXPORT int QoreFile::detachFd ( )

detaches and returns the file descriptor

the file object is left with no descriptor after this call; the caller owns the descriptor returned

Returns: the file descriptor, if open, or -1 if not

Since: Qore 0.9.3

◆ getchar() [1/2]

DLLEXPORT QoreStringNode * QoreFile::getchar ( )

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

note that this function is not guaranteed to read a character if the File's encoding is a multi-byte character encoding

Returns: a new string consisting of the single character read from the file; can return 0 if an error occurs

◆ getchar() [2/2]

DLLEXPORT QoreStringNode * QoreFile::getchar ( ExceptionSink * xsink )

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

This function will return a single character in the File's encoding even for multi-byte character encodings. However, a Qore-language exception will be thrown if invalid character data is read from the file (only thrown for multi-byte encodings).

Parameters

xsink if an error occurs, the Qore-language exception info will be added here

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

◆ getFD()

DLLEXPORT int QoreFile::getFD ( ) const

get file descriptor

Returns: the file descriptor, if open, or -1 if not

◆ getPollableDescriptor()

DLLEXPORT int QoreFile::getPollableDescriptor ( ) const

Returns the underlying file descriptor; -1 if not open.

Returns: the underlying file descriptor; -1 if not open

Since: Qore 1.12

◆ getPos() [1/2]

DLLEXPORT size_t QoreFile::getPos ( )

returns the absolute byte position in the file

Returns: the absolute byte position in the file

Deprecated:: : only the const variant will remain in the future

Referenced by FileInputStream::peek().

◆ getPos() [2/2]

DLLEXPORT size_t QoreFile::getPos ( ) const

returns the absolute byte position in the file

Returns: the absolute byte position in the file

◆ hstat()

DLLEXPORT QoreHashNode * QoreFile::hstat ( ExceptionSink * xsink ) const

returns a QoreHashNode with file status information

Parameters

xsink if an error occurs, the Qore-language exception info will be added here

Returns: a QoreHashNode with file status information

◆ isDataAvailable()

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

◆ open()

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()

◆ 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()

◆ read() [1/4]

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 characters 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 or the file is empty

Note: the string will be tagged with the file's default encoding

Since: Qore 0.8.13 this function uses character semantics instead of byte sementics

Referenced by FileInputStream::peek(), and FileInputStream::read().

◆ read() [2/4]

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 characters 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 or the file is empty

Note: the string will be tagged with the file's default encoding

Since: Qore 0.8.13 this function uses character semantics instead of byte sementics

◆ read() [3/4]

DLLEXPORT int QoreFile::read	(	QoreString &	str,
		qore_offset_t	size,
		ExceptionSink *	xsink
	)

reads string data from the file into a QoreString object (or subclass, such as QoreStringNode) and returns 0 for OK or non-zero for error

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

Parameters

str	the data read will be placed here
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: 0 for OK or non-zero for error

Note: the string will be tagged with the file's default encoding

◆ read() [4/4]

DLLEXPORT size_t QoreFile::read	(	void *	ptr,
		size_t	limit,
		int	timeout_ms,
		ExceptionSink *	xsink
	)

reads data from the file

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

Parameters

ptr	the destination buffer
limit	the maximum number of bytes to read
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 number of bytes read, 0 means EOF

◆ readBinary() [1/3]

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

reads binary data from the file into a BinaryNode object and returns 0 for OK or non-zero for error

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

Parameters

b	the data read will be placed here
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: 0 for OK or non-zero for error

◆ readBinary() [2/3]

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 or the file is empty

◆ readBinary() [3/3]

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

◆ readi1()

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()

◆ readi2()

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()

◆ readi2LSB()

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()

◆ readi4()

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()

◆ readi4LSB()

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()

◆ readi8()

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()

◆ readi8LSB()

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()

◆ readLine() [1/4]

DLLEXPORT QoreStringNode * QoreFile::readLine	(	bool	incl_eol,
		ExceptionSink *	xsink
	)

reads string data from the file up to and optionally including the terminating EOL characters (can be "\n", "\r" or "\r\n") and returns the string read

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

Parameters

incl_eol	if this parameter is true, then the EOL character(s) read will be written to the string, if false, then they are not
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 EOL characters (if any - if EOF is encountered then there may not be any) or 0 if there is an error or no data could be read. caller owns the reference count returned

See also: QoreFile::readUntil()

◆ readLine() [2/4]

DLLEXPORT QoreStringNode * QoreFile::readLine ( ExceptionSink * xsink )

reads string data from the file up to and including the terminating EOL characters (can be "\n", "\r" or "\r\n") and returns the string read with the EOL characters

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 EOL characters (if any - if EOF is encountered then there may not be any) or 0 if there is an error or no data could be read. caller owns the reference count returned

See also: QoreFile::readUntil()

◆ readLine() [3/4]

DLLEXPORT int QoreFile::readLine ( QoreString & str )

clears the string passed, then reads string data from the file up to and including the terminating EOL characters (can be "\n", "\r" or "\r\n"), returns 0 for no error, -1 for EOF, -2 for file not opened

Note: string data will be appended to the string with the assumption that the string's encoding is the same as the file's

Parameters

str	the string container that will have the line from the file written into

Returns: 0 for no error, -1 for EOF, -2 for file not opened

See also: QoreFile::readUntil()

◆ readLine() [4/4]

DLLEXPORT int QoreFile::readLine	(	QoreString &	str,
		bool	incl_eol
	)

clears the string passed, then reads string data from the file up to and optionally including the terminating EOL characters (can be "\n", "\r" or "\r\n"), returns 0 for no error, -1 for EOF, -2 for file not opened

Note: string data will be appended to the string with the assumption that the string's encoding is the same as the file's

Parameters

str	the string container that will have the line from the file written into
incl_eol	if this parameter is true, then the EOL character(s) read will be written to the string, if false, then they are not

Returns: 0 for no error, -1 for EOF, -2 for file not opened

See also: QoreFile::readUntil()

◆ readu1()

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()

◆ readu2()

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()

◆ readu2LSB()

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()

◆ readu4()

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()

◆ readu4LSB()

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()

◆ readUntil() [1/3]

DLLEXPORT int QoreFile::readUntil	(	char	byte,
		QoreString &	str,
		bool	incl_bytes = `true`
	)

clears the string passed, then reads string data from the file up to a terminating byte value, returns 0 for no error, -1 for EOF, -2 for file not opened

Note: string data will be appended to the string with the assumption that the string's encoding is the same as the file's

Parameters

byte	the end of line byte
str	the string to write the line read into
incl_bytes	if this parameter is true, then the EOL character(s) read will be written to the string, if false, then they are not

Returns: 0 for no error, -1 for EOF, -2 for file not opened

See also: QoreFile::readLine()

◆ readUntil() [2/3]

DLLEXPORT QoreStringNode * QoreFile::readUntil	(	const char *	bytes,
		bool	incl_bytes,
		ExceptionSink *	xsink
	)

reads string data from the file up to and optionally including the terminating EOL characters passed as an argument and returns the string read

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

Parameters

bytes	the end of line characters that separate lines
incl_bytes	if this parameter is true, then the EOL character(s) read will be written to the string, if false, then they are not
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 EOL characters (if any - if EOF is encountered then there may not be any) or 0 if there is an error or no data could be read. caller owns the reference count returned

See also: QoreFile::readLine()

◆ readUntil() [3/3]

DLLEXPORT int QoreFile::readUntil	(	const char *	bytes,
		QoreString &	str,
		bool	incl_bytes = `true`
	)

clears the string passed, then reads string data from the file up to the given byte string, returns 0 for no error, -1 for EOF, -2 for file not opened

Parameters

bytes	the byte string giving the end of the data to read
str	the string where the data read will be stored in (this string must already be tagged with the QoreFile's encoding)
incl_bytes	include "bytes" in the string

Note: string data will be appended to the string with the assumption that the string's encoding is the same as the file's

Returns: 0 for no error, -1 for EOF, -2 for file not opened

See also: QoreFile::readLine()

◆ redirect()

DLLEXPORT int QoreFile::redirect	(	QoreFile &	file,
		ExceptionSink *	xsink
	)

redirects the current file (this) to the argument

Since: Qore 0.9

◆ setPos()

DLLEXPORT size_t QoreFile::setPos ( size_t pos )

sets the absolute file position to "pos"

Parameters

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

Referenced by FileInputStream::peek().

◆ stat()

DLLEXPORT QoreListNode * QoreFile::stat ( ExceptionSink * xsink ) const

returns a QoreListNode with file status information

Parameters

xsink if an error occurs, the Qore-language exception info will be added here

Returns: a QoreListNode with file status information

◆ statvfs()

DLLEXPORT QoreHashNode * QoreFile::statvfs ( ExceptionSink * xsink ) const

returns a QoreHashNode with filesystem status information

Parameters

xsink if an error occurs, the Qore-language exception info will be added here

Returns: a QoreHashNode with filesystem status information

◆ write() [1/3]

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)

◆ write() [2/3]

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)

Referenced by FileOutputStream::write().

◆ write() [3/3]

DLLEXPORT int QoreFile::write	(	const void *	data,
		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)

◆ writei1()

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)

◆ writei2()

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()

◆ writei2LSB()

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()

◆ writei4()

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()

◆ writei4LSB()

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()

◆ writei8()

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()

◆ writei8LSB()

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()

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

/tmp/qore/include/qore/QoreFile.h

Public Member Methods

Private Member Methods

Private Attributes

Detailed Description

Member Function Documentation

◆ close()

◆ detachFd()

◆ getchar() [1/2]

◆ getchar() [2/2]

◆ getFD()

◆ getPollableDescriptor()

◆ getPos() [1/2]

◆ getPos() [2/2]

◆ hstat()

◆ isDataAvailable()

◆ open()

◆ open2()

◆ read() [1/4]

◆ read() [2/4]

◆ read() [3/4]

◆ read() [4/4]

◆ readBinary() [1/3]

◆ readBinary() [2/3]

◆ readBinary() [3/3]

◆ readi1()

◆ readi2()

◆ readi2LSB()

◆ readi4()

◆ readi4LSB()

◆ readi8()

◆ readi8LSB()

◆ readLine() [1/4]

◆ readLine() [2/4]

◆ readLine() [3/4]

◆ readLine() [4/4]

◆ readu1()

◆ readu2()

◆ readu2LSB()

◆ readu4()

◆ readu4LSB()

◆ readUntil() [1/3]

◆ readUntil() [2/3]

◆ readUntil() [3/3]

◆ redirect()

◆ setPos()

◆ stat()

◆ statvfs()

◆ write() [1/3]

◆ write() [2/3]

◆ write() [3/3]

◆ writei1()

◆ writei2()

◆ writei2LSB()

◆ writei4()

◆ writei4LSB()

◆ writei8()

◆ writei8LSB()