File Functions

Use this function to append a line of text to a file using a ‘log’ format.  It will put a timestamp on the front of the line automatically.  This is an atomic write (full open, append, and close operations done).

Params

Returns

Nothing

Recursively create a directory.  This will create a directory (and every parent directory it needs to) with the default permissions.  If the directory exists, nothing is done.  If there is a problem creating the directory (for instance a regular already exists with the same name), it will quietly fail.

Params

Returns

Nothing

Rename (move) a file within the same filesystem.  This is the equivalent of the ‘mv’ shell command except that it does not cross filesystem boundaries.  Use it to atomically change the name of a file without dropping to a shell.  Obviously permission checks and everything may prevent this operation, so be sure to check the return code.

Params

Returns

This returns true if successfully renamed, or 0 otherwise.

This will erase a file or directory recursively.  It erases the link to a file on the disk, if this is the lask link to that file and it’s not currently open the file will be deleted.  This is the equivalent of an ‘rm -rf’ shell command, so USE WITH CAUTION!

Note, this operation can have different levels of success.  If recursively deleting files, some may be deleted fine, but others may have permission problems preventing it.  It will try to delete all it can, and will return false if ANY errors are encountered even though some files may have been deleted fine.

Params

Returns

True if sucessfully deleted, or false if there were errors.

Open a file and return its handle.  The file can be opened in one of several modes, as indicated by the second parameter, which can have the values in the following table.

The file handle returned (if successful) is used in any further file operations (including closing the file).  Any files that are open upon <reloading> will automatically be closed (and any remaining file handles made invalid).

Params

Returns

An integer file handle of the newly opened file, or 0 if unable to do so.

Close a previously opened file.  The file must’ve been already opened using fopen.

Params

Returns

Nothing

Check the status of the EOF flag on the file handle.  This flag is set after a read attempt has reached the end of the file.  The proper way to check this is shown in the following.

f = fopen("foo.txt", "r");
while( !feof(f) )do
{
   str$ = fget_line$(f);
   ...
}

In the example above, feof() will return true only after an attempt to fetch a line past the last.  If there are some characters, it will return them, but if not, it will return the empty string.

Params

Returns

True if the EOF flag has been set on the file handle.

Read a signed 4 byte integer from the file.

Params

Returns

The read value.

Read an unsigned 2 byte integer from the file.

Params

Returns

The read value.

Read an unsigned byte from the file.

Params

Returns

The read value.

Read null-terminated string from the file.

Params

Returns

The read value.

Read a newline-terminated string from the file.

Params

Returns

The read value.

Write a signed 4 byte integer to the file.

Params

Returns

Whether it was written successfully.

Write an unsigned 2 byte integer to the file.

Params

Returns

Whether it was written successfully.

Write an unsigned byte to the file.

Params

Returns

Whether it was written successfully.

Write a null-terminated string to the file.

Params

Returns

Whether it was written successfully.

Write a newline terminated string to the file.

Params

Returns

Whether it was written successfully.

Read a block of data from a file into an allocated block of memory.  Note that this can be used to read large blocks at a time (very efficiently).  But it does not guarantee that it read as many bytes as requested.  Always check the return value to see how many were read.  A return value of 0 actually indicates that the EOF has been reached.

Params

Returns

The number of bytes actually read (or -1 if there was an error).

Write a block of data to a file from an allocated block of memory.  This will efficiently write large chunks of data from memory into a file.

Params

Returns

True if the write operation succeeds.

Determine the length of a file.

Params

Returns

An integer indicating the number of bytes in the file.

Quickly scan the file to find out the number of lines.  The current file position is unchanged after this operation.  Note that this can be a very costly operation on large files.

Params

Returns

An integer indicating the number of lines in the file.

Query the current position of writing/reading in a file.  The value returned from this is actually the position after the last byte in the file.  So if you’ve written 6 bytes, this function returns 7 (assuming you haven’t repositioned the file using fseek).

Params

Returns

An integer indicating the number of bytes from the beginning of the file.

Position the current file pointer in an open file.  Use this routine to advance forward or backward in a file.  This type of operation should be used sparingly however, as it can be quite a lengthy operation on large files.

You can seek using three different modes, and each determines where in the file you’re seeking ‘from’. anything else has undefined behavior.

Params

Returns

Whether the file was successfully repositioned.

Position the file at the start of a given line.  This will ready the file to read the Nth line in the file, however at quite a large cost.  Use this function sparingly.  The line numbering is 1 based (the first line in the file is line 1).

Params

Returns

Whether the file was successfully repositioned.

Generate a temporary file name.  This returns a filename of a file that did not exist at the time this routine was called.  Generally in the form /tmp/rapture.XXXXXXXX.  The generation of suffixes is quite complicated and not likely guessable (because of the following problem).

This routine should be used with caution.  It’s susceptible to certain forms of malicious attack.  Namely, the span of time between generating a filename and actually opening it is vulnerable to such things as having a symbolic link placed there before the file is opened.  In this case, a malicious attacker could point your temporary file name at a sensitive file such as /etc/passwd and if permissions are set to allow it, you could begin overwriting or reading this file.  This will likely be fixed in future versions of Rapture, but as this form of attack is unlikely, it is not a priority.

Params

none

Returns

A string containing the name of a file that did not exist at the time of calling.