4.3. File Class

4.3. File Class
Prev	Chapter 4. System Namespaces and Class Library	Next

Note: This class is not available with the PO_NO_FILESYSTEM parse option.

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

File objects can be 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 Qore character encoding is assumed for the file.

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

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

Table 4.26. 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.

Table 4.27. File Method Overview

Method	Except?	Description
`File::constructor()` `File::constructor(string$encoding)`	N	Creates the object and optionally sets the file's character encoding.
`File::destructor()`	N	Closes the file if it is open and destroys the file object.
`File::copy()`	N	Creates a new file object with the same character encoding specification as the original, otherwise no other information is copied.
`nothingFile::chown(softint$uid, softint$gid = -1)`	Y	Changes the user and group owners of the file on the filesystem (if the current user has sufficient permission to do so).
`intFile::close()`	N	Closes the file object
`intFile::f_printf(string$fmt, ...)` `intFile::f_printf() (RT_NOOP)`	Y	Writes a formatted string to a file, enforces hard field limits.
`intFile::f_vprintf(string$fmt, any$args)` `intFile::f_vprintf() (RT_NOOP)`	Y	Writes a formatted string to a file, where the second argument is the formatting argument list, enforces hard field limits.
`*stringFile::getchar()`	N	Reads one character from the file; returns NOTHING if no data can be read from the file.
`stringFile::getCharset()`	N	Returns the character encoding for the file
`hashFile::getLockInfo()`	Y	Returns a hash of lock information.
`intFile::getPos()`	N	Gets the current file position (in bytes)
`nothingFile::getTerminalAttributes(TermIOS$termios)`	Y	Saves the current terminal attributes for the file in the TermIOS object passed; changes the object passed to reflect the terminal attributes as set for the file.
`hashFile::hstat()`	Y	Returns a Stat Hash about the file's status or throws an exception if any errors occur.
`boolFile::isDataAvailable(timeout$timeout_ms = 0)`	Y	Returns True if there is data available for reading from the file within the timeout period.
`intFile::lock(softint$type = F_RDLCK, softint$start = 0, softint$len = 0, softint$whence = SEEK_SET)`	Y	Attempts to lock the file according to the arguments passed, does not block.
`nothingFile::lockBlocking(softint$type = F_RDLCK, softint$start = 0, softint$len = 0, softint$whence = SEEK_SET)`	Y	Attempts to lock the file according to the arguments passed, blocking.
`intFile::open(string$path, softint$flags = O_RDONLY, softint$mode = 0666)` `intFile::open(string$path, softint$flags = O_RDONLY, softint$mode = 0666, string$encoding)`	Y	Opens a file in a particular mode, returns an error code on failure.
`nothingFile::open2(string$path, softint$flags = O_RDONLY, softint$mode = 0666)` `nothingFile::open2(string$path, softint$flags = O_RDONLY, softint$mode = 0666, string$encoding)`	Y	Opens a file in a particular mode; throws an exception on failure.
`intFile::printf(string$fmt, ...)` `intFile::printf() (RT_NOOP)`	Y	Writes a formatted string to a file.
`*stringFile::read(softint$size, timeout$timeout_ms = -1)`	Y	Reads a certain number of bytes from the file within an optional timeout period and returns a string of the data read or NOTHING if no data can be read.
`*binaryFile::readBinary(softint$size, timeout$timeout_ms = 1)`	Y	Reads a certain number of bytes from the file within an optional timeout period and returns binary data or NOTHING if no data can be read.
`*intFile::readi1()`	Y	Reads a 1-byte signed integer from the file or NOTHING if no data can be read.
`*intFile::readi2()`	Y	Reads a 2-byte signed integer from the file in big-endian format or NOTHING if no data can be read.
`*intFile::readi4()`	Y	Reads a 4-byte signed integer from the file in big-endian format or NOTHING if no data can be read.
`*intFile::readi8()`	Y	Reads an 8-byte signed integer from the file in big-endian format or NOTHING if no data can be read.
`*intFile::readi2LSB()`	Y	Reads a 2-byte signed integer from the file in little-endian format or NOTHING if no data can be read.
`*intFile::readi4LSB()`	Y	Reads a 4-byte signed integer from the file in little-endian format or NOTHING if no data can be read.
`*intFile::readi8LSB()`	Y	Reads an 8-byte signed integer from the file in little-endian format or NOTHING if no data can be read.
`*intFile::readu1()`	Y	Reads a 1-byte unsigned integer from the file or NOTHING if no data can be read.
`*intFile::readu2()`	Y	Reads a 2-byte unsigned integer from the file in big-endian format or NOTHING if no data can be read.
`*intFile::readu4()`	Y	Reads a 4-byte unsigned integer from the file in big-endian format or NOTHING if no data can be read.
`*intFile::readu2LSB()`	Y	Reads a 2-byte unsigned integer from the file in little-endian format or NOTHING if no data can be read.
`*intFile::readu4LSB()`	Y	Reads a 4-byte unsigned integer from the file in little-endian format or NOTHING if no data can be read.
`*stringFile::readLine()`	Y	Reads until an EOL marker is found and returns the string read or NOTHING if no data can be read.
`nothingFile::setCharset()` `nothingFile::setCharset(string$encoding)`	N	Sets the character encoding for the file; if passed with no argument, the default encoding is set.
`intFile::setPos(softint$pos = 0)`	N	Sets the current file position (in bytes).
`nothingFile::setTerminalAttributes(softint$action = TCSANOW, TermIOS$termios)`	Y	Sets the current terminal attributes for the file from the TermIOS object passed; does not change the object passed.
`listFile::stat()`	Y	Returns a Stat List about the file's status or throws an exception if any errors occur.
`hashFile::statvfs()`	Y	Returns a Filesystem Status Hash about the file's filesystem status or throws an exception if any errors occur.
`intFile::sync()`	N	Flushes the file's buffer to disk.
`intFile::vprintf(string$fmt, any$args)` `intFile::vprintf() (RT_NOOP)`	Y	Writes a formatted string to a file, where the second argument is the formatting argument list.
`intFile::write(data$data)`	Y	Writes string or binary data to a file
`intFile::writei1(softint$i = 0)`	Y	Writes a 1-byte integer to the file.
`intFile::writei2(softint$i = 0)`	Y	Writes a 2-byte integer in big-endian format.
`intFile::writei4(softint$i = 0)`	Y	Writes a 4-byte integer in big-endian format.
`intFile::writei8(softint$i = 0)`	Y	Writes an 8-byte integer in big-endian format.
`intFile::writei2LSB(softint$i = 0)`	Y	Writes a 2-byte integer in little-endian format.
`intFile::writei4LSB(softint$i = 0)`	Y	Writes a 4-byte integer in little-endian format.
`intFile::writei8LSB(softint$i = 0)`	Y	Writes an 8-byte integer in little-endian format.
`statichashFile::hlstat(string$path)`	Y	Returns a Stat Hash about the given path's status (does not follow symbolic links) or throws an exception if any errors occur.
`statichashFile::hstat(string$path)`	Y	Returns a Stat Hash about the given path's status (follows symbolic links) or throws an exception if any errors occur.
`staticlistFile::lstat(string$path)`	Y	Returns a Stat List about given path's status (does not follow synbolic links) or throws an exception if any errors occur.
`staticlistFile::stat(string$path)`	Y	Returns a Stat List about given path's status (follows symbolic links) or throws an exception if any errors occur.
`statichashFile::statvfs(string$path)`	Y	Returns a Filesystem Status Hash about the given path's filesystem status or throws an exception if any errors occur.

