Qore::ReadOnlyFile Class Reference

The ReadOnlyFile class allows Qore programs to read existing files. More...

#include <QC_ReadOnlyFile.dox.h>

Inheritance diagram for Qore::ReadOnlyFile:

Public Member Methods
int	close ()
	Closes the ReadOnlyFile object. More...
	constructor (string path, *string encoding)
	Creates the ReadOnlyFile object. More...
	copy ()
	Creates a new ReadOnlyFile object with the same character encoding specification as the original, otherwise no other information is copied. More...
	destructor ()
	Closes the ReadOnlyFile if it is open and destroys the ReadOnlyFile object. More...
string	getEncoding ()
	Returns the character encoding for the ReadOnlyFile. More...
*string	getFileName ()
	returns the file path/name used to open the file if the file is open, otherwise NOTHING More...
int	getPos ()
	Returns the current file position as an integer giving the offset in bytes from the beginning of the file (starting from zero) More...
*string	getchar ()
	Reads one character from the file and returns it as a string; returns NOTHING if no data can be read from the file. More...
hash< StatInfo >	hstat ()
	Returns a StatInfo hash about the file's status or throws an exception if any errors occur. More...
bool	isDataAvailable (timeout timeout_ms=0)
	Returns True if there is data available for reading from the file within the timeout period. More...
bool	isOpen ()
	returns True if the File is open, False if not More...
bool	isTty ()
	returns True if the File is connected to a terminal device, False if not More...
nothing	open (string path, *string encoding)
	Opens a file in a particular mode; throws an exception on failure. More...
*string	read (softint size, timeout timeout_ms=-1)
	Reads a certain number of characters from the ReadOnlyFile within an optional timeout period and returns a string of the data read or NOTHING if no data can be read. More...
*binary	readBinary (softint size, timeout timeout_ms=-1)
	Reads a certain number of bytes from the file within an optional timeout period and returns a binary object of the data read or NOTHING if no data can be read. More...
*string	readLine (bool incl_eol=True, *string eol)
	Reads until an EOL marker is found and returns the string read or NOTHING if no data can be read. More...
*int	readi1 ()
	Reads a 1-byte signed integer from the file in binary format or NOTHING if no data can be read. More...
*int	readi2 ()
	Reads a 2-byte (16 bit) signed integer from the file in binary big-endian format or NOTHING if no data can be read. More...
*int	readi2LSB ()
	Reads a 2-byte (16 bit) signed integer from the file in binary little-endian format or NOTHING if no data can be read. More...
*int	readi4 ()
	Reads a 4-byte (32 bit) signed integer from the file in binary big-endian format or NOTHING if no data can be read. More...
*int	readi4LSB ()
	Reads a 4-byte (32 bit) signed integer from the file in binary little-endian format or NOTHING if no data can be read. More...
*int	readi8 ()
	Reads an 8-byte (64 bit) signed integer from the file in binary big-endian format or NOTHING if no data can be read. More...
*int	readi8LSB ()
	Reads an 8-byte (64 bit) signed integer from the file in binary little-endian format or NOTHING if no data can be read. More...
*int	readu1 ()
	Reads a 1-byte unsigned integer from the ReadOnlyFile in binary format or NOTHING if no data can be read. More...
*int	readu2 ()
	Reads a 2-byte (16 bit) unsigned integer from the ReadOnlyFile in binary big-endian format or NOTHING if no data can be read. More...
*int	readu2LSB ()
	Reads a 2-byte (16 bit) unsigned integer from the file in binary little-endian format or NOTHING if no data can be read. More...
*int	readu4 ()
	Reads a 4-byte (32 bit) unsigned integer from the file in big-endian format or NOTHING if no data can be read. More...
*int	readu4LSB ()
	Reads a 4-byte (32 bit) unsigned integer from the file in binary little-endian format or NOTHING if no data can be read. More...
nothing	setEncoding (*string encoding)
	Sets the character encoding for the ReadOnlyFile; if called with no argument, the default encoding is set. More...
nothing	setEventQueue (Queue queue, auto arg, *bool with_data)
	Sets a Queue object to receive file events. More...
