4.3. File Class

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.22. 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.23. File Method Overview

Method

Except?

Description

File::constructor()

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.

File::chown()

N

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

File::close()

N

Closes the file object

File::f_printf()

Y

Writes a formatted string to a file, enforces hard field limits.

File::f_vprintf()

Y

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

File::getchar()

N

Reads one character from the file

File::getCharset()

N

Returns the character encoding for the file

File::getLockInfo()

Y

Returns a hash of lock information.

File::getPos()

N

Gets the current file position (in bytes)

File::getTerminalAttributes()

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.

File::isDataAvailable()

Y

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

File::lock()

Y

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

File::lockBlocking()

Y

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

File::open()

Y

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

File::open2()

Y

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

File::printf()

Y

Writes a formatted string to a file.

File::read()

Y

Reads a certain number of bytes from the file within an optional timeout period and returns a string of the data read.

File::readBinary()

Y

Reads a certain number of bytes from the file within an optional timeout period and returns binary data.

File::readi1()

Y

Reads a 1-byte signed integer from the file.

File::readi2()

Y

Reads a 2-byte signed integer from the file in big-endian format.

File::readi4()

Y

Reads a 4-byte signed integer from the file in big-endian format.

File::readi8()

Y

Reads an 8-byte signed integer from the file in big-endian format.

File::readi2LSB()

Y

Reads a 2-byte signed integer from the file in little-endian format.

File::readi4LSB()

Y

Reads a 4-byte signed integer from the file in little-endian format.

File::readi8LSB()

Y

Reads an 8-byte signed integer from the file in little-endian format.

File::readu1()

Y

Reads a 1-byte unsigned integer from the file.

File::readu2()

Y

Reads a 2-byte unsigned integer from the file in big-endian format.

File::readu4()

Y

Reads a 4-byte unsigned integer from the file in big-endian format.

File::readu2LSB()

Y

Reads a 2-byte unsigned integer from the file in little-endian format.

File::readu4LSB()

Y

Reads a 4-byte unsigned integer from the file in little-endian format.

File::readBinary()

Y

Read a certain amount of data and return a binary object.

File::readLine()

Y

Reads until an EOL marker is found

File::setCharset()

N

Sets the character encoding for the file.

File::setPos()

N

Sets the current file position (in bytes).

File::setTerminalAttributes()

Y

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

File::sync()

N

Flushes the file's buffer to disk.

File::vprintf()

Y

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

File::write()

Y

Writes string or binary data to a file

File::writei1()

Y

Writes a 1-byte integer to the file.

File::writei2()

Y

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

File::writei4()

Y

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

File::writei8()

Y

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

File::writei2LSB()

Y

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

File::writei4LSB()

Y

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

File::writei8LSB()

Y

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


Table 4.24. 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.25. File Locking Constants in the Qore Namespace

Name

Description

F_RDLCK

Use for read-only locking.

F_WRLCK

Use for exclusive write locking.


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

Usage
new File([string:encoding])
Example
$f = new File("ISO-8859-1"); # specify ISO-8859-1 encoding for the file

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


Table 4.27. Return Value for File::constructor()

Return Type

Description

Object

The File object created.


4.3.2. File::destructor()

Synopsis

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

Usage
delete lvalue
Example
delete $f;
Events
EVENT_CHANNEL_CLOSED, EVENT_DELETED
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.

Usage
File::copy()
Example
$f1 = $f.copy();

Table 4.28. Arguments for File::copy()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.29. Return Value for File::copy()

Return Type

Description

n/a

The new File object created with the same character encoding specification as the original object.


4.3.4. File::chown()

Synopsis

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

Usage
File::chown(user_id, group_id)
Example
$f.chown(0, 0);

Table 4.30. Arguments for File::chown()

Argument

Type

Description

user_id

Integer

The user id of the user to change to.

group_id

Integer

The group id of the user to change to.


Table 4.31. 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.32. Exceptions Thrown by File::chown()

err

desc

FILE-CHOWN-ERROR

File is not open or the chown operation failed.


4.3.5. File::close()

Synopsis

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

Usage
File::close()
Example
$f.close();
Events
EVENT_CHANNEL_CLOSED

Table 4.33. Arguments for File::close()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


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

Return Type

Description

Integer

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.

Usage
File::f_printf(string:format, [args ...])
Example
$f.f_printf("%5s\n", "long string"); # will print "long \n", respecting the 5-character field width