Table 4.28. File Constants in the Qore Namespace

Name	Description
`O_RDONLY`	Open the file read-only.
`O_WRONLY`	Open the file write-only.
`O_CREAT`	Create the file if it doesn't exist.
`O_APPEND`	Open the file in append mode.
`O_RDWR`	Open for reading and writing.
`O_TRUNC`	Truncate the size to zero.

Table 4.29. File Locking Constants in the Qore Namespace

Name	Description
`F_RDLCK`	Use for read-only locking.
`F_WRLCK`	Use for exclusive write locking.
`F_UNLCK`	Use for unlocking a lock.

Table 4.30. File Seek Constants in the Qore Namespace

Name	Description
`SEEK_SET`	Indicates that the offset is from the start of the file.
`SEEK_CUR`	Indicates that the offset is from the current position in the file.
`SEEK_END`	Indicates that the offset is from the end of the file.

Table 4.31. Stat Constants in the Qore Namespace

Name	Description
`S_IFMT`	File type bitmask
`S_IFCHR`	Bit signifying if the file is a character special (device) file
`S_IFDIR`	Bit signifying if the entry is a directory
`S_IFBLK`	Bitmask signifying if the file is a block special (device) file
`S_IFREG`	Bit signifying if the file is a regular file
`S_IFLNK`	Bitmask signifying if the file is a symbolic link
`S_IFSOCK`	Bitmask signifying if the file is a socket file
`S_IFWHT`	Bitmask signifying if the file is a whiteout file
`S_IRWXU`	Bitmask giving the RWX mask for the owner
`S_IRUSR`	Bit signifying if the file's owner has read permissions
`S_IWUSR`	Bit signifying if the file's owner has write permissions
`S_IXUSR`	Bit signifying if the file's owner has execute permissions
`S_IRWXG`	Bitmask giving the RWX mask for the group
`S_IRGRP`	Bit signifying if the file's group has read permissions
`S_IWGRP`	Bit signifying if the file's group has write permissions
`S_IXGRP`	Bit signifying if the file's group has execute permissions
`S_IRWXO`	Bitmask giving the RWX mask for other
`S_IROTH`	Bit signifying if other has read permissions
`S_IWOTH`	Bit signifying if other has write permissions
`S_IXOTH`	Bit signifying if other has execute permissions
`S_ISUID`	Bit signifying set user id on execution
`S_ISGID`	Bit signifying set group id on execution
`S_ISVTX`	Bit signifying restricted deletes for directories

4.3.1. File::constructor()

Synopsis

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

Prototype

File::constructor()

File::constructor(string$encoding)

Example

my File $f("ISO-8859-1"); # specify ISO-8859-1 encoding for the file

