Qore::File Class Reference

The File class allows Qore programs to read, write, and create files. More...

#include <QC_File.dox.h>

Inheritance diagram for Qore::File:

Public Member Methods
nothing	chown (softint uid, softint gid=-1)
	Changes the user and group owners of the file on the filesystem (if the current user has sufficient permission to do so) More...
	constructor (*string encoding)
	Creates the File object. More...
	copy ()
	Creates a new File object with the same character encoding specification as the original, otherwise no other information is copied. More...
	destructor ()
	Closes the File if it is open and destroys the File object. More...
int	f_printf (string fmt,...)
	Writes a formatted string with hard field widths to the file. More...
int	f_printf ()
	This method variant does nothing except return a constant 0; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
int	f_vprintf (string fmt, any fmt_args)
	Writes a formatted string with hard field widths to a file, where the second argument is the formatting argument list. More...
int	f_vprintf ()
	This method variant does nothing except return a constant 0; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
string	getCharset ()
	Returns the character encoding for the File. More...
hash	getLockInfo ()
	Returns a hash of lock information. More...
nothing	getTerminalAttributes (TermIOS termios)
	Saves the current terminal attributes for the file in the TermIOS object passed; changes the object passed as an argument to reflect the terminal attributes as set for the File. More...
TermIOS	getTerminalAttributes ()
	Returns the current terminal attributes for the file as a TermIOS object returned as the return value. More...
int	lock (softint type=F_RDLCK, softint start=0, softint len=0, softint whence=SEEK_SET)
	Attempts to lock the file according to the arguments passed, does not block. More...
nothing	lockBlocking (softint type=F_RDLCK, softint start=0, softint len=0, softint whence=SEEK_SET)
	Attempts to lock the file according to the arguments passed, blocking. More...
int	open (string path, softint flags=O_RDONLY, softint mode=0666, *string encoding)
	Opens a File in a particular mode, returns an error code on failure. More...
nothing	open2 (string path, softint flags=O_RDONLY, softint mode=0666, *string encoding)
	Opens a file in a particular mode; throws an exception on failure. More...
int	print (string data)
	Writes string data to a file; string data is converted to the File's character encoding if necessary before writing. More...
int	printf (string fmt,...)
	Writes a formatted string with soft field widths to the file. More...
int	printf ()
	This method variant does nothing except return a constant 0; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
nothing	redirect (Qore::File file)
	redirects an existing file to another file More...
nothing	setCharset (*string encoding)
	Sets the character encoding for the file; if called with no argument, the default encoding is set. More...
nothing	setTerminalAttributes (softint action=TCSANOW, TermIOS termios)
	Sets the current terminal attributes for the File from the TermIOS object passed; does not change the object passed. More...
int	sync ()
	Flushes the file's buffer to disk. More...
int	vprintf (string fmt, any fmt_args)
	Writes a formatted string with soft field widths to a file, where the second argument is the formatting argument list. More...
int	vprintf ()
	This method variant does nothing except return a constant 0; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
int	write (binary data)
	Writes binary data to a file. More...
int	write (string data)
	Writes string data to a file; string data is converted to the File's character encoding if necessary before writing. More...
int	writei1 (int c)
	Writes a 1-byte integer to the file. More...
int	writei2 (int s)
	Writes a 2-byte (16 bit) integer to the file in binary big-endian format. More...
int	writei2LSB (int s)
	Writes a 2-byte (16 bit) integer to the file in binary little-endian format. More...
int	writei4 (int i)
	Writes a 4-byte (32 bit) integer to the file in binary big-endian format. More...
int	writei4LSB (int i)
	Writes a 4-byte (32 bit) integer to the file in binary little-endian format. More...
int	writei8 (int i)
	Writes an 8-byte (64 bit) integer to the file in binary big-endian format. More...
int	writei8LSB (int i)
	Writes an 8-byte (64 bit) integer to the file in binary little-endian format. More...
