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 |
---|---|
Raised when data is read from the file. | |
Raised when data is written to the file. | |
Raised when the file is closed. | |
Raised when the object being monitored is deleted. | |
Raised right before an attempt to open a file is made. | |
Raised when the file has been successfully opened. |
Table 4.23. File Method Overview
Method | Except? | Description |
---|---|---|
N | Creates the object and optionally sets the file's character encoding. | |
N | Closes the file if it is open and destroys the file object. | |
N | Creates a new file object with the same character encoding specification as the original, otherwise no other information is copied. | |
N | Changes the user and group owners of the file on the filesystem (if the current user has sufficient permission to do so). | |
N | Closes the file object | |
Y | Writes a formatted string to a file, enforces hard field limits. | |
Y | Writes a formatted string to a file, where the second argument is the formatting argument list, enforces hard field limits. | |
N | Reads one character from the file | |
N | Returns the character encoding for the file | |
Y | Returns a hash of lock information. | |
N | Gets the current file position (in bytes) | |
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. | |
Y | Returns true if there is data available for reading from the file within the timeout period. | |
Y | Attempts to lock the file according to the arguments passed, does not block. | |
Y | Attempts to lock the file according to the arguments passed, blocking. | |
Y | Opens a file in a particular mode, returns an error code on failure. | |
Y | Opens a file in a particular mode; throws an exception on failure. | |
Y | Writes a formatted string to a file. | |
Y | Reads a certain number of bytes from the file within an optional timeout period and returns a string of the data read. | |
Y | Reads a certain number of bytes from the file within an optional timeout period and returns binary data. | |
Y | Reads a 1-byte signed integer from the file. | |
Y | Reads a 2-byte signed integer from the file in big-endian format. | |
Y | Reads a 4-byte signed integer from the file in big-endian format. | |
Y | Reads an 8-byte signed integer from the file in big-endian format. | |
Y | Reads a 2-byte signed integer from the file in little-endian format. | |
Y | Reads a 4-byte signed integer from the file in little-endian format. | |
Y | Reads an 8-byte signed integer from the file in little-endian format. | |
Y | Reads a 1-byte unsigned integer from the file. | |
Y | Reads a 2-byte unsigned integer from the file in big-endian format. | |
Y | Reads a 4-byte unsigned integer from the file in big-endian format. | |
Y | Reads a 2-byte unsigned integer from the file in little-endian format. | |
Y | Reads a 4-byte unsigned integer from the file in little-endian format. | |
Y | Read a certain amount of data and return a binary object. | |
Y | Reads until an EOL marker is found | |
N | Sets the character encoding for the file. | |
N | Sets the current file position (in bytes). | |
Y | Sets the current terminal attributes for the file from the TermIOS object passed; does not change the object passed. | |
N | Flushes the file's buffer to disk. | |
Y | Writes a formatted string to a file, where the second argument is the formatting argument list. | |
Y | Writes string or binary data to a file | |
Y | Writes a 1-byte integer to the file. | |
Y | Writes a 2-byte integer in big-endian format. | |
Y | Writes a 4-byte integer in big-endian format. | |
Y | Writes an 8-byte integer in big-endian format. | |
Y | Writes a 2-byte integer in little-endian format. | |
Y | Writes a 4-byte integer in little-endian format. | |
Y | Writes an 8-byte integer in little-endian format. |
Table 4.24. File Constants in the Qore Namespace
Name | Description |
---|---|
| Open the file read-only. |
| Open the file write-only. |
| Create the file if it doesn't exist. |
| Open the file in append mode. |
| Open for reading and writing. |
| Truncate the size to zero. |
Table 4.25. File Locking Constants in the Qore Namespace
Name | Description |
---|---|
| Use for read-only locking. |
| Use for exclusive write locking. |
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).
new File([string:encoding]
)
$f = new File("ISO-8859-1"); # specify ISO-8859-1 encoding for the file
Table 4.26. Arguments for File::constructor()
Argument | Type | Description |
---|---|---|
| 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. |
Closes the file if it's open and destroys the File object.
delete lvalue
delete $f;
EVENT_CHANNEL_CLOSED, EVENT_DELETED
EVENT_CHANNEL_CLOSED, EVENT_DELETED
Creates a new File object with the same character encoding specification as the original.
File::copy()
$f1 = $f.copy();
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. |
Changes the file's user and group owner (if the user has sufficient permissions to do so).
File::chown(user_id, group_id
)
$f.chown(0, 0);
Table 4.30. Arguments for File::chown()
Argument | Type | Description |
---|---|---|
| Integer | The user id of the user to change to. |
| 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 is not open or the chown operation failed. |
Closes the file object if it's open. Note that this is automatically called by File::destructor().
File::close()
$f.close();
EVENT_CHANNEL_CLOSED
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) |
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.
File::f_printf(string:format, [args ...]
)
$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 |
---|---|---|
| String | The format string, see String Formatting for a specification. |
| 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. |
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.
File::f_vprintf(format_string, [arg_list]
)
$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 |
---|---|---|
| String | The format string, see String Formatting for a specification. |
| 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. |
Reads one character from the file and returns it as a one-character string.
File::getchar()
$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. |
Returns the character encoding for the file.
File::getCharset()
$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. |
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.
File::getLockInfo()
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 is not open or the fcntl operation failed. |
Gets the current file position as an integer giving the offset in bytes from the beginning of the file (starting from zero).
File::getPos()
$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. |
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.
File::getTerminalAttributes(termios
)
my $termios = new TermIOS(); $f.getTerminalAttributes($termios);
Table 4.50. Arguments for File::getTerminalAttributes()
Argument | Type | Description |
---|---|---|
| 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 |
---|---|
| The file is not open. |
| Error reading terminal attributes from the file descriptor. |
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
).
File::isDataAvailable([timeout_ms]
)
$bool = $file.isDataAvailable(0); # returns True if data is available now
Table 4.53. Arguments for File::isDataAvailable()
Argument | Type | Description |
---|---|---|
| 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. |
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().
File::lock(type, [start, [len]]
)
# 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 |
---|---|---|
| Integer | Type of lock (or unlock), see File locking constants. |
| Integer | Start byte for lock, 0 is the default (start of file). |
| 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 is not open, lock length is negative, or the fcntl operation failed. |
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().
File::lockBlocking(type, [start, [len]]
)
# 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 |
---|---|---|
| Integer | Type of lock (or unlock), see File locking constants. |
| Integer | Start byte for lock, 0 is the default (start of file). |
| 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 is not open, lock length is negative, or the fcntl operation failed. |
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.
File::printf(string:format, [args ...]
)
$f.printf("%5s\n", "hello there"); # outputs "hello there\n", exceeding field width
EVENT_DATA_WRITTEN
Table 4.62. Arguments for File::printf()
Argument | Type | Description |
---|---|---|
| String | The format string, see String Formatting for a specification. |
| 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. |
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().
File::open(string:filename, [integer:flags, [integer:mode, [string:charset]]]
)
# 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");
EVENT_OPEN_FILE, EVENT_FILE_OPENED
Table 4.65. Arguments for File::open()
Argument | Type | Description |
---|---|---|
| String | The Filename of the file. |
| 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. |
| Integer | Permission bits for when the file is to be created (default: 0777) |
| 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 |
---|---|
| Missing filename argument. |
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().
File::open2(string:filename, [integer:flags, [integer:mode, [string:charset]]]
)
# 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");
EVENT_OPEN_FILE, EVENT_FILE_OPENED
Table 4.68. Arguments for File::open2()
Argument | Type | Description |
---|---|---|
| String | The Filename of the file. |
| 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. |
| Integer | Permission bits for when the file is to be created (default: 0777) |
| 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 |
---|---|
| Missing filename argument. |
| Error opening the file; attempted to reopen a system file (I/O constants). |
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.
File::read(integer:size, [timeout_ms]
)
$data = $f.read(-1); # read an entire text file into a variable
EVENT_DATA_READ
Table 4.71. Arguments for File::read()
Argument | Type | Description |
---|---|---|
| Integer | The number of bytes to read of the file, -1 will read the entire file. |
| 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 |
---|---|
| Missing size argument. |
| File is not open; timeout limit exceeded. |
Reads a 1-byte signed integer from the file and returns the integer value read.
File::readi1()
$int = $f.readi1();
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. |
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.
File::readi2()
$int = $f.readi2();
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. |
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.
File::readi4()
$int = $f.readi4();
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. |
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.
File::readi8()
$int = $f.readi8();
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. |
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.
File::readi2LSB()
$int = $f.readi2LSB();
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. |
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.
File::readi4LSB()
$int = $f.readi4LSB();
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. |
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.
File::readi8LSB()
$int = $f.readi8LSB();
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. |
Reads a 1-byte unsigned integer from the file and returns the integer value read.
File::readu1()
$int = $f.readu1();
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. |
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.
File::readu2()
$int = $f.readu2();
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. |
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.
File::readu4()
$int = $f.readu4();
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. |
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.
File::readu2LSB()
$int = $f.readu2LSB();
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. |
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.
File::readu4LSB()
$int = $f.readu4LSB();
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. |
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.
File::readBinary(integer:size, [timeout_ms]
)
$data = $f.readBinary(-1); # reads an entire binary file into a variable
EVENT_DATA_READ
Table 4.110. Arguments for File::readBinary()
Argument | Type | Description |
---|---|---|
| Integer | The number of bytes to read of the file. |
| 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 |
---|---|
| Missing size argument. |
| File is not open; timeout limit exceeded. |
Reads until an EOL marker is found and returns a string containing the EOL marker. Returns NOTHING on end of file.
File::readLine()
while (exists (my $line = $f.readLine())) { # remove EOL marker chomp $line; # print out the line just read printf("%s\n", $line); }
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. |
Sets the characte encoding for the file.
File::setCharset(string:encoding
)
$f.setCharset("ISO-8859-1");
Table 4.116. Arguments for File::setCharset()
Argument | Type | Description |
---|---|---|
| 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. |
Sets the current file position in bytes starting with zero.
File::setPos(integer:position
)
$f.setPos(0); # go to the beginning of the file
Table 4.118. Arguments for File::setPos()
Argument | Type | Description |
---|---|---|
| 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. |
Sets the terminal attributes for the file from the TermIOS object passed; does not change the object passed.
File::setTerminalAttributes(termios
)
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.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 |
---|---|
| The file is not open. |
| Error setting terminal attributes on the file descriptor. |
Flushes the file's buffer to disk.
File::sync()
$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. |
Writes a formatted string to a file, where the first argument is a format string,and the second argument is the formatting argument list.
File::vprintf(string:format, [arg_list]
)
$f.vprintf("%5s\n", "hello");
EVENT_DATA_WRITTEN
Table 4.125. Arguments for File::vprintf()
Argument | Type | Description |
---|---|---|
| String | The format string, see String Formatting for a specification. |
| 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. |
Writes string or binary data to a file. String data will be converted to the file's character encoding if necessary before writing.
File::write(arg
)
$f.write($data);
EVENT_DATA_WRITTEN
Table 4.128. Arguments for File::write()
Argument | Type | Description |
---|---|---|
| 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 |
---|---|
| Missing string or binary argument. |
| File is not open. |
Writes a 1-byte integer to the file.
File::writei1(integer
)
$f.writei1($val);
EVENT_DATA_WRITTEN
Table 4.131. Arguments for File::writei1()
Argument | Type | Description |
---|---|---|
| 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. |
Writes a 2-byte integer in big-endian format.
File::writei2(integer
)
$f.writei2($val);
EVENT_DATA_WRITTEN
Table 4.134. Arguments for File::writei2()
Argument | Type | Description |
---|---|---|
| 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. |
Writes a 4-byte integer in big-endian format.
File::writei4(integer
)
$f.writei4($val);
EVENT_DATA_WRITTEN
Table 4.137. Arguments for File::writei4()
Argument | Type | Description |
---|---|---|
| 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. |
Writes an 8-byte integer in big-endian format.
File::writei8(integer
)
$f.writei8($val);
EVENT_DATA_WRITTEN
Table 4.140. Arguments for File::writei8()
Argument | Type | Description |
---|---|---|
| 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. |
Writes a 2-byte integer in little-endian format.
File::writei2LSB(integer
)
$f.writei2LSB($val);
EVENT_DATA_WRITTEN
Table 4.143. Arguments for File::writei2LSB()
Argument | Type | Description |
---|---|---|
| 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. |
Writes a 4-byte integer in little-endian format.
File::writei4LSB(integer
)
$f.writei4LSB($val);
EVENT_DATA_WRITTEN
Table 4.146. Arguments for File::writei4LSB()
Argument | Type | Description |
---|---|---|
| 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. |
Writes an 8-byte integer to the file in little-endian (LSB) format.
File::writei8LSB(integer
)
$f.writei8LSB($val);
EVENT_DATA_WRITTEN
Table 4.149. Arguments for File::writei8LSB()
Argument | Type | Description |
---|---|---|
| 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. |