nothing	setEventQueue ()
	Removes any Queue object from the ReadOnlyFile object so that file events are no longer added to the Queue. More...
int	setPos (int pos=0)
	Sets the current file position (in bytes from the beginning of the file) More...
list< auto >	stat ()
	Returns a Stat List about the file's status or throws an exception if any errors occur. More...
hash< FilesystemInfo >	statvfs ()
	Returns a FilesystemInfo hash about the file's filesystem status or throws an exception if any errors occur. More...
Public Member Methods inherited from Qore::AbstractPollableIoObjectBase
	constructor ()
	Throws an exception; this class is not usable by Qore classes. More...
int	getPollableDescriptor ()
	Returns a pollable file / socket / I/O descriptor. More...
abstract int	getPollableDescriptor ()
	Returns a pollable file / socket / I/O descriptor. More...

Static Public Member Methods
static hash< StatInfo >	hlstat (string path)
	Returns a StatInfo hash about the file's status (does not follow symbolic links) or throws an exception if any errors occur. More...
static hash< StatInfo >	hstat (string path)
	Returns a StatInfo hash about the file's status (follows symbolic links) or throws an exception if any errors occur. More...
static list< auto >	lstat (string path)
	Returns a Stat List about the given path's status (does not follow symbolic links) or throws an exception if any errors occur. More...
static binary	readBinaryFile (string path, int max_file_len=-1)
	returns the contents of a binary file as a binary object More...
static string	readTextFile (string path, *string encoding, int max_file_len=-1)
	returns the contents of a text file as a string optionally tagged with the given character encoding More...
static list< auto >	stat (string path)
	Returns a Stat List about the file's status (follows symbolic links) or throws an exception if any errors occur. More...
static hash< FilesystemInfo >	statvfs (string path)
	Returns a FilesystemInfo hash about filesystem status of the given path; throws an exception if any errors occur. More...

Detailed Description

The ReadOnlyFile class allows Qore programs to read existing files.

Restrictions:

Qore::PO_NO_FILESYSTEM

Note

This class is not available with the PO_NO_FILESYSTEM parse option

ReadOnlyFile objects are opened with a specific character encoding, meaning that any string read from the file will be tagged with the file's character encoding. If no character encoding is specified, then the default character encoding is assumed for the file.

This class supports posting read events to a Queue. See I/O Event Handling for more information.

See also

file_events for a list of I/O events raised by this object

Since

Qore 0.8.6 this class was split from the Qore::File class and added as a base class of Qore::File

Member Function Documentation

close()

int Qore::ReadOnlyFile::close

(

)

Closes the ReadOnlyFile object.

Example:

if (f.close())
    printf("error closing file: %s\n", strerror(errno()));

Events:

EVENT_CHANNEL_CLOSED

Exceptions

ILLEGAL-EXPRESSION

this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

Returns

0 for success, -1 for an error (see errno() and strerror() for the error information)

constructor()

Qore::ReadOnlyFile::constructor	(	string	path,
		*string	encoding
	)

Creates the ReadOnlyFile object.

The constructor takes the file path and one optional argument that will set the default character encoding for the file (only affects reading string data) To open the file again with another file, call ReadOnlyFile::open(); the character encoding can also be set or changed by the ReadOnlyFile::open() or ReadOnlyFile::setEncoding() methods.

Example:

ReadOnlyFile f("/tmp/my-file.txt", "iso-8859-1");

Parameters

path	the path to open for reading
encoding	The character encoding for the ReadOnlyFile. Strings data read from the file will be tagged with this character encoding; if this argument is not given then the ReadOnlyFile will receive the default encoding

Exceptions

READONLYFILE-OPEN-ERROR	the given file cannot be opened for reading (arg will be assigned to the errno value)
ILLEGAL-EXPRESSION	ReadOnlyFile::constructor() cannot be called with a TTY target when %no-terminal-io is set

See also

ReadOnlyFile::open()

copy()

Qore::ReadOnlyFile::copy

(

)

Creates a new ReadOnlyFile object with the same character encoding specification as the original, otherwise no other information is copied.

Example:

ReadOnlyFile f1 = f.copy();

destructor()

Qore::ReadOnlyFile::destructor

(

)

