File I/O: Functions

3. Functions

The functions in this patch are grouped into a few categories. There is a function to open a file and a function for closing a file, a set of functions for doing stream-oriented I/O from files, and a set of housekeeping functions.

Function documentation includes a prototype, information about the function, and a list of exceptions the function might raise (in addition to the ones outlined in "Error handling".

WARNING: All of the actual I/O functions in this package are implemented using the stdio portion of libc. Your system's documentation may have applicable warnings for these functions. When appropriate, the function documentation will say which libc function is used.

3.1 Error handling

Errors are always handled by raising some kind of exception. The following exceptions are defined:

``E_FILE'': This is raised when a stdio call returned an error value. It is the string value "E_FILE", not a new value of type error. CODE is set to "E_FILE", MSG is set to the return of strerror() (which may vary from system to system), and VALUE depends on which function raised the error. When a function fails because the stdio function returned EOF, VALUE is set to "EOF".
E_INVARG: This is raised for a number of reasons. The common reasons are an invalid FHANDLE being passed to a function and an invalid pathname specification. In each of these cases MSG will be set to the cause and VALUE will be the offending value.
E_PERM: This is raised when any of these functions are called with non-wizardly permissions.

3.2 Version

Function: STR file_version()

Returns the package shortname/version number of this package e.g.


  ;file_version()
  => "FIO/1.5"

3.3 Opening and closing of files and related functions

File streams are associated with FHANDLES. FHANDLES are similar to the FILE* using stdio. You get an FHANDLE from file_open. You should not depend on the actual type of FHANDLEs (currently TYPE_INT). FHANDLEs are not persistent across server restarts. That is, files open when the server is shut down are closed when it comes back up and no information about open files is saved in the DB.

file_open

Function: FHANDLE file_open(STR pathname, STR mode)

Raises: E_INVARG if mode is not a valid mode, E_QUOTA if too many files open

This opens a file specified by pathname and returns an FHANDLE for it. It ensures pathname is legal. mode is a string of characters indicating what mode the file is opened in. The mode string is four characters.

The first character must be (r)ead, (w)rite, or (a)ppend. The second must be '+' or '-'. This modifies the previous argument.

r- opens the file for reading and fails if the file does not exist.
r+ opens the file for reading and writing and fails if the file does not exist.
w- opens the file for writing, truncating if it exists and creating if not.
w+ opens the file for reading and writing, truncating if it exists and creating if not.
a- opens a file for writing, creates it if it does not exist and positions the stream at the end of the file.
a+ opens the file for reading and writing, creates it if does not exist and positions the stream at the end of the file.

The third character is either (t)ext or (b)inary. In text mode, data is written as-is from the MOO and data read in by the MOO is stripped of unprintable characters. In binary mode, data is written filtered through the binary-string->raw-bytes conversion and data is read filtered through the raw-bytes->binary-string conversion. For example, in text mode writing "~1B" means three bytes are written: '~' '1' 'B'. In binary mode writing "~1B" means an ASCII ESC is written. Similarly, in text mode reading "~1B" means the characters '~' '1' 'B' were present in the file. In binary mode reading "~1B" means an ASCII ESC was in the file. In text mode, reading an ESC from a file results in the ESC getting stripped.

It is not recommended that files containing unprintable ASCII data be read in text mode, for obvious reasons.

The final character is either 'n' or 'f'. If this character is 'f' then the stream will be flushed using fflush after every operation that writes data to the stream. If it is 'n' then this won't happen.

This is implemented using fopen().

file_close

Function: void file_close(FHANDLE fh)

Closes the file associated with fh.

This is implemented using fclose().

file_name

Function: STR file_name(FHANDLE fh)

Returns the pathname originally associated with fh by file_open(). This is not necessarily the file's current name if it was renamed or unlinked after the fh was opened.

file_openmode

Function: STR file_openmode(FHANDLE fh)

Returns the mode the file associated with fh was opened in.

3.4 Input and Ouput operations

file_readline

Function: STR file_readline(FHANDLE fh)

Reads the next line in the file and returns it (without the newline).

Not recommended for use on files in binary mode.

This is implemented using fgets().

file_readlines

Function: LIST file_readlines(FHANDLE fh, INT start, INT end)

Rewinds the file and then reads the specified lines from the file, returning them as a list of strings. After this operation, the stream is positioned right after the last line read.

Not recommended for use on files in binary mode.

This is implemented using fgets().

file_writeline

Function: void file_writeline(FHANDLE fh, STR line)

Writes the specified line to the file (adding a newline).

Not recommended for use on files in binary mode.

This is implemented using fputs().

file_read

Function: STR file_read(FHANDLE fh, INT bytes)

Reads up to the specified number of bytes from the file and returns them.

Not recommended for use on files in text mode.

This is implemented using fread().

file_write

Function: INT file_write(FHANDLE fh, STR data)

Writes the specified data to the file. Returns number of bytes written.

Not recommended for use on files in text mode.

This is implemented using fwrite().

Getting and setting stream position

file_tell

Function: INT file_tell(FHANDLE fh)

Returns position in file.

This is implemented using ftell().

file_seek

Function: void file_seek(FHANDLE fh, INT loc, STR whence)

Seeks to a particular location in a file. whence is one of the strings:

"SEEK_SET" - seek to location relative to beginning
"SEEK_CUR" - seek to location relative to current
"SEEK_END" - seek to location relative to end

This is implemented using fseek().

file_eof

Function: INT file_eof(FHANDLE fh)

Returns true if and only if fh's stream is positioned at EOF.

This is implemented using feof().

3.5 Housekeeping operations

file_size, file_mode, file_last_access, file_last_modify, file_last_change

Function: INT file_size(STR pathname)
Function: STR file_mode(STR pathname)
Function: INT file_last_access(STR pathname)
Function: INT file_last_modify(STR pathname)
Function: INT file_last_change(STR pathname)
Function: INT file_size(FHANDLE fh)
Function: STR file_mode(FHANDLE fh)
Function: INT file_last_access(FHANDLE fh)
Function: INT file_last_modify(FHANDLE fh)
Function: INT file_last_change(FHANDLE fh)

Returns the size, mode, last access time, last modify time, or last change time of the specified file. All of these functions also take FHANDLE arguments and then operate on the open file.

These are all implemented using fstat() (for open FHANDLEs) or stat() (for pathnames).

file_stat

Function: void file_stat(STR pathname)
Function: void file_stat(FHANDLE fh)

Returns the result of stat() (or fstat()) on the given file. Specifically a list as follows:

{file size in bytes, file type, file access mode, owner, group, 
     last access, last modify, and last change}

owner and group are always the empty string.

It is recommended that the specific information functions file_size, file_type, file_mode, file_last_access, file_last_modify, and file_last_change be used instead. In most cases only one of these elements is desired and in those cases there's no reason to make and free a list.

file_rename

Function: void file_rename(STR oldpath, STR newpath)

Attempts to rename the oldpath to newpath.

This is implemented using rename().

file_remove

Function: void file_remove(STR pathname)

Attempts to remove the given file.

This is implemented using remove().

file_mkdir

Function: void file_mkdir(STR pathname)

Attempts to create the given directory.

This is implemented using mkdir().

file_rmdir

Function: void file_rmdir(STR pathname)

Attempts to remove the given directory.

This is implemented using rmdir().

file_list

Function: LIST file_list(STR pathname, [ANY detailed])

Attempts to list the contents of the given directory. Returns a list of files in the directory. If the detailed argument is provided and true, then the list contains detailed entries, otherwise it contains a simple list of names.

detailed entry:
  {STR filename, STR file type, STR file mode, INT file size}
normal entry:
  STR filename

This is implemented using scandir().

file_type

Function: STR file_type(STR pathname)

Returns the type of the given pathname, one of "reg", "dir", "dev", "fifo", or "socket".

This is implemented using stat().

file_mode

Function: STR file_mode(STR filename)

Returns octal mode for a file (e.g. "644").

This is implemented using stat().

file_chmod

Function: void file_chmod(STR filename, STR mode)

Attempts to set mode of a file using mode as an octal string of exactly three characters.

This is implemented using chmod().

Previous Next Table of Contents