File and compression routines

The following routines implement a fast buffered file I/O system, which supports the reading and writing of compressed files using a ring buffer algorithm based on the LZSS compressor by Haruhiko Okumura. This does not achieve quite such good compression as programs like zip and lha, but unpacking is very fast and it does not require much memory. Packed files always begin with the 32-bit value F_PACK_MAGIC, and autodetect files with the value F_NOPACK_MAGIC.

The following FA_* flags are guaranteed to work:

      FA_NONE           - Exclude files that have any attribute set
      FA_RDONLY         - Directory entries that are unwritable for current user
      FA_HIDDEN         - Hidden flag
      FA_DIREC          - Directories
      FA_SYSTEM         - Files with system flag set (DOS/Windows only)
      FA_LABEL          - Files with volume label flag set (DOS/Windows only)
      FA_ARCH           - Files with archive flag set (DOS/Windows only)
      FA_ALL            - Match all attributes

Do not use any other flags from DOS/Windows or your code will not compile on another platform. FA_RDONLY is for directory entries with read-only flag on DOS-like systems or unwritable by current user on Unix-like systems. Hidden files are directory entries that have the hidden flag set (DOS/Windows) or have names starting with '.' (UNIX, excluding '.' and '..'). Flags can be combined using '|' (binary OR operator).

When passed to the functions as the 'attrib' parameter, these flags represent an upper set in which the actual flag set of a matching file must be included. That is, in order for a file to be matching, its attributes may contain any of the specified flags but must not contain any of the unspecified flags. In other words, you explictly exclude the flags that you do not specify. Thus if you pass 'FA_DIREC | FA_RDONLY', normal files and directories will be included as well as read-only files and directories, but not hidden files and directories. Similarly, if you pass 'FA_ARCH' then both archived and non-archived files will be included. If FA_NONE is passed all attributes are excluded and only files with no attributes are returned. Conversely, if you pass FA_ALL, no attributes are excluded so all files are returned (which is what you would usually want).

Functions which accept wildcards as file names support the meta characters `*' (which means, zero or any quantity of characters) and `?' (which means any character, but only one).

get_executable_name - Obtains the full path to the current executable.
fix_filename_case - Converts a filename to a standardised case.
fix_filename_slashes - Converts all the directory separators to a standard character.
canonicalize_filename - Converts any filename into its canonical form.
make_absolute_filename - Makes an absolute filename from a path and relative filename.
make_relative_filename - Tries to make a relative filename from absolute path and filename.
is_relative_filename - Returns TRUE if the filename is relative.
replace_filename - Replaces path+filename with a new filename tail.
replace_extension - Replaces filename+extension with a new extension tail.
append_filename - Concatenates a filename to a path.
get_filename - Returns a pointer to the filename portion of a path.
get_extension - Returns a pointer to the extension of a filename.
put_backslash - Puts a path separator at the end of a path if needed.
file_exists - Tells if a file exists.
exists - Shortcut version of file_exists() for normal files.
file_size_ex - Returns the size of a file in bytes.
file_time - Returns the modification time of a file.
delete_file - Removes a file from the disk.
for_each_file_ex - Executes callback() for each file matching a wildcard.
al_findfirst - Low-level function for searching files.
al_findnext - Finds the next file in a search started by al_findfirst().
al_findclose - Closes a previously opened search with al_findfirst().
al_ffblk_get_size - Get size of file returned by al_findfirst/al_findnext.
find_allegro_resource - Searches for a support file in many places.
set_allegro_resource_path - Sets a specific resource search path.
packfile_password - Sets the global I/O encryption password.
pack_fopen - Opens a file according to mode.
pack_fopen_vtable
pack_fclose - Closes a stream previously opened.
pack_fseek - Seeks inside a stream.
pack_feof - Returns nonzero as soon as you reach the end of the file.
pack_ferror - Tells if an error occurred during an operation on the stream.
pack_getc - Returns the next character from a stream.
pack_putc - Puts a character in the stream.
pack_igetw - Like pack_getc(), but using 16-bit Intel byte ordering words.
pack_iputw - Like pack_putc(), but using 16-bit Intel byte ordering words.
pack_igetl - Like pack_getc(), but using 32-bit Intel byte ordering words.
pack_iputl - Like pack_putc(), but using 32-bit Intel byte ordering words.
pack_mgetw - Like pack_getc(), but using 16-bit Motorola byte ordering words.
pack_mputw - Like pack_putc(), but using 16-bit Motorola byte ordering words.
pack_mgetl - Like pack_getc(), but using 32-bit Motorola byte ordering words.
pack_mputl - Like pack_putc(), but using 32-bit Motorola byte ordering words.
pack_fread - Reads n bytes from the stream.
pack_fwrite - Writes n bytes to the stream.
pack_fgets - Reads a line from the stream.
pack_fputs - Writes a string to the stream.
pack_fopen_chunk - Opens a sub-chunk of a file.
pack_fclose_chunk - Closes a previously opened sub-chunk.
create_lzss_pack_data - Creates an LZSS structure for compression.
free_lzss_pack_data - Frees an LZSS structure.
lzss_write - Compresses data using LZSS.
create_lzss_unpack_data - Creates an LZSS structure for decompression.
free_lzss_unpack_data - Frees an LZSS structure.
lzss_read - Decompresses data using LZSS.

Allegro Manual

API

File and compression routines