Public Member Methods inherited from Qore::ReadOnlyFile
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...
AbstractPollOperation	startPollRead (string path, bool to_string=True, int to_read=-1)
	Returns an AbstractPollOperation object to read a file from the filesystem. 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< PipeInfo >	getPipe ()
	Returns a hash with read and write files on an internal FIFO pipe. More...
Static Public Member Methods inherited from Qore::ReadOnlyFile
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 File class allows Qore programs to read, write, and create files.

Restrictions:

Qore::PO_NO_FILESYSTEM

Note

This class is not available with the PO_NO_FILESYSTEM parse option

File objects are created and/or opened with a specific character encoding, meaning that any string read from the file will be tagged with the file's character encoding, and any string data written to the file will be transparently converted to that character encoding before being written (if necessary). If no character encoding is specified, then the default character encoding is assumed for the file.

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

The events raised by this object are listed in the following table:

File Events

Name	Description
EVENT_DATA_READ	Raised when data is read from the file
EVENT_DATA_WRITTEN	Raised when data is written to the file
EVENT_CHANNEL_CLOSED	Raised when the file is closed
EVENT_DELETED	Raised when the object being monitored is deleted
EVENT_OPEN_FILE	Raised right before an attempt to open a file is made
EVENT_FILE_OPENED	Raised when the file has been successfully opened

Member Function Documentation

chown()

nothing Qore::File::chown	(	softint	uid,
		softint	gid = -1
	)

Changes the user and group owners of the file on the filesystem (if the current user has sufficient permission to do so)

Platform Availability:

Qore::Option::HAVE_UNIX_FILEMGT

Example:

f.chown(0, 0);

Parameters

uid	The user id of the user to change to; -1 means do not change uid
gid	The group id of the user to change to; -1 means do not change gid

Exceptions

FILE-CHOWN-ERROR	File is not open or the chown operation failed
MISSING-FEATURE-ERROR	this method is not supported on this platform; check Option::HAVE_UNIX_FILEMGT 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

constructor()

Qore::File::constructor

(

*string

encoding

)

Creates the File object.

It accepts one optional argument that will set the default character encoding for the file (only affects reading and writing string data) To open the file, call File::open() or File::open2(); the character encoding can also be set or changed by the File::open(), File::open2(), or File::setEncoding() methods.

Example:

File f();
f.open2("/tmp/my-file.txt");

Parameters

encoding

The character encoding for the File. Any strings written to the File will be converted to this character encoding if necessary; if this argument is not given then the File will receive the default encoding

Exceptions

ILLEGAL-EXPRESSION

File::constructor() cannot be called with a TTY target when %no-terminal-io is set

See also

File::open(), File::open2()

copy()

Qore::File::copy

(

)

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

Example:

File f1 = f.copy();

destructor()

Qore::File::destructor

(

)

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

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

f_printf() [1/2]

int Qore::File::f_printf

(

)

This method variant does nothing except return a constant 0; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:

RUNTIME_NOOP

Returns

a constant 0

f_printf() [2/2]

int Qore::File::f_printf	(	string	fmt,
			...
	)

Writes a formatted string with hard field widths to the file.

This method does not allow arguments to overrun field width specifiers in the format string.

Example:

f.f_printf("%5s\n", "hello there"); # outputs "hello\n", enforcing the field width

Events:

EVENT_DATA_WRITTEN

Parameters

fmt	the format string; see String Formatting for more information about the format string

Returns

the number of bytes written

Exceptions

FILE-WRITE-ERROR	File is not open or an I/O error occurred writing data to 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

See also

File::printf() for a similar method that does not enforce field widths

Since

Qore 0.8.7 this method throws exceptions on I/O errors to avoid silent write errors in Qore code

f_vprintf() [1/2]

int Qore::File::f_vprintf

(

)

This method variant does nothing except return a constant 0; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:

RUNTIME_NOOP

Returns

a constant 0

f_vprintf() [2/2]