Closes the ReadOnlyFile if it is open and destroys the ReadOnlyFile object.

Closes the ReadOnlyFile if it is open and destroys the ReadOnlyFile object

getchar()

*string Qore::ReadOnlyFile::getchar

(

)

Reads one character from the file and returns it as a string; returns NOTHING if no data can be read from the file.

Multi-byte characters are also read; use ReadOnlyFile::readu1() or ReadOnlyFile::readi1() to read a single byte from a file regardless of the ReadOnlyFile's character encoding.

Example:

*string str = f.getchar();

Returns

the single character read from the file or NOTHING if no data can be read from the ReadOnlyFile

Exceptions

FILE-READ-ERROR	file is not open
FILE-GETCHAR-ERROR	invalid multi-byte character read or EOF received while reading a multi-byte character
ILLEGAL-EXPRESSION	this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

getEncoding()

string Qore::ReadOnlyFile::getEncoding

(

)

Returns the character encoding for the ReadOnlyFile.

Code Flags:

CONSTANT

Example:

string encoding = f.getEncoding();

Returns

the character encoding for the ReadOnlyFile

getFileName()

*string Qore::ReadOnlyFile::getFileName

(

)

returns the file path/name used to open the file if the file is open, otherwise NOTHING

Code Flags:

CONSTANT

Example:

*string fn = f.getFileName();

Returns

the file path/name used to open the file if the file is open, otherwise NOTHING

Since

Qore 0.8.6

getPos()

int Qore::ReadOnlyFile::getPos

(

)

Returns the current file position as an integer giving the offset in bytes from the beginning of the file (starting from zero)

Code Flags:

RET_VALUE_ONLY

Example:

int pos = f.getPos();

Returns

the current file position as an integer giving the offset in bytes from the beginning of the file (starting from zero)

Exceptions

ILLEGAL-EXPRESSION

this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

See also

ReadOnlyFile::setPos()

hlstat()

static hash< StatInfo > Qore::ReadOnlyFile::hlstat ( string  path )

static

Returns a StatInfo hash about the file's status (does not follow symbolic links) or throws an exception if any errors occur.

Does not follow symbolic links, but rather returns filesystem information for symbolic links. If any errors occur, a FILE-HSTAT-ERROR exception is thrown

Restrictions:

Qore::PO_NO_FILESYSTEM

Example:

hash<StatInfo> h = ReadOnlyFile::hstat(path);

Parameters

path	the file to stat()

Returns

a StatInfo hash about the file's status

Exceptions

FILE-HSTAT-ERROR

stat() call failed

See also

hstat() for a normal function returns NOTHING instead of throwing an exception when errors occur

File Stat Constants

Since

Qore 0.8.13 this method was moved from the File class (where it is still available due to public inheritance)

hstat() [1/2]

hash< StatInfo > Qore::ReadOnlyFile::hstat

(

)

Returns a StatInfo hash about the file's status or throws an exception if any errors occur.

If any errors occur, a FILE-HSTAT-ERROR exception is thrown

Example:

hash<StatInfo> h = file.hstat();

Returns

a StatInfo hash about the file's status

Exceptions

FILE-HSTAT-ERROR	stat() call failed or file not open
ILLEGAL-EXPRESSION	this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

See also

• File::stat()
• File Stat Constants

hstat() [2/2]

static hash< StatInfo > Qore::ReadOnlyFile::hstat ( string  path )

static

Returns a StatInfo hash about the file's status (follows symbolic links) or throws an exception if any errors occur.

This method will follow symbolic links and return information about the target. If any errors occur, a FILE-HSTAT-ERROR exception is thrown

Restrictions:

Qore::PO_NO_FILESYSTEM

Example:

hash<StatInfo> h = ReadOnlyFile::hstat(path);

Parameters

path	the file to stat()

Returns

a StatInfo hash about the file's status

Exceptions

FILE-HSTAT-ERROR

stat() call failed

See also

hstat() for a normal function returns NOTHING instead of throwing an exception when errors occur

File Stat Constants

Since

Qore 0.8.13 this method was moved from the File class (where it is still available due to public inheritance)

isDataAvailable()

bool Qore::ReadOnlyFile::isDataAvailable

