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

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

Inheritance diagram for Qore::File:

Public Member Methods

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

Additional Inherited Members

- Static Public Member Methods inherited from Qore::ReadOnlyFile
static hash< StatInfohlstat (string path)
 Returns a StatInfo hash about the file's status (does not follow symbolic links) or throws an exception if any errors occur. More...
 
static hash< StatInfohstat (string path)
 Returns a StatInfo hash about the file's status (follows symbolic links) or throws an exception if any errors occur. More...
 
static list lstat (string path)
 Returns a Stat List about the given path's status (does not follow symbolic links) or throws an exception if any errors occur. More...
 
static binary readBinaryFile (string path)
 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...
 
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< FilesystemInfostatvfs (string path)
 Returns a FilesystemInfo hash about filesystem status of the given path; throws an exception if any errors occur. More...
 

Detailed Description

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

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

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

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

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

File Events

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

Member Function Documentation

◆ chown()

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

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

Platform Availability:
Qore::Option::HAVE_UNIX_FILEMGT
Example:
f.chown(0, 0);
Parameters
uidThe user id of the user to change to; -1 means do not change uid
gidThe group id of the user to change to; -1 means do not change gid
Exceptions
FILE-CHOWN-ERRORFile is not open or the chown operation failed
MISSING-FEATURE-ERRORthis method is not supported on this platform; check Option::HAVE_UNIX_FILEMGT before calling this method to avoid this exception
ILLEGAL-EXPRESSIONthis exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

◆ constructor()

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

Creates the File object.

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

Example:
File f();
f.open2("/tmp/my-file.txt");
Parameters
encodingThe 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-EXPRESSIONFile::constructor() cannot be called with a TTY target when %no-terminal-io is set
See also
File::open(), File::open2()

◆ copy()

Qore::File::copy ( )

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

Example:
File f1 = f.copy();

◆ destructor()

Qore::File::destructor ( )

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

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

◆ f_printf() [1/2]

