Qore Programming Language Reference Manual: Qore::File Class Reference

Qore Programming Language Reference Manual 0.8.11

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes

- Class List
- Class Index
- Class Hierarchy
- Class Members

All Classes Namespaces Functions Variables Groups Pages
Public Member Functions | Static Public Member Functions | List of all members
Qore::File Class Reference

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

Inheritance diagram for Qore::File:
[legend]

## Public Member Functions
nothing | chown (softint uid, softint gid=-1)
| Changes the user and group owners of the file on the filesystem (if the current user has sufficient permission to do so) More...
| constructor (*string encoding)
| Creates the File object. More...
| copy ()
| Creates a new File object with the same character encoding specification as the original, otherwise no other information is copied. More...
| destructor ()
| Closes the File if it is open and destroys the File object. More...
int | f_printf (string fmt,...)
| Writes a formatted string with hard field widths to the file. More...
int | f_printf ()
| This method variant does nothing except return a constant 0; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
int | f_vprintf (string fmt, any fmt_args)
| Writes a formatted string with hard field widths to a file, where the second argument is the formatting argument list. More...
int | f_vprintf ()
| This method variant does nothing except return a constant 0; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
string | getCharset ()
| Returns the character encoding for the File. More...
hash | getLockInfo ()
| Returns a hash of lock information. More...
nothing | getTerminalAttributes (TermIOS termios)
| Saves the current terminal attributes for the file in the TermIOS object passed; changes the object passed as an argument to reflect the terminal attributes as set for the File. More...
TermIOS | getTerminalAttributes ()
| Returns the current terminal attributes for the file as a TermIOS object returned as the return value. More...
int | lock (softint type=F_RDLCK, softint start=0, softint len=0, softint whence=SEEK_SET)
| Attempts to lock the file according to the arguments passed, does not block. More...
nothing | lockBlocking (softint type=F_RDLCK, softint start=0, softint len=0, softint whence=SEEK_SET)
| Attempts to lock the file according to the arguments passed, blocking. More...
int | open (string path, softint flags=O_RDONLY, softint mode=0666, *string encoding)
| Opens a File in a particular mode, returns an error code on failure. More...
nothing | open2 (string path, softint flags=O_RDONLY, softint mode=0666, *string encoding)
| Opens a file in a particular mode; throws an exception on failure. More...
int | print (string data)
| Writes string data to a file; string data is converted to the File's character encoding if necessary before writing. More...
int | printf (string fmt,...)
| Writes a formatted string with soft field widths to the file. More...
int | printf ()
| This method variant does nothing except return a constant 0; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
nothing | setCharset (*string encoding)
| Sets the character encoding for the file; if called with no argument, the default encoding is set. More...
nothing | setTerminalAttributes (softint action=TCSANOW, TermIOS termios)
| Sets the current terminal attributes for the File from the TermIOS object passed; does not change the object passed. More...
int | sync ()
| Flushes the file's buffer to disk. More...
int | vprintf (string fmt, any fmt_args)
| Writes a formatted string with soft field widths to a file, where the second argument is the formatting argument list. More...
int | vprintf ()
| This method variant does nothing except return a constant 0; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
int | write (binary data)
| Writes binary data to a file. More...
int | write (string data)
| Writes string data to a file; string data is converted to the File's character encoding if necessary before writing. More...
int | writei1 (int c)
| Writes a 1-byte integer to the file. More...
int | writei2 (int s)
| Writes a 2-byte (16 bit) integer to the file in binary big-endian format. More...
int | writei2LSB (int s)
| Writes a 2-byte (16 bit) integer to the file in binary little-endian format. More...
int | writei4 (int i)
| Writes a 4-byte (32 bit) integer to the file in binary big-endian format. More...
int | writei4LSB (int i)
| Writes a 4-byte (32 bit) integer to the file in binary little-endian format. More...
int | writei8 (int i)
| Writes an 8-byte (64 bit) integer to the file in binary big-endian format. More...
int | writei8LSB (int i)
| Writes an 8-byte (64 bit) integer to the file in binary little-endian format. More...
Public Member Functions inherited from Qore::ReadOnlyFile
int | close ()
| Closes the ReadOnlyFile object. More...
| constructor (string path, *string encoding)
| Creates the ReadOnlyFile object. More...
| copy ()
| Creates a new ReadOnlyFile object with the same character encoding specification as the original, otherwise no other information is copied. More...
| destructor ()
| Closes the ReadOnlyFile if it is open and destroys the ReadOnlyFile object. More...
string | getEncoding ()
| Returns the character encoding for the ReadOnlyFile. More...
*string | getFileName ()
| returns the file path/name used to open the file if the file is open, otherwise NOTHING More...
int | getPos ()
| Returns the current file position as an integer giving the offset in bytes from the beginning of the file (starting from zero) More...
*string | getchar ()
| Reads one character from the file and returns it as a string; returns NOTHING if no data can be read from the file. More...
hash | hstat ()
| Returns a Stat Hash about the file's status or throws an exception if any errors occur. More...
bool | isDataAvailable (timeout timeout_ms=0)
| Returns True if there is data available for reading from the file within the timeout period. More...
bool | isOpen ()
| returns True if the File is open, False if not More...
bool | isTty ()
| returns True if the File is connected to a terminal device, False if not More...
nothing | open (string path, *string encoding)
| Opens a file in a particular mode; throws an exception on failure. More...
*string | read (softint size, timeout timeout_ms=-1)
| Reads a certain number of bytes from the ReadOnlyFile within an optional timeout period and returns a string of the data read or NOTHING if no data can be read. More...
*binary | readBinary (softint size, timeout timeout_ms=-1)
| Reads a certain number of bytes from the file within an optional timeout period and returns a binary object of the data read or NOTHING if no data can be read. More...
*string | readLine (bool incl_eol=True, *string eol)
| Reads until an EOL marker is found and returns the string read or NOTHING if no data can be read. More...
*int | readi1 ()
| Reads a 1-byte signed integer from the file in binary format or NOTHING if no data can be read. More...
*int | readi2 ()
| Reads a 2-byte (16 bit) signed integer from the file in binary big-endian format or NOTHING if no data can be read. More...
*int | readi2LSB ()
| Reads a 2-byte (16 bit) signed integer from the file in binary little-endian format or NOTHING if no data can be read. More...
*int | readi4 ()
| Reads a 4-byte (32 bit) signed integer from the file in binary big-endian format or NOTHING if no data can be read. More...
*int | readi4LSB ()
| Reads a 4-byte (32 bit) signed integer from the file in binary little-endian format or NOTHING if no data can be read. More...
*int | readi8 ()
| Reads an 8-byte (64 bit) signed integer from the file in binary big-endian format or NOTHING if no data can be read. More...
*int | readi8LSB ()
| Reads an 8-byte (64 bit) signed integer from the file in binary little-endian format or NOTHING if no data can be read. More...
*int | readu1 ()
| Reads a 1-byte unsigned integer from the ReadOnlyFile in binary format or NOTHING if no data can be read. More...
*int | readu2 ()
| Reads a 2-byte (16 bit) unsigned integer from the ReadOnlyFile in binary big-endian format or NOTHING if no data can be read. More...
*int | readu2LSB ()
| Reads a 2-byte (16 bit) unsigned integer from the file in binary little-endian format or NOTHING if no data can be read. More...
*int | readu4 ()
| Reads a 4-byte (32 bit) unsigned integer from the file in big-endian format or NOTHING if no data can be read. More...
*int | readu4LSB ()
| Reads a 4-byte (32 bit) unsigned integer from the file in binary little-endian format or NOTHING if no data can be read. More...
nothing | setEncoding (*string encoding)
| Sets the character encoding for the ReadOnlyFile; if called with no argument, the default encoding is set. More...
nothing | setEventQueue (Qore::Thread::Queue queue)
| Sets a Queue object to receive file events. More...
nothing | setEventQueue ()
| Removes any Queue object from the ReadOnlyFile object so that file events are no longer added to the Queue. More...
int | setPos (int pos=0)
| Sets the current file position (in bytes from the beginning of the file) More...
list | stat ()
| Returns a Stat List about the file's status or throws an exception if any errors occur. More...
hash | statvfs ()
| Returns a Filesystem Status Hash about the file's filesystem status or throws an exception if any errors occur. More...