(

timeout

timeout_ms = 0

)

Returns True if there is data available for reading from the file within the timeout period.

With a timeout of zero (the default if no timeout value is passed), this method can be used for non-blocking polling the file for data. Like all Qore functions and methods taking timeout values, a relative date/time value may be passed instead of an integer to make the timeout units clear (ex: 25ms).

Code Flags:

RET_VALUE_ONLY

Example:

if (!isDataAvailable(30s))
    return;

Parameters

timeout_ms

An optional timeout in milliseconds (1/1000 second); relative date/time values can be given instead of an integer in milliseconds to make the source more readable; ex: 20s

Returns

True if data becomes available for reading from the file within the timeout period, False if not

Exceptions

ILLEGAL-EXPRESSION

this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

isOpen()

bool Qore::ReadOnlyFile::isOpen

(

)

returns True if the File is open, False if not

Returns

True if the File is open, False if not

Code Flags:

CONSTANT

Example:

bool b = file.isOpen();

isTty()

bool Qore::ReadOnlyFile::isTty

(

)

returns True if the File is connected to a terminal device, False if not

Code Flags:

CONSTANT

Example:

bool b = file.isTty();

Returns

True if the File is connected to a terminal device, False if not

Since

Qore 0.8.6

lstat()

static list< auto > Qore::ReadOnlyFile::lstat ( string  path )

static

Returns a Stat List about the given path's status (does not follow symbolic links) or throws an exception if any errors occur.

Does not follow symbolic links, but rather returns filesystem information for symbolic links. If any errors occur, a FILE-LSTAT-ERROR exception is thrown

Restrictions:

Qore::PO_NO_FILESYSTEM

Example:

int mode = ReadOnlyFile::lstat(path)[2];

Parameters

path	the file to stat()

Returns

a list of file status values for the given file

Exceptions

FILE-LSTAT-ERROR

stat() call failed

See also

lstat() for a similar function that does not throw exceptions when errors occur, but rather returns NOTHING

File Stat Constants

Since

Qore 0.8.13 this method was moved from the File class (where it is still available due to public inheritance)

open()

nothing Qore::ReadOnlyFile::open	(	string	path,
		*string	encoding
	)

Opens a file in a particular mode; throws an exception on failure.

Opens the file in the mode given; if the ReadOnlyFile was previously open, it is closed first. Optionally the ReadOnlyFile's default character encoding can be specified.

Note that if no encoding is specified, the ReadOnlyFile will be tagged with the character encoding set in the ReadOnlyFile's constructor. Any string data written to the ReadOnlyFile will be converted to the ReadOnlyFile's encoding, and any string data read from the ReadOnlyFile will be automatically tagged with the ReadOnlyFile's encoding.

If an error occurs, a READONLYFILE-OPEN-ERROR exception is thrown.

Example:

try {
    f.open(fn, "iso-8859-1");
} catch (hash<ExceptionInfo> ex) {
    printf("%s: %s: %s\n", fn, ex.err, ex.desc);
}

Events:

EVENT_OPEN_FILE, EVENT_FILE_OPENED

Parameters

path	the path to the file
encoding	the name of the character encoding for the ReadOnlyFile; if this argument is not given, the ReadOnlyFile will be tagged with the character encoding given in the constructor

Exceptions

READONLYFILE-OPEN-ERROR	an error occurred opening the file
ILLEGAL-EXPRESSION	this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

read()

*string Qore::ReadOnlyFile::read	(	softint	size,
		timeout	timeout_ms = -1
	)

Reads a certain number of characters from the ReadOnlyFile within an optional timeout period and returns a string of the data read or NOTHING if no data can be read.

Reads a certain amount of string data from the ReadOnlyFile; the size argument is required. To read binary data, use the ReadOnlyFile::readBinary() method.

Note that the amount of data read from the file may be less than the size given, for example if the file does not contain enough data to fulfill the request. In this case, only the data available in the file is returned.

An optional timeout period in milliseconds can be passed as well (or a relative date/time value may be passed instead of an integer to make the timeout units clear; ex: 25ms). If a timeout value is passed and the data cannot be read within the timeout period, then a READONLYFILE-READ-TIMEOUT exception is thrown. If no timeout value is passed or a negative value is given, then the call will never timeout until either the requested amount of data has been read from the ReadOnlyFile or an end-of-file condition has been reached.