int Qore::File::f_vprintf	(	string	fmt,
		any	fmt_args
	)

Writes a formatted string with hard field widths to a file, where the second argument is the formatting argument list.

This method will not allow arguments to overrun field width specifiers in the format string.

Example:

f.f_vprintf("%5s: %d\n", ("hello there", 2)); # outputs "hello: 2\n", enforcing the field width

Events:

EVENT_DATA_WRITTEN

Parameters

fmt	the format string; see String Formatting for more information about the format string
fmt_args	the single argument or list of arguments that will be used as the argument list or the format string. If a single argument is passed instead of a list, it will be used as the first argument as if a list were passed

Returns

the number of bytes written

Exceptions

FILE-WRITE-ERROR	File is not open or an I/O error occurred writing data to 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

See also

File::vprintf() for a similar method that does not enforce field widths

Since

Qore 0.8.7 this method throws exceptions on I/O errors to avoid silent write errors in Qore code

getCharset()

string Qore::File::getCharset

(

)

Returns the character encoding for the File.

Code Flags:

CONSTANT

A method synonym for Qore::ReadOnlyFile::getEncoding(), kept for backwards-compatibility

Returns

the character encoding for the File

getLockInfo()

hash Qore::File::getLockInfo

(

)

Returns a hash of lock information.

Platform Availability:

Qore::Option::HAVE_FILE_LOCKING

Code Flags:

RET_VALUE_ONLY

Example:

hash hash = f.getLockInfo();

Returns

a hash with the following keys:

• start: starting byte of the lock
• len: the length in bytes of the locked region
• pid: the PID of the process holding the lock
• type: see File Locking Constants; if no lock is set on the file, the key type has the value F_UNLCK.
• whence: always returned as SEEK_SET when the call is successful

Exceptions

FILE-LOCK-ERROR	File is not open or the internal fcntl operation failed
MISSING-FEATURE-ERROR	this exception is thrown when the method is not available on the runtime platform; for maximum portability, check the constant Qore::Option::HAVE_FILE_LOCKING before calling this function.
ILLEGAL-EXPRESSION	this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

getPipe()

static hash< PipeInfo > Qore::File::getPipe ( )

static

Returns a hash with read and write files on an internal FIFO pipe.

Returns

a hash with read and write files on an internal FIFO pipe

Note

the files returned in the return value are considered "special" files that cannot be reopened

Since

Qore 1.12

getTerminalAttributes() [1/2]

TermIOS Qore::File::getTerminalAttributes

(

)

Returns the current terminal attributes for the file as a TermIOS object returned as the return value.

Platform Availability:

Qore::Option::HAVE_TERMIOS

Example:

TermIOS termios = stdin.getTerminalAttributes();

Returns

the current terminal attributes for the File

Exceptions

FILE-OPERATION-ERROR	the File is not open
TERMIOS-GET-ERROR	error reading terminal attributes from the file descriptor (ex: not a TTY)
MISSING-FEATURE-ERROR	this method is not supported on this platform; check Option::HAVE_TERMIOS 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

Since

Qore 0.8.7

getTerminalAttributes() [2/2]

nothing Qore::File::getTerminalAttributes

(

TermIOS

termios

)

Saves the current terminal attributes for the file in the TermIOS object passed; changes the object passed as an argument to reflect the terminal attributes as set for the File.

Do not pass a reference to the TermIOS object; pass the object itself as an argument.

Platform Availability:

Qore::Option::HAVE_TERMIOS

Example:

TermIOS termios();
stdin.getTerminalAttributes(termios);

Parameters

termios

The method writes the current terminal attributes for the file to the object passed

Exceptions

FILE-OPERATION-ERROR	the File is not open
TERMIOS-GET-ERROR	error reading terminal attributes from the file descriptor (ex: not a TTY)
MISSING-FEATURE-ERROR	this method is not supported on this platform; check Option::HAVE_TERMIOS 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

lock()