## Static Public Member Functions
static hash | hlstat (string path)
| Returns a Stat Hash about the file's status (does not follow symbolic links) or throws an exception if any errors occur. More...
static hash | hstat (string path)
| Returns a Stat Hash about the file's status (follows symbolic links) or throws an exception if any errors occur. More...
static list | lstat (string path)
| Returns a Stat List about the given path's status (does not follow symbolic links) or throws an exception if any errors occur. More...
static list | stat (string path)
| Returns a Stat List about the file's status (follows symbolic links) or throws an exception if any errors occur. More...
static hash | statvfs (string path)
| Returns a Filesystem Status Hash about filesystem status of the given path; throws an exception if any errors occur. More...
Static Public Member Functions inherited from Qore::ReadOnlyFile
static binary | readBinaryFile (string path)
| returns the contents of a binary file as a binary object More...
static string | readTextFile (string path, *string encoding)
| returns the contents of a text file as a string optionally tagged with the given character encoding More...

## Detailed Description

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

Restrictions:
  Qore::PO_NO_FILESYSTEM

Note
  This class is not available with the PO_NO_FILESYSTEM parse option

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

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

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

File Events

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

## Member Function Documentation

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

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

Platform Availability:
  Qore::Option::HAVE_UNIX_FILEMGT

Example:
  $f.chown(0, 0);