Table 4.35. Arguments for File::f_printf()

Argument

Type

Description

format

String

The format string, see String Formatting for a specification.

args

Any

The remainder of the arguments are arguments to the format string.


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

Return Type

Description

Integer

Returns 0 for success, -1 for error.


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

Usage
File::f_vprintf(format_string, [arg_list])
Example
$f.f_vprintf("%5s %3d\n", ("a long string", 5000)); # outputs "a lon 500", truncating output

Table 4.38. Arguments for File::f_vprintf()

Argument

Type

Description

format

String

The format string, see String Formatting for a specification.

arg_list

List

This list will be used as the argument list or the format string.


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

Return Type

Description

Integer

Returns 0 for success, -1 for error.


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

Usage
File::getchar()
Example
$char = $f.getchar();

Table 4.41. Arguments for File::getchar()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


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

Return Type

Description

String

The single character read from the file.


4.3.9. File::getCharset()

Synopsis

Returns the character encoding for the file.

Usage
File::getCharset()
Example
$encoding = $f.getCharset();

Table 4.43. Arguments for File::getCharset()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


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.

Usage
File::getLockInfo()
Example
my $hash = $f.getLockInfo();

Table 4.45. Arguments for File::getLockInfo()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.46. 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.47. 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).

Usage
File::getPos()
Example
$pos = $f.getPos();

Table 4.48. Arguments for File::getPos()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


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

Return Type

Description

Integer

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.

Usage
File::getTerminalAttributes(termios)
Example
my $termios = new TermIOS();
$f.getTerminalAttributes($termios);

Table 4.50. Arguments for File::getTerminalAttributes()

Argument

Type

Description

termios

TermIOS

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


Table 4.51. Return Value for File::getTerminalAttributes()

Return Type

Description

Integer

Always returns 0; if an error is encountered, an exception is raised.


Table 4.52. 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::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).

Usage
File::isDataAvailable([timeout_ms])
Example
$bool = $file.isDataAvailable(0); # returns True if data is available now

Table 4.53. Arguments for File::isDataAvailable()

Argument

Type

Description

[timeout_ms]

Integer or Relative Date/Time

An optional timeout in milliseconds (1/1000 second). If no timeout is given, the method assumes a timeout of zero and returns immediately.


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

Return Type

Description

Boolean

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


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

err

desc

FILE-READ-ERROR

The file is not open.


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

Usage
File::lock(type, [start, [len]])
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);

Table 4.56. Arguments for File::lock()

Argument

Type

Description

type

Integer

Type of lock (or unlock), see File locking constants.

start

Integer

Start byte for lock, 0 is the default (start of file).

len

Integer

Length in bytes for range to lock, 0 is the default (rest of file).


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

Return Type

Description

Integer

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.58. Exceptions Thrown by File::lock()

err

desc

FILE-LOCK-ERROR

File is not open, lock length is negative, or the fcntl operation failed.


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

Usage
File::lockBlocking(type, [start, [len]])
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);

Table 4.59. Arguments for File::lockBlocking()

Argument

Type

Description

type

Integer

Type of lock (or unlock), see File locking constants.

start

Integer

Start byte for lock, 0 is the default (start of file).

len

Integer

Length in bytes for range to lock, 0 is the default (rest of file).


Table 4.60. 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.61. Exceptions Thrown by File::lockBlocking()

err

desc

FILE-LOCK-ERROR

File is not open, lock length is negative, or the fcntl operation failed.


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

Usage
File::printf(string:format, [args ...])
Example
$f.printf("%5s\n", "hello there"); # outputs "hello there\n", exceeding field width
Events
EVENT_DATA_WRITTEN

Table 4.62. Arguments for File::printf()

Argument

Type

Description

format

String

The format string, see String Formatting for a specification.

args

Any

The remainder of the arguments are arguments to the format string.


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

Return Type

Description

Integer

Returns 0 for success, -1 for error.


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

err

desc

FILE-WRITE-ERROR

File is not open.


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

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

Usage
File::open(string:filename, [integer:flags, [integer:mode, [string:charset]]])
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.65. Arguments for File::open()

Argument

Type

Description

filename

String

The Filename of the file.

flags

Integer

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.

mode

Integer

Permission bits for when the file is to be created (default: 0777)

charset

String

The name of the default character encoding for this file.


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

Return Type

Description

Integer

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


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

err

desc

FILE-OPEN-PARAMETER-ERROR

