| dblog() | execute() | fchmod() | fclose() | feof() |
| fflush() | file() | files() | fmkdir() | fopen() |
| fread() | fremove() | frename() | frmdir() | fseek() |
| fstat() | fwrite() |
dblog()
INTEGER dblog(STRING line)
This function writes line to the database logfile (specified on startup, defaulting to ~/[game_directory]/logs/db.log).
execute()
INTEGER execute(STRING program, LIST args[, INTEGER nb])
This function executes the program named by program with the arguments given in the list arguments. Each argument must be a string. By default, calling this function will block execution of Genesis until the called program returns. If the optional third argument is specified as a true value, the program is forked and executed in a non-blocking manner. The return value of this function should not be relied upon for any useful information. Other means (such as a dedicated port) should be provided to allow communication with external programs.
This function looks for the program in the executable directory specified upon startup by the driver. This usually defaults to ~/[game_dir]/dbbin.
fchmod()
INTEGER fchmod(STRING mode[, STRING file])
This function changes the mode of a file or directory. The mode is an octal number constructed by logically OR-ing the following values:
| 4000 | Set user ID on execution. |
| 2000 | Set group ID on execution. |
| 1000 | Sticky bit - this value is ignored. |
| 0400 | Make readable by owner. |
| 0200 | Make writeable by owner. |
| 0100 | Make executeable (or searchable for directories) by owner. |
| 0070 | Make readable, writable, executable/searchable by group. |
| 0007 | Make readable, writable, executable/searchable by others. |
The read, write, and execute/search values for group and others are encoded as described for owner. If, for example, you wish to make the file warnings readable and writable by owner and group only, the proper function call would be:
fchmod("0660", "warnings");
If the RESTRICTIVE_FILES option has been compiled into the driver, sticky and setuid/setgid bits cannot be changed.
fclose()
INTEGER fclose()
This function closes the file on the current object and returns 1 (true). If no file is open on the current object, the error ~file is thrown.
feof()
INTEGER feof()
This function returns 1 (true) if the open file on the current object is at its end, or 0 (false) if it is not. If the current object does not have an open file, ~file is thrown.
fflush()
INTEGER fflush()
This function flushes any buffered output for the open file on the current object and returns 1 (true). If there is no file on the current object the error ~file is thrown.
file()
LIST file()
This function returns the following ordered list of information on the file on the current object:
- BOOLEAN - file is readable.
- BOOLEAN - file is writable.
- BOOLEAN - file is closed.
- BOOLEAN - file is binary.
- STRING - file path.
If no file is bound to the current object, the error ~file is thrown.
files()
LIST files(STRING directory)
This function returns a list of files in the specified directory. The current and previous directory ("." and "..") are not included in this listing. Each element in the list is a string.
files("/")
=> ["runtime", "enter"]
fmkdir()
INTEGER fmkdir(STRING path)
This function creates the directory specified by path. If a file or directory already exists by that designation, the error ~file is thrown. Otherwise the directory is created with read, write and execute permission for the owner and group, and no permissions for others (these permissions can be changed with the function fchmod().
fopen()
LIST fopen(STRING filename[, STRING mode])
This function is used to open a file on the current object. It is called with one or two arguments. The first argument is the name of the file to open. If the driver was compiled with the RESTRICTIVE_FILES option, the filename will have restrictions (see Files for more information). If RESTRICTIVE_FILES was compiled, all files will have the ~/[game_dir]/root directory prepended to them (this directory is defined by a command line argument to Genesis). If it was not compiled, but the file does not begin with a slash ("/"), the root directory will still be prepended.
The second argument is the mode for the file. If the mode begins with "<" or nothing, the file is opened for reading. If the mode begins with ">", the file is truncated to zero length or created for writing. If the mode begins with ">>", the file is opened for appending. If the second argument is not specified, the mode of file defaults to "<".
A "+" may be placed before ">" or "<" to specify both read and write access to the file. Ending a mode with a "-" sets it as a binary file, meaning that input and output to the file is through buffers, rather than ColdC strings.
If successful, the return value of fopen() is stat information in the format returned by fstat().
A function call to open the file log in append mode:
stat = fopen("log", ">>");
A function call to open and the file /atyreus/notes for binary reading and writing and truncate it to zero length:
stat = fopen("/atyreus/notes", "+>-");
fread()
STRING|BUFFER fread([INTEGER block])
Read from the existing file bound to this object. If the file is a binary file, a buffer is returned. If the file is a text file (default), a string is returned. If the file is at the end, the ~eof error is thrown. With binary files an optional block size may be specified. The default block size is 512 characters.
catch any {
lines = [];
fopen(fname);
while ((tmp = (| tmp = fread() |)) != ~eof) {
refresh();
lines += [tmp];
}
}
fremove()
INTEGER fremove(STRING path)
This function removes the file specified by path.
frename()
INTEGER frename(ANY from, STRING to)
This function renames the file specified by the argument from, to the name specified by the argument to. If from is not a string or is logically false, the driver renames the file on the current object. Do not rename the file on the current object by specifying the file's name, as the driver will not know the name has changed and this may cause confusion at a later time.
A function call to change the name of a file on the current object:
frename("", "new_name");
frmdir()
INTEGER frmdir(STRING path)
This function removes the directory specified by path. If an error occurs, ~file is thrown (the error explanation will vary depending upon what occurred).
fseek()
INTEGER fseek(INTEGER offset, SYMBOL whence)
This function changes the file position to offset. The variable whence is either 'SEEK_SET, 'SEEK_CUR, 'SEEK_END, indicating that the offset is relative to the start of the file, the current position indicator, or end-of-file, respectively.
If the file is not both readable and writable, this function cannot be used.
fstat()
LIST fstat([STRING path])
This function returns information on a file. If the file is not specified as path, then it returns information on the open file on the current object. The information is returned as an ordered list:
- STRING - octal file mode (see fchmod()).
- INTEGER - file size (in bytes).
- INTEGER - time when the file was last accessed.
- INTEGER - time when the file was last modified.
- INTEGER - time when the file was last changed.
For more information refer to the unix manual page on stat. The octal file mode will likely include additional bit fields on top of those that are commonly seen. These represent file attributes, such as directories, FIFO, etc. The last four bits will refer to the permissions.
fstat("runtime")
=> ["100660", 511, 1253456276, 1253456229, 1253456229]
fwrite()
INTEGER fwrite(STRING|BUFFER info)
Write to an existing file bound to this object. The argument is either a buffer (if it is a binary file) or a string (if it is a text file). The return value is an integer representing an offset value of characters which were not written out (due to an error). In normal operating conditions the return value will be zero.
Using fwrite() with strings will always terminate the string with a newline character (ASCII 10).