Example:

*string data = f.read(-1); # read an entire text file into a variable

Events:

EVENT_DATA_READ

Parameters

size	the number of characters to read of the file, -1 will read the entire file
timeout_ms	a timeout period with a resolution of milliseconds (a relative date/time value; integer arguments will be assumed to be milliseconds); if not given or negative the call will never time out and will only return when the data has been read

Returns

the data read from the file, returned as a string tagged with the ReadOnlyFile's character encoding. NOTHING is returned if end-of-file is encountered, however, if data has been read before EOF, the data read will be returned and NOTHING (signifying EOF) will be returned on the next call to this method.

Exceptions

READONLYFILE-READ-PARAMETER-ERROR	zero size argument passed
FILE-READ-ERROR	file is not open
FILE-READ-TIMEOUT	timeout limit exceeded
ILLEGAL-EXPRESSION	this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

See also

ReadOnlyFile::readBinary()

Since

Qore 0.8.13 this method uses character semantics instead of byte semantics

readBinary()

*binary Qore::ReadOnlyFile::readBinary	(	softint	size,
		timeout	timeout_ms = -1
	)

Reads a certain number of bytes from the file within an optional timeout period and returns a binary object of the data read or NOTHING if no data can be read.

Reads a certain amount of string data from the file; the size argument is required. To read string data, use the ReadOnlyFile::read() method.

Note that the amount of data read from the file may be less than the size given, for example if the file does not contain enough data to fulfill the request. In this case, only the data available in the file is returned.

An optional timeout period in milliseconds can be passed as well (or a relative date/time value may be passed instead of an integer to make the timeout units clear; ex: 25ms). If a timeout value is passed and the data cannot be read within the timeout period, then a FILE-READ-TIMEOUT exception is thrown. If no timeout value is passed or a negative value is given, then the call will never timeout until either the requested amount of data has been read from the file or an end-of-file condition has been reached.

Events:

EVENT_DATA_READ

Example:

*binary data = f.readBinary(-1); # read an entire file into a variable

Parameters

size	the number of bytes to read of the file, -1 will read the entire file
timeout_ms	a timeout period with a resolution of milliseconds (a relative date/time value; integer arguments will be assumed to be milliseconds); if not given or negative the call will never time out and will only return when the data has been read

Returns

the data read from the file, returned as a binary object. NOTHING is returned if end-of-file is encountered, however, if data has been read before EOF, the data read will be returned and NOTHING (signifying EOF) will be returned on the next call to this method.

Exceptions

READONLYFILE-READ-BINARY-PARAMETER-ERROR	zero size argument passed
FILE-READ-ERROR	file is not open, or an I/O or other error occurred when reading the file
FILE-READ-TIMEOUT	timeout limit exceeded
ILLEGAL-EXPRESSION	this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

See also

ReadOnlyFile::read()

readBinaryFile()

static binary Qore::ReadOnlyFile::readBinaryFile ( string  path, int  max_file_len = -1  )

static

returns the contents of a binary file as a binary object

Restrictions:

Qore::PO_NO_FILESYSTEM

Example:

binary data = File::readBinaryFile(path);

Parameters

path	the path of the file to retrieve
max_file_len	the maximum size of the file returned; if the data on the filesystem exceeds this value, the data returned will be truncated up to this byte length

Returns

the contents of a binary file as a binary object

Exceptions

FILE-READ-ERROR

an I/O or other error occurred when reading the file

Since

• Qore 0.8.8 introduced this method
• Qore 0.8.12 changed the behavior of the method; either a binary object (possibly an empty binary object for an empty file) will be returned, or an exception will be raised
• Qore 0.9.3 added the max_file_len parameter

readi1()

*int Qore::ReadOnlyFile::readi1

(

)

Reads a 1-byte signed integer from the file in binary format or NOTHING if no data can be read.

Example:

*int i = f.readi1();

Events:

EVENT_DATA_READ

Returns

a 1-byte signed integer as read from the file in binary format or NOTHING if no data can be read