Missing filename argument.


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

Usage
File::open2(string:filename, [integer:flags, [integer:mode, [string:charset]]])
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.68. Arguments for File::open2()

Argument

Type

Description

filename

String

The Filename of the file.

flags

Integer

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.

mode

Integer

Permission bits for when the file is to be created (default: 0777)

charset

String

The name of the default character encoding for this file.


Table 4.69. Return Values for File::open2()

Return Type

Description

n/a

This method does not return any value; if an error occurs, an exception is thrown.


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

err

desc

FILE-OPEN2-PARAMETER-ERROR

Missing filename argument.

FILE-OPEN2-ERROR

Error opening the file; attempted to reopen a system file (I/O constants).


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

Usage
File::read(integer:size, [timeout_ms])
Example
$data = $f.read(-1); # read an entire text file into a variable
Events
EVENT_DATA_READ

Table 4.71. Arguments for File::read()

Argument

Type

Description

size

Integer

The number of bytes to read of the file, -1 will read the entire file.

[timeout_ms]

Integer or Relative Date/Time

A timeout period in milliseconds; if not given or negative the call will never time out and will only return when the data has been read.


Table 4.72. 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.73. Exceptions Thrown by File::read()

err

desc

FILE-READ-PARAMETER-ERROR

Missing size argument.

FILE-READ-ERROR

File is not open; timeout limit exceeded.


4.3.20. File::readi1()

Synopsis

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

Usage
File::readi1()
Example
$int = $f.readi1();
Events
EVENT_DATA_READ

Table 4.74. Arguments for File::readi1()

Argument

Type

Description

n/a

n/a

This method does not take any arguments.


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

Return Type

Description

Integer

Returns a 1-byte signed integer as read from the file in binary format.


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

err

desc

FILE-READ-ERROR

File is not open.


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

Usage
File::readi2()
Example
$int = $f.readi2();
Events
EVENT_DATA_READ

Table 4.77. Arguments for File::readi2()

Argument

Type

Description

n/a

n/a

This method does not take any arguments.


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

Return Type

Description

Integer

Returns a 2-byte signed integer as read from the file in big-endian format.


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

err

desc

FILE-READ-ERROR

File is not open.


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

Usage
File::readi4()
Example
$int = $f.readi4();
Events
EVENT_DATA_READ

Table 4.80. Arguments for File::readi4()

Argument

Type

Description

n/a

n/a

This method does not take any arguments.


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

Return Type

Description

Integer

Returns a 4-byte signed integer as read from the file in big-endian format.


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

err

desc

FILE-READ-ERROR

File is not open.


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

Usage
File::readi8()
Example
$int = $f.readi8();
Events
EVENT_DATA_READ

Table 4.83. Arguments for File::readi8()

Argument

Type

Description

n/a

n/a

This method does not take any arguments.


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

Return Type

Description

Integer

Returns a 4-byte signed integer as read from the file in big-endian format.


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

err

desc

FILE-READ-ERROR

File is not open.


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

Usage
File::readi2LSB()
Example
$int = $f.readi2LSB();
Events
EVENT_DATA_READ

Table 4.86. Arguments for File::readi2LSB()

Argument

Type

Description

n/a

n/a

This method does not take any arguments.


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

Return Type

Description

Integer

Reads a 2-byte signed integer from the file in little-endian format.


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

err

desc

FILE-READ-ERROR

File is not open.


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

Usage
File::readi4LSB()
Example
$int = $f.readi4LSB();
Events
EVENT_DATA_READ

Table 4.89. Arguments for File::readi4LSB()

Argument

Type

Description

n/a

n/a

This method does not take any arguments.


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

Return Type

Description

Integer

Reads a 4-byte signed integer from the file in little-endian format.


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

err

desc

FILE-READ-ERROR

File is not open.


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

Usage
File::readi8LSB()
Example
$int = $f.readi8LSB();
Events
EVENT_DATA_READ

Table 4.92. Arguments for File::readi8LSB()

Argument

Type

Description

n/a

n/a

This method does not take any arguments.


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

Return Type

Description

Integer

Reads a 4-byte signed integer from the file in little-endian format.


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

err

desc

FILE-READ-ERROR

File is not open.


4.3.27. File::readu1()

Synopsis

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

Usage
File::readu1()
Example
$int = $f.readu1();
Events
EVENT_DATA_READ

Table 4.95. Arguments for File::readu1()

Argument

Type

Description

n/a