Parameters

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

Exceptions

  FILE-CHOWN-ERROR | File is not open or the chown operation failed
  MISSING-FEATURE-ERROR | this method is not supported on this platform; check Option::HAVE_UNIX_FILEMGT before calling this method to avoid this exception
  ILLEGAL-EXPRESSION | this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

Qore::File::constructor | ( | *string | encoding | ) |

Creates the File object.

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

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

Parameters

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

Exceptions

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

See Also
  File::open(), File::open2()

Qore::File::copy | ( |  | ) |

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

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

Qore::File::destructor | ( |  | ) |

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

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

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

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

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

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

Events:
  EVENT_DATA_WRITTEN

Parameters

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

Returns
  the number of bytes written

Exceptions

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

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

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

int Qore::File::f_printf | ( |  | ) |

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

Code Flags:
  RUNTIME_NOOP

Returns
  a constant 0

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

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

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

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

Events:
  EVENT_DATA_WRITTEN

Parameters

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

Returns
  the number of bytes written

Exceptions

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

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

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

int Qore::File::f_vprintf | ( |  | ) |

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

Code Flags:
  RUNTIME_NOOP

Returns
  a constant 0

string Qore::File::getCharset | ( |  | ) |

Returns the character encoding for the File.

Code Flags:
  CONSTANT

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

Returns
  the character encoding for the File

hash Qore::File::getLockInfo | ( |  | ) |

Returns a hash of lock information.

Platform Availability:
  Qore::Option::HAVE_FILE_LOCKING

Code Flags:
  RET_VALUE_ONLY

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

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

Exceptions

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

nothing Qore::File::getTerminalAttributes | ( | TermIOS | termios | ) |

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

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

Platform Availability:
  Qore::Option::HAVE_TERMIOS

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

Parameters

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