Exceptions

FILE-READ-ERROR	file is not open
ILLEGAL-EXPRESSION	this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

readi2()

*int Qore::ReadOnlyFile::readi2

(

)

Reads a 2-byte (16 bit) signed integer from the file in binary big-endian format or NOTHING if no data can be read.

Example:

*int i = f.readi2();

Events:

EVENT_DATA_READ

Returns

a 2-byte signed integer as read from the file in binary big-endian format or NOTHING if no data can be read

Exceptions

FILE-READ-ERROR	file is not open
ILLEGAL-EXPRESSION	this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

readi2LSB()

*int Qore::ReadOnlyFile::readi2LSB

(

)

Reads a 2-byte (16 bit) signed integer from the file in binary little-endian format or NOTHING if no data can be read.

Example:

*int i = f.readi2LSB();

Events:

EVENT_DATA_READ

Returns

a 2-byte signed integer as read from the file in binary little-endian format or NOTHING if no data can be read

Exceptions

FILE-READ-ERROR	file is not open
ILLEGAL-EXPRESSION	this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

readi4()

*int Qore::ReadOnlyFile::readi4

(

)

Reads a 4-byte (32 bit) signed integer from the file in binary big-endian format or NOTHING if no data can be read.

Example:

*int i = f.readi4();

Events:

EVENT_DATA_READ

Returns

a 4-byte signed integer as read from the file in binary big-endian format or NOTHING if no data can be read

Exceptions

FILE-READ-ERROR	file is not open
ILLEGAL-EXPRESSION	this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

readi4LSB()

*int Qore::ReadOnlyFile::readi4LSB

(

)

Reads a 4-byte (32 bit) signed integer from the file in binary little-endian format or NOTHING if no data can be read.

Example:

*int i = f.readi4LSB();

Events:

EVENT_DATA_READ

Returns

a 4-byte signed integer as read from the file in binary little-endian format or NOTHING if no data can be read

Exceptions

FILE-READ-ERROR	file is not open
ILLEGAL-EXPRESSION	this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

readi8()

*int Qore::ReadOnlyFile::readi8

(

)

Reads an 8-byte (64 bit) signed integer from the file in binary big-endian format or NOTHING if no data can be read.

Example:

*int i = f.readi8();

Events:

EVENT_DATA_READ

Returns

a 8-byte signed integer as read from the file in binary big-endian format or NOTHING if no data can be read

Exceptions

FILE-READ-ERROR	file is not open
ILLEGAL-EXPRESSION	this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

readi8LSB()

*int Qore::ReadOnlyFile::readi8LSB

(

)

Reads an 8-byte (64 bit) signed integer from the file in binary little-endian format or NOTHING if no data can be read.

Example:

*int i = f.readi8LSB();

Events:

EVENT_DATA_READ

Returns

an 8-byte signed integer as read from the file in binary little-endian format or NOTHING if no data can be read

Exceptions

FILE-READ-ERROR	file is not open
ILLEGAL-EXPRESSION	this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

readLine()

*string Qore::ReadOnlyFile::readLine	(	bool	incl_eol = True,
		*string	eol
	)

Reads until an EOL marker is found and returns the string read or NOTHING if no data can be read.

Any string returned will be tagged with the ReadOnlyFile's character encoding.

Example:

# remove EOL marker
while (exists (*string line = f.readLine(False))) {
    # print out the line just read
    printf("%s\n", line);
}

Events:

EVENT_DATA_READ

Parameters

incl_eol

if this argument is True, then the end of line characters read are included in the string returned

eol

the end of line character(s); if not given, then the end of line character(s) are detected automatically, and can be either "\n", "\r", or "\r\n" (the last one is only automatically detected when not connected to a terminal device in order to keep the I/O from stalling); if this string is passed and has a different character encoding from the File's, then it will be converted to the File's character encoding

Returns

The line read from the file. NOTHING is returned if end-of-file is encountered, however, if data has been read before EOF, the data read will be returned and NOTHING (signifying EOF) will be returned on the next call to this method. Any string returned will be tagged with the ReadOnlyFile's character encoding.

Exceptions