int Qore::File::lock	(	softint	type = F_RDLCK,
		softint	start = 0,
		softint	len = 0,
		softint	whence = SEEK_SET
	)

Attempts to lock the file according to the arguments passed, does not block.

Locks or unlocks a portion of the file or the entire file, for reading or writing, non-blocking. The file must be opened in the appropriate mode before this call or the call will fail with an exception.

Platform Availability:

Qore::Option::HAVE_FILE_LOCKING

Example:

# lock the entire file exclusively
f.lock(F_WRLCK);
 
# lock a section of the file for reading, start byte 512, 2K range
f.lock(F_RDLCK, 512, 2048);
 
# release all locks
f.lock(F_UNLCK);

Parameters

type	Type of lock (or unlock); see File Locking Constants
start	Start byte for lock, 0 is the default (start of file)
len	Length in bytes for range to lock, 0 is the default (rest of file)
whence	Indicates how the relative offset of the file should be calculated for the lock; see File Seek Constants

Returns

0 for success, EACCES if the lock would block (only in the case that the lock would block is no exception thrown and EACCES returned)

Exceptions

FILE-LOCK-ERROR	File is not open, lock length is negative, or the fcntl operation failed
MISSING-FEATURE-ERROR	this exception is thrown when the method is not available on the runtime platform; for maximum portability, check the constant Qore::Option::HAVE_FILE_LOCKING before calling this function.
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::lockBlocking() for a blocking version of this method

lockBlocking()

nothing Qore::File::lockBlocking	(	softint	type = F_RDLCK,
		softint	start = 0,
		softint	len = 0,
		softint	whence = SEEK_SET
	)

Attempts to lock the file according to the arguments passed, blocking.

Locks or unlocks a portion of the file or the entire file, for reading or writing, blocking. The file must be opened in the appropriate mode before this call or the call will fail with an exception.

Platform Availability:

Qore::Option::HAVE_FILE_LOCKING

Example:

# lock the entire file exclusively
f.lockBlocking(F_WRLCK);
 
# lock a section of the file for reading, start byte 512, 2K range
f.lockBlocking(F_RDLCK, 512, 2048);
 
# release all locks
f.lockBlocking(F_UNLCK);

Parameters

type	Type of lock (or unlock); see File Locking Constants
start	Start byte for lock, 0 is the default (start of file)
len	Length in bytes for range to lock, 0 is the default (rest of file)
whence	Indicates how the relative offset of the file should be calculated for the lock; see File Seek Constants

Exceptions

FILE-LOCK-ERROR	File is not open, lock length is negative, or the fcntl operation failed
MISSING-FEATURE-ERROR	this exception is thrown when the method is not available on the runtime platform; for maximum portability, check the constant Qore::Option::HAVE_FILE_LOCKING before calling this function.
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::lockBlocking() for a blocking version of this method

open()

int Qore::File::open	(	string	path,
		softint	flags = O_RDONLY,
		softint	mode = 0666,
		*string	encoding
	)

Opens a File in a particular mode, returns an error code on failure.

Opens the File in the mode given; if the File was previously open, it is closed first. Additionally, the file permissions can be given if the file is to be created, and optionally the File's character encoding can be specified.

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

Example:

# open a file for writing, truncate data if already exists, create the file if doesn't exist
# set 0644 permissions, and convert all string data to ISO-8859-1 encoding
if (f.open(fn, O_CREAT | O_TRUNC | O_WRONLY, 0644, "ISO-8859-1"))
    printf("%s: %s\n", fn, strerror(errno()));

Events:

EVENT_OPEN_FILE, EVENT_FILE_OPENED

Parameters

path	the path to the file
flags	flags that determine the way the file is accessed, see File Open Constants for more information; if this argument is not given, O_RDONLY will be used as the default value.
mode	permission bits for when the file is to be created (default: 0666)
encoding	the name of the character encoding for the File; if this argument is not given, the file will be tagged with the character encoding given in the constructor

Returns