n/a

This method does not take any arguments.


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

Return Type

Description

Integer

Returns a 1-byte unsigned integer as read from the file in binary format.


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

err

desc

FILE-READ-ERROR

File is not open.


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

Usage
File::readu2()
Example
$int = $f.readu2();
Events
EVENT_DATA_READ

Table 4.98. Arguments for File::readu2()

Argument

Type

Description

n/a

n/a

This method does not take any arguments.


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

Return Type

Description

Integer

Returns a 2-byte signed integer as read from the file in big-endian format.


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

err

desc

FILE-READ-ERROR

File is not open.


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

Usage
File::readu4()
Example
$int = $f.readu4();
Events
EVENT_DATA_READ

Table 4.101. Arguments for File::readu4()

Argument

Type

Description

n/a

n/a

This method does not take any arguments.


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

Return Type

Description

Integer

Returns a 4-byte signed integer as read from the file in big-endian format.


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

err

desc

FILE-READ-ERROR

File is not open.


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

Usage
File::readu2LSB()
Example
$int = $f.readu2LSB();
Events
EVENT_DATA_READ

Table 4.104. Arguments for File::readu2LSB()

Argument

Type

Description

n/a

n/a

This method does not take any arguments.


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

Return Type

Description

Integer

Reads a 2-byte signed integer from the file in little-endian format.


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

err

desc

FILE-READ-ERROR

File is not open.


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

Usage
File::readu4LSB()
Example
$int = $f.readu4LSB();
Events
EVENT_DATA_READ

Table 4.107. Arguments for File::readu4LSB()

Argument

Type

Description

n/a

n/a

This method does not take any arguments.


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

Return Type

Description

Integer

Reads a 4-byte unsigned integer from the file in little-endian format.


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

err

desc

FILE-READ-ERROR

File is not open.


4.3.32. File::readBinary()

Synopsis

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

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.

Usage
File::readBinary(integer:size, [timeout_ms])
Example
$data = $f.readBinary(-1); # reads an entire binary file into a variable
Events
EVENT_DATA_READ

Table 4.110. Arguments for File::readBinary()

Argument

Type

Description

size

Integer

The number of bytes to read of the file.

[timeout_ms]

Integer or Relative Date/Time

A timeout period in milliseconds; if not given or negative the call will never time out and will only return when the data has been read.


Table 4.111. 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.112. Exceptions Thrown by File::readBinary()

err

desc

FILE-READ-BINARY-PARAMETER-ERROR

Missing size argument.

FILE-READ-ERROR

File is not open; timeout limit exceeded.


4.3.33. File::readLine()

Synopsis

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

Usage
File::readLine()
Example
while (exists (my $line = $f.readLine()))
{
    # remove EOL marker
    chomp $line;
    # print out the line just read
    printf("%s\n", $line);
}
Events
EVENT_DATA_READ

Table 4.113. Arguments for File::readLine()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.114. 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.115. Exceptions Thrown by File::readLine()

err

desc

FILE-READLINE-ERROR

File is not open.


4.3.34. File::setCharset()

Synopsis

Sets the characte encoding for the file.

Usage
File::setCharset(string:encoding)
Example
$f.setCharset("ISO-8859-1");

Table 4.116. Arguments for File::setCharset()

Argument

Type

Description

encoding

String

The character encoding for the file.


Table 4.117. Return Value for File::setCharset()

Return Type

Description

n/a

This method does not return any value.


4.3.35. File::setPos()

Synopsis

Sets the current file position in bytes starting with zero.

Usage
File::setPos(integer:position)
Example
$f.setPos(0); # go to the beginning of the file

Table 4.118. Arguments for File::setPos()

Argument

Type

Description

position

Integer

The position in the file as offset from position 0.


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

Return Type

Description

Integer

Returns the new offset in the file, -1 for error.


4.3.36. File::setTerminalAttributes()

Synopsis

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

Usage
File::setTerminalAttributes(termios)
Example
my $termios = new TermIOS();
my $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.120. Arguments for File::setTerminalAttributes()

Argument

Type

Description

termios

TermIOS

Sets the current terminal attributes for the file from the TermIOS object passed.


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

Return Type

Description

Integer

Always returns 0; if an error is encountered, an exception is raised.


Table 4.122. 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.37. File::sync()

Synopsis

Flushes the file's buffer to disk.

Usage
File::sync()
Example
$f.sync();

Table 4.123. Arguments for File::sync()