int Qore::File::f_printf ( 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
fmtthe format string; see String Formatting for more information about the format string
Returns
the number of bytes written
Exceptions
FILE-WRITE-ERRORFile is not open or an I/O error occurred writing data to the File
ILLEGAL-EXPRESSIONthis exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set
See also
File::printf() for a similar method that does not enforce field widths
Since
Qore 0.8.7 this method throws exceptions on I/O errors to avoid silent write errors in Qore code

◆ f_printf() [2/2]

int Qore::File::f_printf ( )

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

Code Flags:
RUNTIME_NOOP
Returns
a constant 0

◆ f_vprintf() [1/2]

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

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

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

Example:
f.f_vprintf("%5s: %d\n", ("hello there", 2)); # outputs "hello: 2\n", enforcing the field width
Events:
EVENT_DATA_WRITTEN
Parameters
fmtthe format string; see String Formatting for more information about the format string
fmt_argsthe 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-ERRORFile is not open or an I/O error occurred writing data to the File
ILLEGAL-EXPRESSIONthis 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

◆ f_vprintf() [2/2]

int Qore::File::f_vprintf ( )

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

Code Flags:
RUNTIME_NOOP
Returns
a constant 0

◆ getCharset()

string Qore::File::getCharset ( )

Returns the character encoding for the File.

Code Flags:
CONSTANT

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

Returns
the character encoding for the File

◆ getLockInfo()

hash Qore::File::getLockInfo ( )

Returns a hash of lock information.

Platform Availability:
Qore::Option::HAVE_FILE_LOCKING
Code Flags:
RET_VALUE_ONLY
Example:
hash hash = f.getLockInfo();
Returns
a hash with the following keys:
  • start: starting byte of the lock
  • len: the length in bytes of the locked region
  • pid: the PID of the process holding the lock
  • type: see File Locking Constants; if no lock is set on the file, the key type has the value F_UNLCK.
  • whence: always returned as SEEK_SET when the call is successful
Exceptions
FILE-LOCK-ERRORFile is not open or the internal fcntl operation failed
MISSING-FEATURE-ERRORthis 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-EXPRESSIONthis exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

◆ getTerminalAttributes() [1/2]

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

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

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

Platform Availability:
Qore::Option::HAVE_TERMIOS
Example:
TermIOS termios();
stdin.getTerminalAttributes(termios);
Parameters
termiosThe method writes the current terminal attributes for the file to the object passed
Exceptions
FILE-OPERATION-ERRORthe File is not open
TERMIOS-GET-ERRORerror reading terminal attributes from the file descriptor (ex: not a TTY)
MISSING-FEATURE-ERRORthis method is not supported on this platform; check Option::HAVE_TERMIOS before calling this method to avoid this exception
ILLEGAL-EXPRESSIONthis exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

◆ getTerminalAttributes() [2/2]

TermIOS Qore::File::getTerminalAttributes ( )

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

Platform Availability:
Qore::Option::HAVE_TERMIOS
Example:
TermIOS termios = stdin.getTerminalAttributes();
Returns
the current terminal attributes for the File
Exceptions
FILE-OPERATION-ERRORthe File is not open
TERMIOS-GET-ERRORerror reading terminal attributes from the file descriptor (ex: not a TTY)
MISSING-FEATURE-ERRORthis method is not supported on this platform; check Option::HAVE_TERMIOS before calling this method to avoid this exception
ILLEGAL-EXPRESSIONthis 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

◆ lock()

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

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

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

Platform Availability:
Qore::Option::HAVE_FILE_LOCKING
Example:
# lock the entire file exclusively
f.lock(F_WRLCK);
# lock a section of the file for reading, start byte 512, 2K range
f.lock(F_RDLCK, 512, 2048);
# release all locks
f.lock(F_UNLCK);
Parameters
typeType of lock (or unlock); see File Locking Constants
startStart byte for lock, 0 is the default (start of file)
lenLength in bytes for range to lock, 0 is the default (rest of file)
whenceIndicates 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-ERRORFile is not open, lock length is negative, or the fcntl operation failed
MISSING-FEATURE-ERRORthis 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-EXPRESSIONthis exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set
See also
File::lockBlocking() for a blocking version of this method

◆ lockBlocking()

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

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

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

Platform Availability:
Qore::Option::HAVE_FILE_LOCKING
Example:
# lock the entire file exclusively
f.lockBlocking(F_WRLCK);
# lock a section of the file for reading, start byte 512, 2K range
f.lockBlocking(F_RDLCK, 512, 2048);
# release all locks
f.lockBlocking(F_UNLCK);
Parameters
typeType of lock (or unlock); see File Locking Constants
startStart byte for lock, 0 is the default (start of file)
lenLength in bytes for range to lock, 0 is the default (rest of file)
whenceIndicates how the relative offset of the file should be calculated for the lock; see File Seek Constants
Exceptions
FILE-LOCK-ERRORFile is not open, lock length is negative, or the fcntl operation failed
MISSING-FEATURE-ERRORthis 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-EXPRESSIONthis exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set
See also
File::lockBlocking() for a blocking version of this method

◆ open()

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

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

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

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

Example:
# open a file for writing, truncate data if already exists, create the file if doesn't exist
# set 0644 permissions, and convert all string data to ISO-8859-1 encoding
if (f.open(fn, O_CREAT | O_TRUNC | O_WRONLY, 0644, "ISO-8859-1"))
printf("%s: %s\n", fn, strerror(errno()));
Events:
EVENT_OPEN_FILE, EVENT_FILE_OPENED
Parameters
paththe path to the file
flagsflags 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.
modepermission bits for when the file is to be created (default: 0666)
encodingthe 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-EXPRESSIONthis exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set
See also
File::open2() for a version of this method that throws an exception when errors occur opening the file

◆ open2()

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

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

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

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

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

Example:
# open a file for writing, truncate data if already exists, create the file if doesn't exist
# set 0644 permissions, and convert all string data to ISO-8859-1 encoding
try {
f.open2(fn, O_CREAT | O_TRUNC | O_WRONLY, 0644, "ISO-8859-1");
}
catch (hash ex) {
printf("%s: %s: %s\n", fn, ex.err, ex.desc);
}
Events:
EVENT_OPEN_FILE, EVENT_FILE_OPENED
Parameters
paththe path to the file
flagsflags 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.
modepermission bits for when the file is to be created (default: 0666)
encodingthe 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-ERRORan error occurred opening the file
ILLEGAL-EXPRESSIONthis exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set
See also
File::open() for a version of this method that returns an error code instead of throwing an exception when errors occur opening the File

◆ print()

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

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

Example:
f.print(data);
Events:
EVENT_DATA_WRITTEN
Parameters
datathe 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-ERRORFile is not open or an I/O error occurred writing data to the File
ENCODING-CONVERSION-ERRORerror converting from the string's character encoding to the File's character encoding
ILLEGAL-EXPRESSIONthis exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set
Note
this method is equivalent to File::write(string)
Since
Qore 0.8.7 this method throws exceptions on I/O errors to avoid silent write errors in Qore code

◆ printf() [1/2]

int Qore::File::printf ( 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
fmtthe format string; see String Formatting for more information about the format string
Returns
the number of bytes written
Exceptions
FILE-WRITE-ERRORFile is not open or an I/O error occurred writing data to the File
ILLEGAL-EXPRESSIONthis 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

◆ printf() [2/2]

int Qore::File::printf ( )

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

Code Flags:
RUNTIME_NOOP
Returns
a constant 0

◆ redirect()

nothing Qore::File::redirect ( Qore::File  file)

redirects an existing file to another file

Example:
File my_file("/tmp/my_stderr.txt", O_CREAT|O_TRUNC|O_WRONLY);
stderr.redirect(my_file);
Parameters
filethe file that the current object will be redirected to
Exceptions
FILE-REDIRECT-ERRORthe underlying call to dup2() failed
ILLEGAL-EXPRESSIONthis exception is only thrown if called on or with a system constant object (stdin, stdout, stderr) when no-terminal-io is set
Note
Once this method has been successfully executed, the file descriptor of the current object mirrors all operations of the argument's file descriptor and vice-versa, however the internal state and file path information is not kept synchronized between the linked objects in Qore, which must be taken into consideration when performing operations on objects linked through calls to this method.
Since
Qore 0.9

◆ setCharset()

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

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

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

Parameters
encodingthe character encoding for the file; if called with no argument, the default encoding is set
Exceptions
ILLEGAL-EXPRESSIONthis exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

◆ setTerminalAttributes()

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

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

Platform Availability:
Qore::Option::HAVE_TERMIOS
Example:
TermIOS termios();
stdin.getTerminalAttributes(termios);
TermIOS orig = termios.copy();
on_exit
stdin.setTerminalAttributes(TCSADRAIN, orig);
int lflag = termios.getLFlag();
lflag &= ~ICANON;
lflag &= ~ECHO;
lflag &= ~ISIG;
termios.setLFlag(lflag);
termios.setCC(VMIN, 1);
termios.setCC(VTIME, 0);
stdin.setTerminalAttributes(TCSADRAIN, termios);
Parameters
actiona 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
termiosthe TermIOS to use
Exceptions
FILE-OPERATION-ERRORthe File is not open
TERMIOS-SET-ERRORerror setting terminal attributes on the file descriptor
MISSING-FEATURE-ERRORthis method is not supported on this platform; check Option::HAVE_TERMIOS before calling this method to avoid this exception
ILLEGAL-EXPRESSIONthis exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

◆ sync()

int Qore::File::sync ( )

Flushes the file's buffer to disk.

Example:
if (f.sync())
printf("error in File::sync(): %s\n", strerror(errno()));
Returns
0 for success, -1 for error (see errno() and strerror() for the error information)
Exceptions
ILLEGAL-EXPRESSIONthis exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set

◆ vprintf() [1/2]

int Qore::File::vprintf ( 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
fmtthe format string; see String Formatting for more information about the format string
fmt_argsthe 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-ERRORFile is not open or an I/O error occurred writing data to the File
ILLEGAL-EXPRESSIONthis 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

◆ vprintf() [2/2]

int Qore::File::vprintf ( )

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

Code Flags:
RUNTIME_NOOP
Returns
a constant 0

◆ write() [1/2]

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

Writes binary data to a file.

Example:
f.write(data);
Events:
EVENT_DATA_WRITTEN
Parameters
datathe data to be written to the file
Returns
the number of bytes written
Exceptions
FILE-WRITE-ERRORFile is not open or an I/O error occurred writing data to the File
ILLEGAL-EXPRESSIONthis exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set
Since
Qore 0.8.7 this method throws exceptions on I/O errors to avoid silent write errors in Qore code

◆ write() [2/2]

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

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

Example:
f.write(data);
Events:
EVENT_DATA_WRITTEN
Parameters
datathe 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-ERRORFile is not open or an I/O error occurred writing data to the File
ENCODING-CONVERSION-ERRORerror converting from the string's character encoding to the File's character encoding
ILLEGAL-EXPRESSIONthis exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set
Note
this variant of this method is equivalent to File::print()
Since
Qore 0.8.7 this method throws exceptions on I/O errors to avoid silent write errors in Qore code

◆ writei1()

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

Writes a 1-byte integer to the file.

Example:
f.writei1(val);
Events:
EVENT_DATA_WRITTEN
Parameters
cthe integer to write; only the least-significant 8 bits will be written to the file
Returns
0 for success
Exceptions
FILE-WRITE-ERRORFile is not open or an I/O error occurred writing data to the File
ILLEGAL-EXPRESSIONthis exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set
Since
Qore 0.8.7 this method throws exceptions on I/O errors to avoid silent write errors in Qore code

◆ writei2()

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

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

Example:
f.writei2(val);
Events:
EVENT_DATA_WRITTEN
Parameters
sthe 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-ERRORFile is not open or an I/O error occurred writing data to the File
ILLEGAL-EXPRESSIONthis exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set
Since
Qore 0.8.7 this method throws exceptions on I/O errors to avoid silent write errors in Qore code

◆ writei2LSB()

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

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

Example:
f.writei2LSB(val);
Events:
EVENT_DATA_WRITTEN
Parameters
sthe 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-ERRORFile is not open or an I/O error occurred writing data to the File
ILLEGAL-EXPRESSIONthis exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set
Since
Qore 0.8.7 this method throws exceptions on I/O errors to avoid silent write errors in Qore code

◆ writei4()

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

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

Example:
f.writei4(val);
Events:
EVENT_DATA_WRITTEN
Parameters
ithe 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-ERRORFile is not open or an I/O error occurred writing data to the File
ILLEGAL-EXPRESSIONthis exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set
Since
Qore 0.8.7 this method throws exceptions on I/O errors to avoid silent write errors in Qore code

◆ writei4LSB()

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

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

Example:
f.writei4LSB(val);
Events:
EVENT_DATA_WRITTEN
Parameters
ithe 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-ERRORFile is not open or an I/O error occurred writing data to the File
ILLEGAL-EXPRESSIONthis exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set
Since
Qore 0.8.7 this method throws exceptions on I/O errors to avoid silent write errors in Qore code

◆ writei8()

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

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

Example:
f.writei8(val);
Events:
EVENT_DATA_WRITTEN
Parameters
ithe 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-ERRORFile is not open or an I/O error occurred writing data to the File
ILLEGAL-EXPRESSIONthis exception is only thrown if called with a system constant object (stdin, stdout, stderr) when no-terminal-io is set
Since
Qore 0.8.7 this method throws exceptions on I/O errors to avoid silent write errors in Qore code

◆ writei8LSB()

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

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

Example:
f.writei8LSB(val);
Events:
EVENT_DATA_WRITTEN
Parameters
ithe 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-ERRORFile is not open or an I/O error occurred writing data to the File
ILLEGAL-EXPRESSIONthis 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