0 = no error, -1 = see errno() and strerror() for the error message

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

File::open2() for a version of this method that throws an exception when errors occur opening the file

open2()

nothing Qore::File::open2	(	string	path,
		softint	flags = O_RDONLY,
		softint	mode = 0666,
		*string	encoding
	)

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

Opens the file in the mode given; if the File was previously open, it is closed first. Additionally, the file permissions can be given if the file is to be created, and optionally the File's default character encoding can be specified.

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

If an error occurs, a FILE-OPEN2-ERROR exception is thrown. For a version of this method that returns an error code, see File::open().

Example:

# open a file for writing, truncate data if already exists, create the file if doesn't exist
# set 0644 permissions, and convert all string data to ISO-8859-1 encoding
try {
    f.open2(fn, O_CREAT | O_TRUNC | O_WRONLY, 0644, "ISO-8859-1");
}
catch (hash 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
flags	flags that determine the way the file is accessed, see File Open Constants for more information; if this argument is not given, O_RDONLY will be used as the default value.
mode	permission bits for when the file is to be created (default: 0666)
encoding	the name of the character encoding for the File; if this argument is not given, the File will be tagged with the character encoding given in the constructor

Exceptions

FILE-OPEN2-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

See also

File::open() for a version of this method that returns an error code instead of throwing an exception when errors occur opening the File

print()

int Qore::File::print

(

string

data

)

Writes string data to a file; string data is converted to the File's character encoding if necessary before writing.

Example:

f.print(data);

Events:

EVENT_DATA_WRITTEN

Parameters

data	the data to be written to the file; string data is converted to the File's character encoding if necessary before writing

Returns

the number of bytes written

Exceptions

FILE-WRITE-ERROR	File is not open or an I/O error occurred writing data to the File
ENCODING-CONVERSION-ERROR	error converting from the string's character encoding to the File's character encoding
ILLEGAL-EXPRESSION	this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

Note

this method is equivalent to File::write(string)

Since

Qore 0.8.7 this method throws exceptions on I/O errors to avoid silent write errors in Qore code

printf() [1/2]

int Qore::File::printf

(

)

This method variant does nothing except return a constant 0; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:

RUNTIME_NOOP

Returns

a constant 0

printf() [2/2]

int Qore::File::printf	(	string	fmt,
			...
	)

Writes a formatted string with soft field widths to the file.

This method will allow arguments to overrun field width specifiers in the format string.

Example:

f.printf("%5s\n", "hello there"); # outputs "hello there\n", exceeding field width

Events:

EVENT_DATA_WRITTEN

Parameters

fmt	the format string; see String Formatting for more information about the format string

Returns

the number of bytes written

Exceptions

FILE-WRITE-ERROR	File is not open or an I/O error occurred writing data to 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

See also

File::f_printf() for a similar method that enforces field widths

Since

Qore 0.8.7 this method throws exceptions on I/O errors to avoid silent write errors in Qore code

redirect()

nothing Qore::File::redirect

(

Qore::File

file

)

redirects an existing file to another file

Example:

File my_file("/tmp/my_stderr.txt", O_CREAT|O_TRUNC|O_WRONLY);
stderr.redirect(my_file);

Parameters

file	the file that the current object will be redirected to

Exceptions

FILE-REDIRECT-ERROR	the underlying call to dup2() failed
ILLEGAL-EXPRESSION	this exception is only thrown if called on or with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

Note

Once this method has been successfully executed, the file descriptor of the current object mirrors all operations of the argument's file descriptor and vice-versa, however the internal state and file path information is not kept synchronized between the linked objects in Qore, which must be taken into consideration when performing operations on objects linked through calls to this method.

Since

Qore 0.9

setCharset()

nothing Qore::File::setCharset

(

*string

encoding

)

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

A method synonym for Qore::ReadOnlyFile::setEncoding(), kept for backwards-compatibility

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

setTerminalAttributes()

nothing Qore::File::setTerminalAttributes	(	softint	action = TCSANOW,
		TermIOS	termios
	)

Sets the current terminal attributes for the File from the TermIOS object passed; does not change the object passed.

Platform Availability:

Qore::Option::HAVE_TERMIOS

Example:

TermIOS termios();
stdin.getTerminalAttributes(termios);
TermIOS orig = termios.copy();
on_exit
    stdin.setTerminalAttributes(TCSADRAIN, orig);
 
int lflag = termios.getLFlag();
lflag &= ~ICANON;
lflag &= ~ECHO;
lflag &= ~ISIG;
termios.setLFlag(lflag);
termios.setCC(VMIN, 1);
termios.setCC(VTIME, 0);
stdin.setTerminalAttributes(TCSADRAIN, termios);

Parameters

action	a binary or'ed value of the following actions: TCSANOW: the change occurs immediately TCSADRAIN: the change occurs after all output written to the File has been transmitted to the terminal TCSAFLUSH: the change occurs after all output written to the File has been transmitted to the terminal TCSASOFT: the values of the c_cflag, c_ispeed, and c_ospeed fields are ignored
termios	the TermIOS to use

Exceptions

FILE-OPERATION-ERROR	the File is not open
TERMIOS-SET-ERROR	error setting terminal attributes on the file descriptor
MISSING-FEATURE-ERROR	this method is not supported on this platform; check Option::HAVE_TERMIOS 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

sync()

int Qore::File::sync

(

)

Flushes the file's buffer to disk.

Example:

if (f.sync())
    printf("error in File::sync(): %s\n", strerror(errno()));

Returns

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

Exceptions

ILLEGAL-EXPRESSION

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

vprintf() [1/2]

int Qore::File::vprintf

(

)

This method variant does nothing except return a constant 0; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:

RUNTIME_NOOP

Returns

a constant 0

vprintf() [2/2]

int Qore::File::vprintf	(	string	fmt,
		any	fmt_args
	)

Writes a formatted string with soft field widths to a file, where the second argument is the formatting argument list.

This method will allow arguments to overrun field width specifiers in the format string.

Example:

f.vprintf("%5s: %d\n", ("hello there", 2)); # outputs "hello there: 2\n", exceeding field width

Events:

EVENT_DATA_WRITTEN

Parameters

fmt	the format string; see String Formatting for more information about the format string
fmt_args	the single argument or list of arguments that will be used as the argument list or the format string. If a single argument is passed instead of a list, it will be used as the first argument as if a list were passed

Returns

the number of bytes written

Exceptions

FILE-WRITE-ERROR	File is not open or an I/O error occurred writing data to 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

See also

File::f_vprintf() for a similar method that enforces field widths

Since

Qore 0.8.7 this method throws exceptions on I/O errors to avoid silent write errors in Qore code

write() [1/2]

int Qore::File::write

(

binary

data

)

Writes binary data to a file.

Example:

f.write(data);

Events:

EVENT_DATA_WRITTEN

Parameters

data	the data to be written to the file

Returns

the number of bytes written

Exceptions

FILE-WRITE-ERROR	File is not open or an I/O error occurred writing data to 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

Since

Qore 0.8.7 this method throws exceptions on I/O errors to avoid silent write errors in Qore code

write() [2/2]

int Qore::File::write

(

string

data

)

Writes string data to a file; string data is converted to the File's character encoding if necessary before writing.

Example:

f.write(data);

Events:

EVENT_DATA_WRITTEN

Parameters

data	the data to be written to the file; string data is converted to the File's character encoding if necessary before writing

Returns

the number of bytes written

Exceptions

FILE-WRITE-ERROR	File is not open or an I/O error occurred writing data to the File
ENCODING-CONVERSION-ERROR	error converting from the string's character encoding to the File's character encoding
ILLEGAL-EXPRESSION	this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

Note

this variant of this method is equivalent to File::print()

Since

Qore 0.8.7 this method throws exceptions on I/O errors to avoid silent write errors in Qore code

writei1()

int Qore::File::writei1

(

int

c

)

Writes a 1-byte integer to the file.

Example:

f.writei1(val);

Events:

EVENT_DATA_WRITTEN

Parameters

c	the integer to write; only the least-significant 8 bits will be written to the file

Returns

0 for success

Exceptions

FILE-WRITE-ERROR	File is not open or an I/O error occurred writing data to 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

Since

Qore 0.8.7 this method throws exceptions on I/O errors to avoid silent write errors in Qore code

writei2()

int Qore::File::writei2

(

int

s

)

Writes a 2-byte (16 bit) integer to the file in binary big-endian format.

Example:

f.writei2(val);

Events:

EVENT_DATA_WRITTEN

Parameters

s	the integer to write in binary big-endian format; only the least-significant 16 bits of the integer will be written to the file

Returns

0 for success

Exceptions

FILE-WRITE-ERROR	File is not open or an I/O error occurred writing data to 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

Since

Qore 0.8.7 this method throws exceptions on I/O errors to avoid silent write errors in Qore code

writei2LSB()

int Qore::File::writei2LSB

(

int

s

)

Writes a 2-byte (16 bit) integer to the file in binary little-endian format.

Example:

f.writei2LSB(val);

Events:

EVENT_DATA_WRITTEN

Parameters

s	the integer to write in binary little-endian format; only the least-significant 16 bits of the integer will be written to the file

Returns

0 for success

Exceptions

FILE-WRITE-ERROR	File is not open or an I/O error occurred writing data to 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

Since

Qore 0.8.7 this method throws exceptions on I/O errors to avoid silent write errors in Qore code

writei4()

int Qore::File::writei4

(

int

i

)

Writes a 4-byte (32 bit) integer to the file in binary big-endian format.

Example:

f.writei4(val);

Events:

EVENT_DATA_WRITTEN

Parameters

i	the integer to write in binary big-endian format; only the least-significant 32 bits of the integer will be written to the file

Returns

0 for success

Exceptions

FILE-WRITE-ERROR	File is not open or an I/O error occurred writing data to 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

Since

Qore 0.8.7 this method throws exceptions on I/O errors to avoid silent write errors in Qore code

writei4LSB()

int Qore::File::writei4LSB

(

int

i

)

Writes a 4-byte (32 bit) integer to the file in binary little-endian format.

Example:

f.writei4LSB(val);

Events:

EVENT_DATA_WRITTEN

Parameters

i	the integer to write in binary little-endian format; only the least-significant 32 bits of the integer will be written to the file

Returns

0 for success

Exceptions

FILE-WRITE-ERROR	File is not open or an I/O error occurred writing data to 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

Since

Qore 0.8.7 this method throws exceptions on I/O errors to avoid silent write errors in Qore code

writei8()

int Qore::File::writei8

(

int

i

)

Writes an 8-byte (64 bit) integer to the file in binary big-endian format.

Example:

f.writei8(val);

Events:

EVENT_DATA_WRITTEN

Parameters

i	the integer to write in binary big-endian format; only the least-significant 64 bits of the integer will be written to the file

Returns

0 for success

Exceptions

FILE-WRITE-ERROR	File is not open or an I/O error occurred writing data to 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

Since

Qore 0.8.7 this method throws exceptions on I/O errors to avoid silent write errors in Qore code

writei8LSB()

int Qore::File::writei8LSB

(

int

i

)

Writes an 8-byte (64 bit) integer to the file in binary little-endian format.

Example:

f.writei8LSB(val);

Events:

EVENT_DATA_WRITTEN

Parameters

i	the integer to write in binary little-endian format; only the least-significant 64 bits of the integer will be written to the file

Returns

0 for success

Exceptions

FILE-WRITE-ERROR	File is not open or an I/O error occurred writing data to 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

Since

Qore 0.8.7 this method throws exceptions on I/O errors to avoid silent write errors in Qore code