Argument

Type

Description

n/a

n/a

This method does not take any arguments.


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

Return Type

Description

Integer

Returns 0 for success, -1 for error.


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

Usage
File::vprintf(string:format, [arg_list])
Example
$f.vprintf("%5s\n", "hello");
Events
EVENT_DATA_WRITTEN

Table 4.125. Arguments for File::vprintf()

Argument

Type

Description

format

String

The format string, see String Formatting for a specification.

arg_list

List

This list will be used as the argument list or the format string.


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

Return Type

Description

Integer

Returns 0 for success, -1 for error.


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

err

desc

FILE-WRITE-ERROR

File is not open.


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

Usage
File::write(arg)
Example
$f.write($data);
Events
EVENT_DATA_WRITTEN

Table 4.128. Arguments for File::write()

Argument

Type

Description

arg

String or Binary

Writes the data to the file.


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

Return Type

Description

Integer

Returns 0 for success, -1 for error.


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

err

desc

FILE-WRITE-PARAMETER-ERROR

Missing string or binary argument.

FILE-WRITE-ERROR

File is not open.


4.3.40. File::writei1()

Synopsis

Writes a 1-byte integer to the file.

Usage
File::writei1(integer)
Example
$f.writei1($val);
Events
EVENT_DATA_WRITTEN

Table 4.131. Arguments for File::writei1()

Argument

Type

Description

integer

Integer

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


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

Return Type

Description

Integer

Returns 0 for success, -1 for error.


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

err

desc

FILE-WRITE-ERROR

File is not open.


4.3.41. File::writei2()

Synopsis

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

Usage
File::writei2(integer)
Example
$f.writei2($val);
Events
EVENT_DATA_WRITTEN

Table 4.134. Arguments for File::writei2()

Argument

Type

Description

integer

Integer

The integer to write; writes a 2-byte integer in big-endian format.


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

Return Type

Description

Integer

Returns 0 for success, -1 for error.


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

err

desc

FILE-WRITE-ERROR

File is not open.


4.3.42. File::writei4()

Synopsis

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

Usage
File::writei4(integer)
Example
$f.writei4($val);
Events
EVENT_DATA_WRITTEN

Table 4.137. Arguments for File::writei4()

Argument

Type

Description

integer

Integer

The integer to write; writes a 4-byte integer in big-endian format.


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

Return Type

Description

Integer

Returns 0 for success, -1 for error.


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

err

desc

FILE-WRITE-ERROR

File is not open.


4.3.43. File::writei8()

Synopsis

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

Usage
File::writei8(integer)
Example
$f.writei8($val);
Events
EVENT_DATA_WRITTEN

Table 4.140. Arguments for File::writei8()

Argument

Type

Description

integer

Integer

The integer to write; writes an 8-byte integer in big-endian format.


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

Return Type

Description

Integer

Returns 0 for success, -1 for error.


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

err

desc

FILE-WRITE-ERROR

File is not open.


4.3.44. File::writei2LSB()

Synopsis

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

Usage
File::writei2LSB(integer)
Example
$f.writei2LSB($val);
Events
EVENT_DATA_WRITTEN

Table 4.143. Arguments for File::writei2LSB()

Argument

Type

Description

integer

Integer

The integer to write; writes a 2-byte integer in little-endian format.


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

Return Type

Description

Integer

Returns 0 for success, -1 for error.


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

err

desc

FILE-WRITE-ERROR

File is not open.


4.3.45. File::writei4LSB()

Synopsis

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

Usage
File::writei4LSB(integer)
Example
$f.writei4LSB($val);
Events
EVENT_DATA_WRITTEN

Table 4.146. Arguments for File::writei4LSB()

Argument

Type

Description

integer

Integer

The integer to write; writes a 4-byte integer in little-endian format.


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

Return Type

Description

Integer

Returns 0 for success, -1 for error.


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

err

desc

FILE-WRITE-ERROR

File is not open.


4.3.46. File::writei8LSB()

Synopsis

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

Usage
File::writei8LSB(integer)
Example
$f.writei8LSB($val);
Events
EVENT_DATA_WRITTEN

Table 4.149. Arguments for File::writei8LSB()

Argument

Type

Description

integer

Integer

The integer to write; writes an 8-byte integer in little-endian format.


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

Return Type

Description

Integer

Returns 0 for success, -1 for error.


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

err

desc

FILE-WRITE-ERROR

File is not open.