Table 4.32. Arguments for File::constructor()

Argument	Type	Description
`encoding`	`string`	The character encoding for the file. Any strings written to the file will be converted to this character encoding if necessary.

4.3.2. File::destructor()

Synopsis

Closes the file if it's open and destroys the File object.

Example

delete $f;

Events

EVENT_CHANNEL_CLOSED, EVENT_DELETED

4.3.3. File::copy()

Synopsis

Creates a new File object with the same character encoding specification as the original.

Example

my File $f1 = $f.copy();

4.3.4. File::chown()

Synopsis

Changes the file's user and group owner (if the user has sufficient permissions to do so).

Prototype

nothingFile::chown(softint$uid, softint$gid = -1)

Example

$f.chown(0, 0);

Platform Availability

HAVE_UNIX_FILEMGT

Table 4.33. Arguments for File::chown()

Argument	Description
`softint$uid`	The user id of the user to change to; -1 means do not change uid.
`softint$gid`	The group id of the user to change to; -1 means do not change gid.

Table 4.34. Return Value for File::chown()

Return Type	Description
n/a	This method does not return a value; if an error occurs, an exception is thrown.

Table 4.35. Exceptions Thrown by File::chown()

err	desc
`FILE-CHOWN-ERROR`	File is not open or the chown 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 `HAVE_UNIX_FILEMGT` before calling this function.

4.3.5. File::close()

Synopsis

Closes the file object if it's open. Note that this is automatically called by File::destructor().

Prototype

intFile::close()

Example

$f.close();

Events

EVENT_CHANNEL_CLOSED

Table 4.36. Return Value for File::close()

Return Type	Description
`int`	0 for success, -1 for an error (see errno() and strerror() for the error information)

4.3.6. File::f_printf()

Synopsis

Writes a formatted string to a file, enforces hard field limits (similar to the f_printf() function). See String Formatting for more information about the format string.

Prototype

intFile::f_printf(string$fmt, ...)

intFile::f_printf() (RT_NOOP)

Example

$f.f_printf("%5s\n", "long string"); # will print "long \n", respecting the 5-character field width

Table 4.37. Arguments for File::f_printf()

Argument	Description
`string$fmt`	The format string, see String Formatting for a specification.
`...`	The remainder of the arguments are arguments to the format string.

Table 4.38. Return Value for File::f_printf()

Return Type	Description
`int`	Returns 0 for success, -1 for error.

Table 4.39. Exceptions Thrown by File::f_printf()

err	desc
`FILE-WRITE-ERROR`	File is not open.

4.3.7. File::f_vprintf()

Synopsis

Writes a formatted string to a file, where the second argument is the formatting argument list, enforces hard field limits. See String Formatting for more information about the format string.

Prototype

intFile::f_vprintf(string$fmt, any$args)

intFile::f_vprintf() (RT_NOOP)

Example

$f.f_vprintf("%5s %3d\n", ("a long string", 5000)); # outputs "a lon 500", truncating output

Table 4.40. Arguments for File::f_vprintf()

Argument	Description
`string$fmt`	The format string, see String Formatting for a specification.
`any$args`	This single argument or list of arguments 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.

Table 4.41. Return Value for File::f_vprintf()

Return Type	Description
`int`	Returns 0 for success, -1 for error.

Table 4.42. Exceptions Thrown by File::f_vprintf()

err	desc
`FILE-WRITE-ERROR`	File is not open.

4.3.8. File::getchar()

Synopsis

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

Prototype

*stringFile::getchar()

Example

my *string $str = $f.getchar();

Table 4.43. Return Value for File::getchar()

Return Type	Description
`*string or nothing`	The single character read from the file or NOTHING if no data can be read from the file.

4.3.9. File::getCharset()

Synopsis

Returns the character encoding for the file.

Prototype

stringFile::getCharset()

Example

$encoding = $f.getCharset();

Table 4.44. Return Value for File::getCharset()

Return Type	Description
`string`	The character encoding for the file.

4.3.10. File::getLockInfo()

Synopsis

Returns a hash of lock information for the file. The hash contains the following keys: start, len, pid, type, whence. If no lock is set on the file, the key type has the value F_UNLCK.

Prototype

hashFile::getLockInfo()

Example

my hash $hash = $f.getLockInfo();

Table 4.45. Return Value for File::getLockInfo()

Return Type	Description
`hash`	The hash contains the following keys: `start, len, pid, type, whence`. If no lock is set on the file, the key type has the value `F_UNLCK`.

Table 4.46. Exceptions Thrown by File::getLockInfo()

err	desc
`FILE-LOCK-ERROR`	File is not open or the fcntl operation failed.

4.3.11. File::getPos()

Synopsis

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

Prototype

intFile::getPos()

Example

$pos = $f.getPos();

Table 4.47. Return Value for File::getPos()

Return Type	Description
`int`	The byte position in the file starting at 0.

4.3.12. File::getTerminalAttributes()

Synopsis

Saves the current terminal attributes for the file in the TermIOS object passed; changes the object passed to reflect the terminal attributes as set for the file. Do not pass a reference to the TermIOS object; pass the object itself.