Exceptions

  FILE-OPERATION-ERROR | the File is not open
  TERMIOS-GET-ERROR | error reading terminal attributes from the file descriptor (ex: not a TTY)
  MISSING-FEATURE-ERROR | this method is not supported on this platform; check Option::HAVE_TERMIOS before calling this method to avoid this exception
  ILLEGAL-EXPRESSION | this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

TermIOS Qore::File::getTerminalAttributes | ( |  | ) |

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

Platform Availability:
  Qore::Option::HAVE_TERMIOS

Example:
  my TermIOS $termios = stdin.getTerminalAttributes();

Returns
  the current terminal attributes for the File

Exceptions

  FILE-OPERATION-ERROR | the File is not open
  TERMIOS-GET-ERROR | error reading terminal attributes from the file descriptor (ex: not a TTY)
  MISSING-FEATURE-ERROR | this method is not supported on this platform; check Option::HAVE_TERMIOS before calling this method to avoid this exception
  ILLEGAL-EXPRESSION | this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

Since
  Qore 0.8.7

static hash Qore::File::hlstat | ( | string | path | ) |
| static

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

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

Restrictions:
  Qore::PO_NO_FILESYSTEM

Example:
  my hash $h = File::hstat($path);

Parameters

  path | the file to stat()

Returns
  a Stat Hash about the file's status

Exceptions

  FILE-HSTAT-ERROR | stat() call failed

See Also
  hstat() for a normal function returns NOTHING instead of throwing an exception when errors occur
  File Stat Constants

static hash Qore::File::hstat | ( | string | path | ) |
| static

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

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

Restrictions:
  Qore::PO_NO_FILESYSTEM

Example:
  my hash $h = File::hstat($path);

Parameters

  path | the file to stat()

Returns
  a Stat Hash about the file's status

Exceptions

  FILE-HSTAT-ERROR | stat() call failed

See Also
  hstat() for a normal function returns NOTHING instead of throwing an exception when errors occur
  File Stat Constants

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

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

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

Platform Availability:
  Qore::Option::HAVE_FILE_LOCKING

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

Parameters

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

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

Exceptions

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

See Also
  File::lockBlocking() for a blocking version of this method

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

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

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

Platform Availability:
  Qore::Option::HAVE_FILE_LOCKING

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

Parameters

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

Exceptions

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

See Also
  File::lockBlocking() for a blocking version of this method

static list Qore::File::lstat | ( | string | path | ) |
| static

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

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

Restrictions:
  Qore::PO_NO_FILESYSTEM

Example:
  my int $mode = File::lstat($path)[2];

Parameters

  path | the file to stat()

Returns
  a list of file status values for the given file

Exceptions

  FILE-LSTAT-ERROR | stat() call failed

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

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

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

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

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

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

Events:
  EVENT_OPEN_FILE, EVENT_FILE_OPENED

Parameters

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

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

Exceptions

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

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

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

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

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

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

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

Example:
  # open a file for writing, truncate data if already exists, create the file if doesn't exist
  # set 0644 permissions, and convert all string data to ISO-8859-1 encoding
  try {
  $f.open2($fn, O_CREAT | O_TRUNC | O_WRONLY, 0644, "ISO-8859-1");
  }
  catch (hash $ex) {
  printf("%s: %s: %s\n", $fn, $ex.err, $ex.desc);
  }

Events:
  EVENT_OPEN_FILE, EVENT_FILE_OPENED

Parameters

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

Exceptions

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

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

int Qore::File::print | ( | string | data | ) |

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

Example:
  $f.print($data);

Events:
  EVENT_DATA_WRITTEN

Parameters

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

Returns
  the number of bytes written

Exceptions

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

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

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

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

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

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

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

Events:
  EVENT_DATA_WRITTEN

Parameters

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

Returns
  the number of bytes written

Exceptions

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

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

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

int Qore::File::printf | ( |  | ) |

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

Code Flags:
  RUNTIME_NOOP

Returns
  a constant 0

nothing Qore::File::setCharset | ( | *string | encoding | ) |

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

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