READONLYFILE-READLINE-ERROR	the file is not open
ILLEGAL-EXPRESSION	this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

See also

• Qore::FileLineIterator

readTextFile()

static string Qore::ReadOnlyFile::readTextFile ( string  path, *string  encoding, int  max_file_len = -1  )

static

returns the contents of a text file as a string optionally tagged with the given character encoding

Restrictions:

Qore::PO_NO_FILESYSTEM

Example:

string data = File::readTextFile(path);

Parameters

path	the path of the file to retrieve
encoding	the name of the character encoding for the string returned; if this argument is not given, then the default character encoding is assumed
max_file_len	the maximum size of the file returned; if the data on the filesystem exceeds this value, the data returned will be truncated up to this byte length

Returns

the contents of a text file as a string optionally tagged with the given character encoding or NOTHING if the file is empty or cannot be read

Exceptions

FILE-READ-ERROR

an I/O or other error occurred when reading the file

Since

• Qore 0.8.8 introduced this method
• Qore 0.8.12 changed the behavior of the method; either a string (possibly an empty string for an empty file) will be returned, or an exception will be raised
• Qore 0.9.3 added the max_file_len parameter

readu1()

*int Qore::ReadOnlyFile::readu1

(

)

Reads a 1-byte unsigned integer from the ReadOnlyFile in binary format or NOTHING if no data can be read.

Example:

*int i = f.readu1();

Events:

EVENT_DATA_READ

Returns

a 1-byte unsigned integer as read from the ReadOnlyFile in binary format or NOTHING if no data can be read

Exceptions

FILE-READ-ERROR	file is not open
ILLEGAL-EXPRESSION	this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

readu2()

*int Qore::ReadOnlyFile::readu2

(

)

Reads a 2-byte (16 bit) unsigned integer from the ReadOnlyFile in binary big-endian format or NOTHING if no data can be read.

Example:

*int i = f.readu2();

Events:

EVENT_DATA_READ

Returns

a 2-byte unsigned integer as read from the file in binary big-endian format or NOTHING if no data can be read

Exceptions

FILE-READ-ERROR	file is not open
ILLEGAL-EXPRESSION	this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

readu2LSB()

*int Qore::ReadOnlyFile::readu2LSB

(

)

Reads a 2-byte (16 bit) unsigned integer from the file in binary little-endian format or NOTHING if no data can be read.

Example:

*int i = f.readu2LSB();

Events:

EVENT_DATA_READ

Returns

a 2-byte unsigned integer as read from the file in binary little-endian format or NOTHING if no data can be read

Exceptions

FILE-READ-ERROR	file is not open
ILLEGAL-EXPRESSION	this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

readu4()

*int Qore::ReadOnlyFile::readu4

(

)

Reads a 4-byte (32 bit) unsigned integer from the file in big-endian format or NOTHING if no data can be read.

Example:

*int i = f.readu4();

Events:

EVENT_DATA_READ

Returns

a 4-byte unsigned integer as read from the file in binary big-endian format or NOTHING if no data can be read

Exceptions

FILE-READ-ERROR	file is not open
ILLEGAL-EXPRESSION	this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

readu4LSB()

*int Qore::ReadOnlyFile::readu4LSB

(

)

Reads a 4-byte (32 bit) unsigned integer from the file in binary little-endian format or NOTHING if no data can be read.

Example:

*int i = f.readu4LSB();

Events:

EVENT_DATA_READ

Returns

a 4-byte unsigned integer as read from the file in binary little-endian format or NOTHING if no data can be read

Exceptions

FILE-READ-ERROR	file is not open
ILLEGAL-EXPRESSION	this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

setEncoding()

nothing Qore::ReadOnlyFile::setEncoding

(

*string

encoding

)

Sets the character encoding for the ReadOnlyFile; if called with no argument, the default encoding is set.

Example:

f.setEncoding("ISO-8859-1");

Parameters

encoding

the character encoding for the file; if called with no argument, the default encoding is set

Exceptions

ILLEGAL-EXPRESSION

this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

setEventQueue() [1/2]

nothing Qore::ReadOnlyFile::setEventQueue

(

)

Removes any Queue object from the ReadOnlyFile object so that file events are no longer added to the Queue.