Prototype

nothingFile::getTerminalAttributes(TermIOS$termios)

Example

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

Table 4.48. Arguments for File::getTerminalAttributes()

Argument	Description
`TermIOS$termios`	The method writes the current terminal attributes for the file to the object passed.

Table 4.49. Exceptions Thrown by File::getTerminalAttributes()

err	desc
`FILE-OPERATION-ERROR`	The file is not open.
`TERMIOS-GET-ERROR`	Error reading terminal attributes from the file descriptor.

4.3.13. File::hstat()

Synopsis

Returns a hash of file status values for the current file.

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

Return Type	Description
`hash`	Returns a hash of file status values for the current file (must be open); if any errors occur, an exception is thrown. See also static File::hstat(). See Stat Hash for a description of the hash returned by this method.

err	desc
`FILE-HSTAT-ERROR`	`stat()` call failed or file not open.

4.3.14. File::isDataAvailable()

Synopsis

Returns True is data becomes available for reading on the file within a 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 time value may be passed instead of an integer to make the timeout units clear (ex: 25ms).

Prototype

boolFile::isDataAvailable(timeout$timeout_ms = 0)

Example

my bool $b = $file.isDataAvailable(0); # returns True if data is available now

Table 4.52. Arguments for File::isDataAvailable()

Argument	Description
`timeout$timeout_ms`	An optional timeout in milliseconds (1/1000 second).

Table 4.53. Return Values for File::isDataAvailable()

Return Type	Description
`bool`	True if data becomes available for reading from the file within the timeout period, `False` if not.

Table 4.54. Exceptions Thrown by File::isDataAvailable()

err	desc
`FILE-READ-ERROR`	The file is not open.

4.3.15. File::lock()

Synopsis

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. For a blocking version of this method, see File::lockBlocking().

Prototype

intFile::lock(softint$type = F_RDLCK, softint$start = 0, softint$len = 0, softint$whence = SEEK_SET)

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

Platform Availability

HAVE_FILE_LOCKING

Table 4.55. Arguments for File::lock()

Argument	Description
`softint$type = F_RDLCK`	Type of lock (or unlock); see File locking constants.
`softint$start = 0`	Start byte for lock, 0 is the default (start of file).
`softint$len = 0`	Length in bytes for range to lock, 0 is the default (rest of file).
`softint$whence = SEEK_SET`	Indicates how the relative offset of the file should be calculated for the lock; see File seek constants.

Table 4.56. Return Value for File::lock()

Return Type	Description
`int`	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).

Table 4.57. Exceptions Thrown by File::lock()

err	desc
`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 `HAVE_FILE_LOCKING` before calling this function.

4.3.16. File::lockBlocking()

Synopsis

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. For a non-blocking version of this method, see File::lock().

Prototype

nothingFile::lockBlocking(softint$type = F_RDLCK, softint$start = 0, softint$len = 0, softint$whence = SEEK_SET)

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

Platform Availability

HAVE_FILE_LOCKING

Table 4.58. Arguments for File::lockBlocking()

Argument	Description
`softint$type = F_RDLCK`	Type of lock (or unlock), see File locking constants.
`softint$start = 0`	Start byte for lock, 0 is the default (start of file).
`softint$len = 0`	Length in bytes for range to lock, 0 is the default (rest of file).
`softint$whence = SEEK_SET`	Indicates how the relative offset of the file should be calculated for the lock; see File seek constants.

Table 4.59. Return Value for File::lockBlocking()

Return Type	Description
n/a	This method does not return a value; exceptions are thrown if errors occur.

Table 4.60. Exceptions Thrown by File::lockBlocking()

err	desc
`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 `HAVE_FILE_LOCKING` before calling this function.

4.3.17. File::printf()

Synopsis

Writes a formatted string with soft field widths to the file. See File::f_printf() for a similar method that enforces field widths. See String Formatting for more information about the format string.

Prototype

intFile::printf(string$fmt, ...)

intFile::printf() (RT_NOOP)

Example

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

Events

EVENT_DATA_WRITTEN

Table 4.61. Arguments for File::printf()

Argument	Description
`string$fmt`	The format string, see String Formatting for a specification.
...	The remainder of the arguments are arguments to the format string.

Table 4.62. Return Value for File::printf()

Return Type	Description
`int`	Returns 0 for success, -1 for error.

Table 4.63. Exceptions Thrown by File::printf()

err	desc
`FILE-WRITE-ERROR`	File is not open.

4.3.18. File::open()

Synopsis

Opens the file in the mode given. Aditionally, 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 default character encoding for the process. 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.

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

Prototype

intFile::open(string$path, softint$flags = O_RDONLY, softint$mode = 0666)