Parameters

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

Exceptions

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

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

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

Platform Availability:
  Qore::Option::HAVE_TERMIOS

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

Parameters

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

Exceptions

  FILE-OPERATION-ERROR | the File is not open
  TERMIOS-SET-ERROR | error setting terminal attributes on the file descriptor
  MISSING-FEATURE-ERROR | this method is not supported on this platform; check Option::HAVE_TERMIOS before calling this method to avoid this exception
  ILLEGAL-EXPRESSION | this exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

static list Qore::File::stat | ( | string | path | ) |
| static

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

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

Restrictions:
  Qore::PO_NO_FILESYSTEM

Example:
  my int $mode = File::stat($path)[2];

Parameters

  path | the file to stat()

Returns
  a list of file status values for the given file

Exceptions

  FILE-STAT-ERROR | stat() call failed

See Also
  File Stat Constants

static hash Qore::File::statvfs | ( | string | path | ) |
| static

Returns a Filesystem Status Hash about filesystem status of the given path; throws an exception if any errors occur.

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

Platform Availability:
  Qore::Option::HAVE_STATVFS

Restrictions:
  Qore::PO_NO_FILESYSTEM

Example:
  my hash $h = File::statvfs($path);

Parameters

  path | the path to the filesystem to check

Returns
  a Filesystem Status Hash about the filesystem where the file resides

Exceptions

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

int Qore::File::sync | ( |  | ) |

Flushes the file's buffer to disk.

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

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

Exceptions

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

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

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

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

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

Events:
  EVENT_DATA_WRITTEN

Parameters

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

Returns
  the number of bytes written

Exceptions

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

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

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

int Qore::File::vprintf | ( |  | ) |

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

Code Flags:
  RUNTIME_NOOP

Returns
  a constant 0

int Qore::File::write | ( | binary | data | ) |

Writes binary data to a file.

Example:
  $f.write($data);

Events:
  EVENT_DATA_WRITTEN

Parameters

  data | the data to be written to the file

Returns
  the number of bytes written

Exceptions

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

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

int Qore::File::write | ( | string | data | ) |

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

Example:
  $f.write($data);

Events:
  EVENT_DATA_WRITTEN

Parameters

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

Returns
  the number of bytes written

Exceptions

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

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

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

int Qore::File::writei1 | ( | int | c | ) |

Writes a 1-byte integer to the file.

Example:
  $f.writei1($val);

Events:
  EVENT_DATA_WRITTEN

Parameters

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

Returns
  0 for success

Exceptions

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

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

int Qore::File::writei2 | ( | int | s | ) |

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

Example:
  $f.writei2($val);

Events:
  EVENT_DATA_WRITTEN

Parameters

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

Returns
  0 for success

Exceptions

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

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

int Qore::File::writei2LSB | ( | int | s | ) |

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

Example:
  $f.writei2LSB($val);

Events:
  EVENT_DATA_WRITTEN

Parameters

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

Returns
  0 for success

Exceptions

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

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

int Qore::File::writei4 | ( | int | i | ) |

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

Example:
  $f.writei4($val);

Events:
  EVENT_DATA_WRITTEN

Parameters

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

Returns
  0 for success

Exceptions

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

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

int Qore::File::writei4LSB | ( | int | i | ) |

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

Example:
  $f.writei4LSB($val);

Events:
  EVENT_DATA_WRITTEN

Parameters

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

Returns
  0 for success

Exceptions

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

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

int Qore::File::writei8 | ( | int | i | ) |

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

Example:
  $f.writei8($val);

Events:
  EVENT_DATA_WRITTEN

Parameters

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

Returns
  0 for success

Exceptions

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

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

int Qore::File::writei8LSB | ( | int | i | ) |

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

Example:
  $f.writei8LSB($val);

Events:
  EVENT_DATA_WRITTEN

Parameters

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

Returns
  0 for success

Exceptions

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

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