Example:

f.setEventQueue();

Exceptions

ILLEGAL-EXPRESSION

this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

See also

I/O Event Handling for more information

setEventQueue() [2/2]

nothing Qore::ReadOnlyFile::setEventQueue	(	Queue	queue,
		auto	arg,
		*bool	with_data
	)

Sets a Queue object to receive file events.

Example:

f.setEventQueue(queue);

Parameters

queue	the Queue object to receive file events; note that the Queue passed cannot have any maximum size set or a QUEUE-ERROR will be thrown
arg	an argument that will be included in each event hash in the arg key
with_data	if True, then the actual raw data transferred / received is also included in the events

Exceptions

ILLEGAL-EXPRESSION	this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set
QUEUE-ERROR	the Queue passed has a maximum size set

See also

I/O Event Handling for more information

Since

Qore 0.9.4 added the arg and with_data options

setPos()

int Qore::ReadOnlyFile::setPos

(

int

pos = 0

)

Sets the current file position (in bytes from the beginning of the file)

Example:

f.setPos(0); # go to the beginning of the file

Parameters

pos	the position in the file as offset from position 0

Returns

the new offset in the file, -1 for error

Exceptions

ILLEGAL-EXPRESSION

this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

See also

ReadOnlyFile::getPos()

stat() [1/2]

list< auto > Qore::ReadOnlyFile::stat

(

)

Returns a Stat List about the file's status or throws an exception if any errors occur.

If any errors occur, a FILE-STAT-ERROR exception is thrown.

Example:

int mode = file.stat()[2];

Returns

a list of file status values for the current file (must be open).

Exceptions

FILE-STAT-ERROR	stat() call failed or file not open
ILLEGAL-EXPRESSION	this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

See also

• File::hstat()
• File Stat Constants

stat() [2/2]

static list< auto > Qore::ReadOnlyFile::stat ( string  path )

static

Returns a Stat List about the file's status (follows symbolic links) or throws an exception if any errors occur.

This method will follow symbolic links and return information about the target. If any errors occur, a FILE-STAT-ERROR exception is thrown

Restrictions:

Qore::PO_NO_FILESYSTEM

Example:

int mode = ReadOnlyFile::stat(path)[2];

Parameters

path	the file to stat()

Returns

a list of file status values for the given file

Exceptions

FILE-STAT-ERROR

stat() call failed

See also

File Stat Constants

Since

Qore 0.8.13 this method was moved from the File class (where it is still available due to public inheritance)

statvfs() [1/2]

hash< FilesystemInfo > Qore::ReadOnlyFile::statvfs

(

)

Returns a FilesystemInfo hash about the file's filesystem status or throws an exception if any errors occur.

If any errors occur, a FILE-STATVFS-ERROR exception is thrown

Platform Availability:

Qore::Option::HAVE_STATVFS

Example:

hash<FilesystemInfo> h = file.statvfs();

Returns

a FilesystemInfo hash about the filesystem where the file resides

Exceptions

FILE-STATVFS-ERROR	statvfs() call failed or file is not open
MISSING-FEATURE-ERROR	this method is not supported on this platform; check Option::HAVE_STATVFS before calling this method to avoid this exception
ILLEGAL-EXPRESSION	this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

statvfs() [2/2]

static hash< FilesystemInfo > Qore::ReadOnlyFile::statvfs ( string  path )

static

Returns a FilesystemInfo hash about filesystem status of the given path; throws an exception if any errors occur.

If any errors occur, a FILE-STATVFS-ERROR exception is thrown

Platform Availability:

Qore::Option::HAVE_STATVFS

Restrictions:

Qore::PO_NO_FILESYSTEM

Example:

hash<FilesystemInfo> h = ReadOnlyFile::statvfs(path);

Parameters

path	the path to the filesystem to check

Returns

a FilesystemInfo hash about the filesystem where the file resides

Exceptions

FILE-STATVFS-ERROR	statvfs() call failed
MISSING-FEATURE-ERROR	this method is not supported on this platform; check Option::HAVE_STATVFS before calling this method to avoid this exception

Since

Qore 0.8.13 this method was moved from the File class (where it is still available due to public inheritance)