intFile::open(string$path, softint$flags = O_RDONLY, softint$mode = 0666, string$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
$f.open("new_file.txt", O_CREAT | O_TRUNC | O_WRONLY, 0644, "ISO-8859-1");

Events

EVENT_OPEN_FILE, EVENT_FILE_OPENED

Table 4.64. Arguments for File::open()

Argument	Description
`string$path`	The path to the file.
`softint$flags = O_RDONLY`	Flags that determine the way the file is accessed, see File Constants for more information. If this argument is not given, `O_RDONLY` will be used as the default value.
`softint$mode = 0666`	Permission bits for when the file is to be created (default: 0666)
`[string$encoding]`	The name of the default character encoding for this file; if this argument is not given, the file will be tagged with the default character encoding for the process.

Table 4.65. Return Values for File::open()

Return Type	Description
`int`	0 = no error, -1 = see errno() and strerror() for the error message

This method does not throw any exceptions.

4.3.19. File::open2()

Synopsis

Opens the file in the mode given. Aditionally, the file permissions can be given if the file is to be created, and optionally the file's default character encoding can be specified.

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

Prototype

nothingFile::open2(string$path, softint$flags = O_RDONLY, softint$mode = 0666)

nothingFile::open2(string$path, softint$flags = O_RDONLY, softint$mode = 0666, string$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
$f.open2("new_file.txt", O_CREAT | O_TRUNC | O_WRONLY, 0644, "ISO-8859-1");

Events

EVENT_OPEN_FILE, EVENT_FILE_OPENED

Table 4.66. Arguments for File::open2()

Argument	Description
`string$path`	The path to the file.
`softint$flags = O_RDONLY`	Flags that determine the way the file is accessed, see File Constants for more information. If this argument is not given, `O_RDONLY` will be used as the default value.
`softint$mode = 0666`	Permission bits for when the file is to be created (default: 0666)
`[string$encoding]`	The name of the default character encoding for this file; if this argument is not given, the file will be tagged with the default character encoding for the process.

Table 4.67. Exceptions Thrown by File::open2()

err	desc
`FILE-OPEN2-ERROR`	Error opening the file; attempted to reopen a system file (I/O constants).

4.3.20. File::read()

Synopsis

Reads a certain amount of string data from the file; the size argument is required. To read binary data, use the File::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 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.

Prototype

*stringFile::read(softint$size, timeout$timeout_ms = -1)

Example

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

Events

EVENT_DATA_READ

Table 4.68. Arguments for File::read()

Argument	Description
`softint$size`	The number of bytes to read of the file, -1 will read the entire file.
`timeout$timeout_ms = -1`	A timeout period with a resolution of milliseconds (an integer argument 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.

Table 4.69. Return Value for File::read()

Return Type	Description
`*string`	The data read from the file, returned as a string. 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.

Table 4.70. Exceptions Thrown by File::read()

err	desc
`FILE-READ-PARAMETER-ERROR`	Zero size argument passed.
`FILE-READ-ERROR`	File is not open; timeout limit exceeded.

4.3.21. File::readi1()

Synopsis

Reads a 1-byte signed integer from the file and returns the integer value read.

Prototype

*intFile::readi1()

Example

my *int $i = $f.readi1();

Events

EVENT_DATA_READ

Table 4.71. Return Value for File::readi1()

Return Type	Description
`*int`	Returns a 1-byte signed integer as read from the file in binary format or NOTHING if no data can be read.

Table 4.72. Exceptions Thrown by File::readi1()

err	desc
`FILE-READ-ERROR`	File is not open.

4.3.22. File::readi2()

Synopsis

Reads a 2-byte signed integer from the file in big-endian (MSB, network byte order) format. See File::readi2LSB() for an equivalent method reading a 2-byte signed integer in little-endian (LSB) format.

Prototype

*intFile::readi2()

Example

my *int $i = $f.readi2();

Events

EVENT_DATA_READ

Table 4.73. Return Value for File::readi2()

Return Type	Description
`*int`	Returns a 2-byte signed integer as read from the file in big-endian format or NOTHING if no data can be read.

Table 4.74. Exceptions Thrown by File::readi2()

err	desc
`FILE-READ-ERROR`	File is not open.

4.3.23. File::readi4()

Synopsis

Reads a 4-byte signed integer from the file in big-endian format. See File::readi4LSB() for an equivalent method reading a 4-byte signed integer in little-endian (LSB) format.

Prototype

*intFile::readi4()

Example

my *int $i = $f.readi4();

Events

EVENT_DATA_READ

Table 4.75. Return Value for File::readi4()

Return Type	Description
`*int`	Returns a 4-byte signed integer as read from the file in big-endian format or NOTHING if no data can be read.

Table 4.76. Exceptions Thrown by File::readi4()

err	desc
`FILE-READ-ERROR`	File is not open.

4.3.24. File::readi8()

Synopsis

Reads a 4-byte signed integer from the file in big-endian format. See File::readi8LSB() for an equivalent method reading a 4-byte signed integer in little-endian (LSB) format.

Prototype

*intFile::readi8()

Example

my *int $i = $f.readi8();

Events

EVENT_DATA_READ

Table 4.77. Return Value for File::readi8()

Return Type	Description
`*int`	Returns a 4-byte signed integer as read from the file in big-endian format or NOTHING if no data can be read.

Table 4.78. Exceptions Thrown by File::readi8()

err	desc
`FILE-READ-ERROR`	File is not open.

4.3.25. File::readi2LSB()

Synopsis

Reads a 2-byte signed integer from the file in little-endian (LSB) format. See File::readi2() for an equivalent method reading a 2-byte signed integer in big-endian (MSB, network byte order) format.

Prototype

*intFile::readi2LSB()

Example

my *int $i = $f.readi2LSB();

Events

EVENT_DATA_READ

Table 4.79. Return Value for File::readi2LSB()

Return Type	Description
`*int`	Reads a 2-byte signed integer from the file in little-endian format or NOTHING if no data can be read.

Table 4.80. Exceptions Thrown by File::readi2LSB()

err	desc
`FILE-READ-ERROR`	File is not open.

4.3.26. File::readi4LSB()

Synopsis

Reads a 4-byte signed integer from the file in little-endian format. See File::readi4() for an equivalent method reading a 4-byte signed integer in big-endian (MSB, network byte order) format.

Prototype

*intFile::readi4LSB()

Example

my *int $i = $f.readi4LSB();

Events

EVENT_DATA_READ

Table 4.81. Return Value for File::readi4LSB()

Return Type	Description
`*int`	Reads a 4-byte signed integer from the file in little-endian format or NOTHING if no data can be read.

Table 4.82. Exceptions Thrown by File::readi4LSB()

err	desc
`FILE-READ-ERROR`	File is not open.

4.3.27. File::readi8LSB()

Synopsis

Reads an 8-byte signed integer from the file in little-endian format. See File::readi8() for an equivalent method reading a 8-byte signed integer in big-endian (MSB, network byte order) format.

Prototype

*intFile::readi8LSB()

Example

my *int $i = $f.readi8LSB();

Events

EVENT_DATA_READ

Table 4.83. Return Value for File::readi8LSB()

Return Type	Description
`*int`	Reads a 4-byte signed integer from the file in little-endian format or NOTHING if no data can be read.

Table 4.84. Exceptions Thrown by File::readi8LSB()

err	desc
`FILE-READ-ERROR`	File is not open.

4.3.28. File::readu1()

Synopsis

Reads a 1-byte unsigned integer from the file and returns the integer value read.

Prototype

*intFile::readu1()

Example

my *int $i = $f.readu1();

Events

EVENT_DATA_READ

Table 4.85. Return Value for File::readu1()

Return Type	Description
`*int`	Returns a 1-byte unsigned integer as read from the file in binary format or NOTHING if no data can be read.

Table 4.86. Exceptions Thrown by File::readu1()

err	desc
`FILE-READ-ERROR`	File is not open.

4.3.29. File::readu2()

Synopsis

Reads a 2-byte signed integer from the file in big-endian (MSB, network byte order) format. See File::readu2LSB() for an equivalent method reading a 2-byte signed integer in little-endian (LSB) format.

Prototype

*intFile::readu2()

Example

my *int $i = $f.readu2();

Events

EVENT_DATA_READ

Table 4.87. Return Value for File::readu2()

Return Type	Description
`*int`	Returns a 2-byte signed integer as read from the file in big-endian format or NOTHING if no data can be read.

Table 4.88. Exceptions Thrown by File::readu2()

err	desc
`FILE-READ-ERROR`	File is not open.

4.3.30. File::readu4()

Synopsis

Reads a 4-byte signed integer from the file in big-endian format. See File::readu4LSB() for an equivalent method reading a 4-byte signed integer in little-endian (LSB) format.

Prototype

*intFile::readu4()

Example

my *int $i = $f.readu4();

Events

EVENT_DATA_READ

Table 4.89. Return Value for File::readu4()

Return Type	Description
`*int`	Returns a 4-byte signed integer as read from the file in big-endian format or NOTHING if no data can be read.

Table 4.90. Exceptions Thrown by File::readu4()

err	desc
`FILE-READ-ERROR`	File is not open.

4.3.31. File::readu2LSB()

Synopsis

Reads a 2-byte signed integer from the file in little-endian (LSB) format. See File::readu2() for an equivalent method reading a 2-byte signed integer in big-endian (MSB, network byte order) format.

Prototype

*intFile::readu2LSB()

Example

my *int $i = $f.readu2LSB();

Events

EVENT_DATA_READ

Table 4.91. Return Value for File::readu2LSB()

Return Type	Description
`*int`	Reads a 2-byte signed integer from the file in little-endian format or NOTHING if no data can be read.

Table 4.92. Exceptions Thrown by File::readu2LSB()

err	desc
`FILE-READ-ERROR`	File is not open.

4.3.32. File::readu4LSB()

Synopsis

Reads a 4-byte unsigned integer from the file in little-endian format. See File::readu4() for an equivalent method reading a 4-byte signed integer in big-endian (MSB, network byte order) format or NOTHING if no data can be read.

Prototype

*intFile::readu4LSB()

Example

my *int $i = $f.readu4LSB();

Events

EVENT_DATA_READ

Table 4.93. Return Value for File::readu4LSB()

Return Type	Description
`*int`	Reads a 4-byte unsigned integer from the file in little-endian format or NOTHING if no data can be read.

Table 4.94. Exceptions Thrown by File::readu4LSB()

err	desc
`FILE-READ-ERROR`	File is not open.

4.3.33. File::readBinary()

Synopsis

Read a certain amount of data and return a binary object; the size parameter is mandatory.

Prototype

*binaryFile::readBinary(softint$size, timeout$timeout_ms = 1)

Example

my *binary $data = $f.readBinary(); # reads an entire binary file into a variable

Events

EVENT_DATA_READ

Table 4.95. Arguments for File::readBinary()

Argument	Description
`int#size`	The number of bytes to read of the file.
`timeout$timeout_ms = -1`	A timeout period in milliseconds; if negative (the default) the call will never time out and will only return when the data has been read.

Table 4.96. Return Value for File::readBinary()

Return Type	Description
`*binary`	A binary object containing the data 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.

Table 4.97. Exceptions Thrown by File::readBinary()

err	desc
`FILE-READ-BINARY-PARAMETER-ERROR`	Zero size argument passed.
`FILE-READ-ERROR`	File is not open; timeout limit exceeded.

4.3.34. File::readLine()

Synopsis

Reads until an EOL marker is found and returns a string containing the EOL marker. Returns NOTHING on end of file.

Prototype

*stringFile::readLine()

Example

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

Events

EVENT_DATA_READ

Table 4.98. Return Value for File::readLine()

Return Type	Description
`*string`	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.

Table 4.99. Exceptions Thrown by File::readLine()

err	desc
`FILE-READLINE-ERROR`	File is not open.

4.3.35. File::setCharset()

Synopsis

Sets the characte encoding for the file.

Prototype

nothingFile::setCharset()

nothingFile::setCharset(string$encoding)

Example

$f.setCharset("ISO-8859-1");

Table 4.100. Arguments for File::setCharset()

Argument	Description
`[string$encoding]`	The character encoding for the file.

4.3.36. File::setPos()

Synopsis

Sets the current file position in bytes starting with zero.

Prototype

intFile::setPos(softint$pos = 0)

Example

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

Table 4.101. Arguments for File::setPos()

Argument	Description
`softint$pos = 0`	The position in the file as offset from position 0.

Table 4.102. Return Value for File::setPos()

Return Type	Description
`int`	Returns the new offset in the file, -1 for error.

4.3.37. File::setTerminalAttributes()

Synopsis

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

Prototype

nothingFile::setTerminalAttributes(softint$action = TCSANOW, TermIOS$termios)

Example

my TermIOS $termios();
stdin.getTerminalAttributes($termios);
my TermIOS $orig = $termios.copy();
on_exit
    stdin.setTerminalAttributes(TCSADRAIN, $orig);

my $lflag = $termios.getLFlag();
$lflag &= ~ICANON;
$lflag &= ~ECHO;
$lflag &= ~ISIG;
$termios.setLFlag($lflag);
$termios.setCC(VMIN, 1);
$termios.setCC(VTIME, 0);
stdin.setTerminalAttributes(TCSADRAIN, $termios);

Table 4.103. Arguments for File::setTerminalAttributes()

Argument	Description
`softint$action = TCSANOW, TermIOS$termios`	Sets the current terminal attributes for the file from the TermIOS object passed.

Table 4.104. Return Value for File::setTerminalAttributes()

Return Type	Description
`int`	Always returns 0; if an error is encountered, an exception is raised.

Table 4.105. Exceptions Thrown by File::setTerminalAttributes()

err	desc
`FILE-OPERATION-ERROR`	The file is not open.
`TERMIOS-GET-ERROR`	Error setting terminal attributes on the file descriptor.

4.3.38. File::stat()

Synopsis

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

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

4.3.39. File::statvfs()

Synopsis

Returns a hash of filesystem status values for the current file (must be open).

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

4.3.40. File::sync()

Synopsis

Flushes the file's buffer to disk.

Prototype

intFile::sync()

Example

$f.sync();

Table 4.110. Return Value for File::sync()

Return Type	Description
`int`	Returns 0 for success, -1 for error.

4.3.41. File::vprintf()

Synopsis

Writes a formatted string to a file, where the first argument is a format string,and the second argument is the formatting argument list.

Prototype

intFile::vprintf(string$fmt, any$args)

intFile::vprintf() (RT_NOOP)

Example

$f.vprintf("%5s\n", "hello");

Events

EVENT_DATA_WRITTEN

Table 4.111. Arguments for File::vprintf()

Argument	Description
`string$fmt`	The format string, see String Formatting for a specification.
`any$args`	This single argument or list of arguments 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.

Table 4.112. Return Value for File::vprintf()

Return Type	Description
`int`	Returns 0 for success, -1 for error.

Table 4.113. Exceptions Thrown by File::vprintf()

err	desc
`FILE-WRITE-ERROR`	File is not open.

4.3.42. File::write()

Synopsis

Writes string or binary data to a file. String data will be converted to the file's character encoding if necessary before writing.

Prototype

intFile::write(data$data)

Example

$f.write($data);

Events

EVENT_DATA_WRITTEN

Table 4.114. Arguments for File::write()

Argument	Description
`data$data`	Writes the data to the file.

Table 4.115. Return Value for File::write()

Return Type	Description
`int`	Returns the number of bytes written or -1 for error. If -1 is returned, the error can be checked with the errno() function.

Table 4.116. Exceptions Thrown by File::write()

err	desc
`FILE-WRITE-ERROR`	File is not open.

4.3.43. File::writei1()

Synopsis

Writes a 1-byte integer to the file.

Prototype

intFile::writei1(softint$i = 0)

Example

$f.writei1($val);

Events

EVENT_DATA_WRITTEN

Table 4.117. Arguments for File::writei1()

Argument	Description
`softint$i = 0`	The integer to write; only the least-significant 8 bits will be written to the file.

Table 4.118. Return Value for File::writei1()

Return Type	Description
`int`	Returns 0 for success, -1 for error.

Table 4.119. Exceptions Thrown by File::writei1()

err	desc
`FILE-WRITE-ERROR`	File is not open.

4.3.44. File::writei2()

Synopsis

Writes a 2-byte integer in big-endian format.

Prototype

intFile::writei2(softint$i = 0)

Example

$f.writei2($val);

Events

EVENT_DATA_WRITTEN

Table 4.120. Arguments for File::writei2()

Argument	Description
`softint$i = 0`	The integer to write; writes a 2-byte integer in big-endian format.

Table 4.121. Return Value for File::writei2()

Return Type	Description
`int`	Returns 0 for success, -1 for error.

Table 4.122. Exceptions Thrown by File::writei2()

err	desc
`FILE-WRITE-ERROR`	File is not open.

4.3.45. File::writei4()

Synopsis

Writes a 4-byte integer in big-endian format.

Prototype

intFile::writei4(softint$i = 0)

Example

$f.writei4($val);

Events

EVENT_DATA_WRITTEN

Table 4.123. Arguments for File::writei4()

Argument	Description
`softint$i = 0`	The integer to write; writes a 4-byte integer in big-endian format.

Table 4.124. Return Value for File::writei4()

Return Type	Description
`int`	Returns 0 for success, -1 for error.

Table 4.125. Exceptions Thrown by File::writei4()

err	desc
`FILE-WRITE-ERROR`	File is not open.

4.3.46. File::writei8()

Synopsis

Writes an 8-byte integer in big-endian format.

Prototype

intFile::writei8(softint$i = 0)

Example

$f.writei8($val);

Events

EVENT_DATA_WRITTEN

Table 4.126. Arguments for File::writei8()

Argument	Description
`softint$i = 0`	The integer to write; writes an 8-byte integer in big-endian format.

Table 4.127. Return Value for File::writei8()

Return Type	Description
`int`	Returns 0 for success, -1 for error.

Table 4.128. Exceptions Thrown by File::writei8()

err	desc
`FILE-WRITE-ERROR`	File is not open.

4.3.47. File::writei2LSB()

Synopsis

Writes a 2-byte integer in little-endian format.

Prototype

intFile::writei2LSB(softint$i = 0)

Example

$f.writei2LSB($val);

Events

EVENT_DATA_WRITTEN

Table 4.129. Arguments for File::writei2LSB()

Argument	Description
`softint$i = 0`	The integer to write; writes a 2-byte integer in little-endian format.

Table 4.130. Return Value for File::writei2LSB()

Return Type	Description
`int`	Returns 0 for success, -1 for error.

Table 4.131. Exceptions Thrown by File::writei2LSB()

err	desc
`FILE-WRITE-ERROR`	File is not open.

4.3.48. File::writei4LSB()

Synopsis

Writes a 4-byte integer in little-endian format.

Prototype

intFile::writei4LSB(softint$i = 0)

Example

$f.writei4LSB($val);

Events

EVENT_DATA_WRITTEN

Table 4.132. Arguments for File::writei4LSB()

Argument	Description
`softint$i = 0`	The integer to write; writes a 4-byte integer in little-endian format.

Table 4.133. Return Value for File::writei4LSB()

Return Type	Description
`int`	Returns 0 for success, -1 for error.

Table 4.134. Exceptions Thrown by File::writei4LSB()

err	desc
`FILE-WRITE-ERROR`	File is not open.

4.3.49. File::writei8LSB()

Synopsis

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

Prototype

intFile::writei8LSB(softint$i = 0)

Example

$f.writei8LSB($val);

Events

EVENT_DATA_WRITTEN

Table 4.135. Arguments for File::writei8LSB()

Argument	Description
`softint$i = 0`	The integer to write; writes an 8-byte integer in little-endian format.

Table 4.136. Return Value for File::writei8LSB()

Return Type	Description
`int`	Returns 0 for success, -1 for error.

Table 4.137. Exceptions Thrown by File::writei8LSB()

err	desc
`FILE-WRITE-ERROR`	File is not open.

Prev	Up	Next
4.2. Type Namespace	Home	4.4. Dir Class

Return Type	Description
`list`	Returns a list of file status values for the current file (must be open); an exception is thrown if any errors occur. See Stat List below for a description of the list returned by this method.

err	desc
`FILE-STATVFS-ERROR`	`statvfs()` call failed or file is not open.
`MISSING-FEATURE-ERROR`	This exception is thrown when the method is not available on the runtime platform; for maximum portability, check the constant `HAVE_STATVFS` before calling this function.