<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html><head><title>
Allegro Manual: File and compression routines
</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="Content-Style-Type" content="text/css">
<link rel="stylesheet" title="Default" type="text/css" href="allegro.css"></head><body bgcolor=white text=black link="#0000ee" alink="#ff0000" vlink="#551a8b">
<h1><a name="File and compression routines">File and compression routines</a></h1>
<ul>
<li><a href="#al_ffblk_get_size">al_ffblk_get_size</a> — Get size of file returned by al_findfirst/al_findnext.
<li><a href="#al_findclose">al_findclose</a> — Closes a previously opened search with al_findfirst().
<li><a href="#al_findfirst">al_findfirst</a> — Low-level function for searching files.
<li><a href="#al_findnext">al_findnext</a> — Finds the next file in a search started by al_findfirst().
<li><a href="#append_filename">append_filename</a> — Concatenates a filename to a path.
<li><a href="#canonicalize_filename">canonicalize_filename</a> — Converts any filename into its canonical form.
<li><a href="#create_lzss_pack_data">create_lzss_pack_data</a> — Creates an LZSS structure for compression.
<li><a href="#create_lzss_unpack_data">create_lzss_unpack_data</a> — Creates an LZSS structure for decompression.
<li><a href="#delete_file">delete_file</a> — Removes a file from the disk.
<li><a href="#exists">exists</a> — Shortcut version of file_exists() for normal files.
<li><a href="#file_exists">file_exists</a> — Tells if a file exists.
<li><a href="#file_size_ex">file_size_ex</a> — Returns the size of a file in bytes.
<li><a href="#file_time">file_time</a> — Returns the modification time of a file.
<li><a href="#find_allegro_resource">find_allegro_resource</a> — Searches for a support file in many places.
<li><a href="#fix_filename_case">fix_filename_case</a> — Converts a filename to a standardised case.
<li><a href="#fix_filename_slashes">fix_filename_slashes</a> — Converts all the directory separators to a standard character.
<li><a href="#for_each_file_ex">for_each_file_ex</a> — Executes callback() for each file matching a wildcard.
<li><a href="#free_lzss_pack_data">free_lzss_pack_data</a> — Frees an LZSS structure.
<li><a href="#free_lzss_unpack_data">free_lzss_unpack_data</a> — Frees an LZSS structure.
<li><a href="#get_executable_name">get_executable_name</a> — Obtains the full path to the current executable.
<li><a href="#get_extension">get_extension</a> — Returns a pointer to the extension of a filename.
<li><a href="#get_filename">get_filename</a> — Returns a pointer to the filename portion of a path.
<li><a href="#get_filename_encoding">get_filename_encoding</a> — Returns the encoding currently assumed for filenames.
<li><a href="#is_relative_filename">is_relative_filename</a> — Returns TRUE if the filename is relative.
<li><a href="#lzss_read">lzss_read</a> — Decompresses data using LZSS.
<li><a href="#lzss_write">lzss_write</a> — Compresses data using LZSS.
<li><a href="#make_absolute_filename">make_absolute_filename</a> — Makes an absolute filename from a path and relative filename.
<li><a href="#make_relative_filename">make_relative_filename</a> — Tries to make a relative filename from absolute path and filename.
<li><a href="#pack_fclose">pack_fclose</a> — Closes a stream previously opened.
<li><a href="#pack_fclose_chunk">pack_fclose_chunk</a> — Closes a previously opened sub-chunk.
<li><a href="#pack_feof">pack_feof</a> — Returns nonzero as soon as you reach the end of the file.
<li><a href="#pack_ferror">pack_ferror</a> — Tells if an error occurred during an operation on the stream.
<li><a href="#pack_fgets">pack_fgets</a> — Reads a line from the stream.
<li><a href="#pack_fopen">pack_fopen</a> — Opens a file according to mode.
<li><a href="#pack_fopen_chunk">pack_fopen_chunk</a> — Opens a sub-chunk of a file.
<li><a href="#pack_fopen_vtable">pack_fopen_vtable</a>
<li><a href="#pack_fputs">pack_fputs</a> — Writes a string to the stream.
<li><a href="#pack_fread">pack_fread</a> — Reads n bytes from the stream.
<li><a href="#pack_fseek">pack_fseek</a> — Seeks inside a stream.
<li><a href="#pack_fwrite">pack_fwrite</a> — Writes n bytes to the stream.
<li><a href="#pack_getc">pack_getc</a> — Returns the next character from a stream.
<li><a href="#pack_igetl">pack_igetl</a> — Like pack_getc(), but using 32-bit Intel byte ordering words.
<li><a href="#pack_igetw">pack_igetw</a> — Like pack_getc(), but using 16-bit Intel byte ordering words.
<li><a href="#pack_iputl">pack_iputl</a> — Like pack_putc(), but using 32-bit Intel byte ordering words.
<li><a href="#pack_iputw">pack_iputw</a> — Like pack_putc(), but using 16-bit Intel byte ordering words.
<li><a href="#pack_mgetl">pack_mgetl</a> — Like pack_getc(), but using 32-bit Motorola byte ordering words.
<li><a href="#pack_mgetw">pack_mgetw</a> — Like pack_getc(), but using 16-bit Motorola byte ordering words.
<li><a href="#pack_mputl">pack_mputl</a> — Like pack_putc(), but using 32-bit Motorola byte ordering words.
<li><a href="#pack_mputw">pack_mputw</a> — Like pack_putc(), but using 16-bit Motorola byte ordering words.
<li><a href="#pack_putc">pack_putc</a> — Puts a character in the stream.
<li><a href="#pack_ungetc">pack_ungetc</a> — Moves one single character back to the input buffer.
<li><a href="#packfile_password">packfile_password</a> — Sets the global I/O encryption password.
<li><a href="#put_backslash">put_backslash</a> — Puts a path separator at the end of a path if needed.
<li><a href="#replace_extension">replace_extension</a> — Replaces filename+extension with a new extension tail.
<li><a href="#replace_filename">replace_filename</a> — Replaces path+filename with a new filename tail.
<li><a href="#set_allegro_resource_path">set_allegro_resource_path</a> — Sets a specific resource search path.
<li><a href="#set_filename_encoding">set_filename_encoding</a> — Sets the encoding to use for filenames.
</ul>
<p>
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.
<p>
The following FA_* flags are guaranteed to work:
<blockquote class="text"><pre>
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</pre></blockquote>
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).
<p>
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 explicitly <i>exclude</i> the flags that you
do <i>not</i> 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).
<p>
Functions which accept wildcards as file names support the meta characters
`*' (which means, zero or any quantity of characters) and <tt>`?'</tt> (which means
any character, but only one).
<p><br>
<div class="al-api"><b>void <a name="get_executable_name">get_executable_name</a>(char *buf, int size);</b></div><br>
Fills <tt>`buf'</tt> with the full path to the current executable, writing at most
<tt>`size'</tt> bytes. This generally comes from <tt>`argv[0]'</tt> but on Unix systems it
tries to get the information from the <tt>`/proc'</tt> filesystem first, searching
the directories specified in `$PATH' if necessary. If this fails too, it
tries to find the executable name from the output of the <tt>`ps'</tt> command,
using <tt>`argv[0]'</tt> only as a last resort if all other options fail. Example:
<blockquote class="code"><pre>
char name[200];
...
<a href="#get_executable_name" class="autotype" title="Obtains the full path to the current executable.">get_executable_name</a>(name, sizeof(name));
<a href="alleg000.html#allegro_message" class="autotype" title="Used mainly to show error messages to users.">allegro_message</a>("Running `%s'\n", name);</pre></blockquote>
<p><br>
<div class="al-api"><b>char *<a name="fix_filename_case">fix_filename_case</a>(char *path);</b></div><br>
Converts the filename stored in <tt>`path'</tt> to a standardised case. On DOS
platforms, they will be entirely uppercase. On other platforms this
function doesn't do anything. Example:
<blockquote class="code"><pre>
<a href="#get_executable_name" class="autotype" title="Obtains the full path to the current executable.">get_executable_name</a>(name, sizeof(name));
<a href="#fix_filename_case" class="autotype" title="Converts a filename to a standardised case.">fix_filename_case</a>(name);
<a href="alleg000.html#allegro_message" class="autotype" title="Used mainly to show error messages to users.">allegro_message</a>("Running `%s'\n", name);</pre></blockquote>
<p><b>Return value:</b>
Returns a copy of the <tt>`path'</tt> parameter.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#fix_filename_slashes" title="Converts all the directory separators to a standard character.">fix_filename_slashes</a>,
<a class="xref" href="#canonicalize_filename" title="Converts any filename into its canonical form.">canonicalize_filename</a>.</blockquote>
<div class="al-api"><b>char *<a name="fix_filename_slashes">fix_filename_slashes</a>(char *path);</b></div><br>
Converts all the directory separators in the filename stored in <tt>`path'</tt> to
a standard character. On DOS and Windows platforms, this is a backslash.
On most other platforms this is a slash. Example:
<blockquote class="code"><pre>
char buf[200] = "c:/dos\\backup/weirdo\\test";
...
<a href="#fix_filename_slashes" class="autotype" title="Converts all the directory separators to a standard character.">fix_filename_slashes</a>(buf);
/* Under DOS we would have c:\dos\backup\weirdo\test.
Under Unix we would have c:/dos/backup/weirdo/test. */</pre></blockquote>
<p><b>Return value:</b>
Returns a copy of the <tt>`path'</tt> parameter.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#fix_filename_case" title="Converts a filename to a standardised case.">fix_filename_case</a>,
<a class="xref" href="#canonicalize_filename" title="Converts any filename into its canonical form.">canonicalize_filename</a>.</blockquote>
<div class="al-api"><b>char *<a name="canonicalize_filename">canonicalize_filename</a>(char *dest, const char *filename, int size);</b></div><br>
Converts any filename into its canonical form, i.e. the minimal absolute
filename describing the same file and fixing incorrect forward/backward
slashes for the current platform, storing at most <tt>`size'</tt> bytes into the
<tt>`dest'</tt> buffer. You can use the same buffer both as input and output
because Allegro internally works on a copy of the input before touching
<tt>`dest'</tt>. Example:
<blockquote class="code"><pre>
char buf[256];
...
<a href="#canonicalize_filename" class="autotype" title="Converts any filename into its canonical form.">canonicalize_filename</a>(buf, "~/../s22/..\\t3st///hi.c",
sizeof(buf));
/* Running this under Unix would
return: /home/t3st/hi.c */
</pre></blockquote>
Note that this function won't work as expected if the path to canonicalize
comes from another platform (eg. a "c:\something" path will canonicalize
into something really wrong under Unix: "/current/path/c:/something").
<p><b>Return value:</b>
Returns a copy of the <tt>`dest'</tt> parameter.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#fix_filename_case" title="Converts a filename to a standardised case.">fix_filename_case</a>,
<a class="xref" href="#fix_filename_slashes" title="Converts all the directory separators to a standard character.">fix_filename_slashes</a>.</blockquote>
<div class="al-api"><b>char *<a name="make_absolute_filename">make_absolute_filename</a>(char *dest, const char *path, const char *filename, int size);</b></div><br>
Makes an absolute filename from an absolute path and a relative filename,
storing at most <tt>`size'</tt> bytes into the <tt>`dest'</tt> buffer. This is like calling
replace_filename() and then canonicalize_filename(). Example:
<blockquote class="code"><pre>
char buf[256];
...
<a href="#make_absolute_filename" class="autotype" title="Makes an absolute filename from a path and relative filename.">make_absolute_filename</a>(buf, "/usr/games/",
"../temp.txt", sizeof(buf));
/* This would create /usr/temp.txt */</pre></blockquote>
<p><b>Return value:</b>
Returns a copy of the <tt>`dest'</tt> parameter.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#make_relative_filename" title="Tries to make a relative filename from absolute path and filename.">make_relative_filename</a>,
<a class="xref" href="#is_relative_filename" title="Returns TRUE if the filename is relative.">is_relative_filename</a>,
<a class="xref" href="#replace_filename" title="Replaces path+filename with a new filename tail.">replace_filename</a>,
<a class="xref" href="#canonicalize_filename" title="Converts any filename into its canonical form.">canonicalize_filename</a>.</blockquote>
<div class="al-api"><b>char *<a name="make_relative_filename">make_relative_filename</a>(char *dest, const char *path, const char *filename, int size);</b></div><br>
Attempts to make a relative filename from an absolute path and an absolute
filename, storing at most <tt>`size'</tt> bytes into the <tt>`dest'</tt> buffer. This
function won't work if the paths are not canonical under the current
platform (see canonicalize_filename()). Also, <tt>`dest'</tt> cannot be used as
input value for <tt>`path'</tt> or <tt>`filename'</tt>. Example:
<blockquote class="code"><pre>
char base[] = "/long/absolute/path/program.exe";
char user_input[] = "/nice/and/short.txt";
...
<a href="#make_relative_filename" class="autotype" title="Tries to make a relative filename from absolute path and filename.">make_relative_filename</a>(buf, base, user_input, sizeof(buf));
/* Under Unix buf would contain:
../../../nice/and/short.txt */</pre></blockquote>
<p><b>Return value:</b>
Returns a copy of the <tt>`dest'</tt> parameter if it succeeds or NULL if it fails
(eg. under DOS, one path starts with "C:\" and another with "A:\").
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#make_absolute_filename" title="Makes an absolute filename from a path and relative filename.">make_absolute_filename</a>,
<a class="xref" href="#is_relative_filename" title="Returns TRUE if the filename is relative.">is_relative_filename</a>,
<a class="xref" href="#canonicalize_filename" title="Converts any filename into its canonical form.">canonicalize_filename</a>.</blockquote>
<div class="al-api"><b>int <a name="is_relative_filename">is_relative_filename</a>(const char *filename);</b></div><br>
Returns TRUE if the filename is relative or FALSE if it is absolute. Note
that an absolute filename under DOS (with a device separator) will be
considered as relative under Unix, because there absolute paths always
start with a slash.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#make_absolute_filename" title="Makes an absolute filename from a path and relative filename.">make_absolute_filename</a>,
<a class="xref" href="#make_relative_filename" title="Tries to make a relative filename from absolute path and filename.">make_relative_filename</a>.</blockquote>
<div class="al-api"><b>char *<a name="replace_filename">replace_filename</a>(char *dest, const char *path,
const char *filename, int size);</b></div><br>
Replaces the specified path+filename with a new filename tail, storing
at most <tt>`size'</tt> bytes into the <tt>`dest'</tt> buffer. You can use the same buffer
both as input and output because Allegro internally works on a copy of
the input before touching <tt>`dest'</tt>. Example:
<blockquote class="code"><pre>
char name[200];
...
<a href="#get_executable_name" class="autotype" title="Obtains the full path to the current executable.">get_executable_name</a>(name, sizeof(name));
<a href="#replace_filename" class="autotype" title="Replaces path+filename with a new filename tail.">replace_filename</a>(name, name, "sound.dat", sizeof(name));</pre></blockquote>
<p><b>Return value:</b>
Returns a copy of the <tt>`dest'</tt> parameter.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#get_filename" title="Returns a pointer to the filename portion of a path.">get_filename</a>,
<a class="xref" href="#replace_extension" title="Replaces filename+extension with a new extension tail.">replace_extension</a>,
<a class="xref" href="#append_filename" title="Concatenates a filename to a path.">append_filename</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#Available Allegro examples" title="">Available Allegro examples</a>.</blockquote>
<div class="al-api"><b>char *<a name="replace_extension">replace_extension</a>(char *dest, const char *filename,
const char *ext, int size);</b></div><br>
Replaces the specified filename+extension with a new extension tail,
storing at most <tt>`size'</tt> bytes into the <tt>`dest'</tt> buffer. If the filename
doesn't have any extension at all, <tt>`ext'</tt> will be appended to it, adding
a dot character if needed. You can use the same buffer both as input and
output because Allegro internally works on a copy of the input before
touching <tt>`dest'</tt>. Example:
<blockquote class="code"><pre>
<a href="#replace_extension" class="autotype" title="Replaces filename+extension with a new extension tail.">replace_extension</a>(buf, "C:\\game\\prog.exe",
"dat", sizeof(buf));</pre></blockquote>
<p><b>Return value:</b>
Returns a copy of the <tt>`dest'</tt> parameter.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#get_extension" title="Returns a pointer to the extension of a filename.">get_extension</a>,
<a class="xref" href="#replace_filename" title="Replaces path+filename with a new filename tail.">replace_filename</a>.</blockquote>
<div class="al-api"><b>char *<a name="append_filename">append_filename</a>(char *dest, const char *path,
const char *filename, int size);</b></div><br>
Concatenates the specified filename onto the end of the specified path,
storing at most <tt>`size'</tt> bytes into the <tt>`dest'</tt> buffer. If <tt>`path'</tt> doesn't
have a trailing path separator, the function will append one if needed.
You can use the same buffer both as input and output because Allegro
internally works on a copy of the input before touching <tt>`dest'</tt>. Example:
<blockquote class="code"><pre>
<a href="#append_filename" class="autotype" title="Concatenates a filename to a path.">append_filename</a>(buf, "/home/user",
"prog.bin", sizeof(buf));</pre></blockquote>
<p><b>Return value:</b>
Returns a copy of the <tt>`dest'</tt> parameter.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#replace_filename" title="Replaces path+filename with a new filename tail.">replace_filename</a>.</blockquote>
<div class="al-api"><b>char *<a name="get_filename">get_filename</a>(const char *path);</b></div><br>
Finds out the filename portion of a completely specified file path. Both
<tt>`\'</tt> and <tt>`/'</tt> are recognized as directory separators under DOS and Windows.
However, only <tt>`/'</tt> is recognized as directory separator under other
platforms. Example:
<blockquote class="code"><pre>
<a href="#get_executable_name" class="autotype" title="Obtains the full path to the current executable.">get_executable_name</a>(name, sizeof(name));
<a href="alleg000.html#allegro_message" class="autotype" title="Used mainly to show error messages to users.">allegro_message</a>("Running `%s'\n", <a href="#get_filename" class="autotype" title="Returns a pointer to the filename portion of a path.">get_filename</a>(name));
</pre></blockquote>
Note that Allegro won't perform any IO operations during the verification.
This means that if you have <tt>`/a/path/like/this/'</tt>, which doesn't have a
filename, the function will return a pointer to the trailing null
character. However, if you have <tt>`/a/path/like/this'</tt>, Allegro will return
a pointer to <tt>`this'</tt>, even if it is a valid directory.
<p><b>Return value:</b>
Returns a pointer to the portion of <tt>`path'</tt> where the filename starts, or
the beginning of <tt>`path'</tt> if no valid filename is found (eg. you are
processing a path with backslashes under Unix).
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#get_extension" title="Returns a pointer to the extension of a filename.">get_extension</a>,
<a class="xref" href="#put_backslash" title="Puts a path separator at the end of a path if needed.">put_backslash</a>,
<a class="xref" href="#replace_filename" title="Replaces path+filename with a new filename tail.">replace_filename</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exmidi" title="Playing MIDI music.">exmidi</a>.</blockquote>
<div class="al-api"><b>char *<a name="get_extension">get_extension</a>(const char *filename);</b></div><br>
Finds out the extension of the filename (with or without path
information). Example:
<blockquote class="code"><pre>
<a href="#get_executable_name" class="autotype" title="Obtains the full path to the current executable.">get_executable_name</a>(name, sizeof(name));
<a href="alleg000.html#allegro_message" class="autotype" title="Used mainly to show error messages to users.">allegro_message</a>("The binary has the extension `%s'\n",
<a href="#get_extension" class="autotype" title="Returns a pointer to the extension of a filename.">get_extension</a>(name));</pre></blockquote>
<p><b>Return value:</b>
Returns a pointer to the portion of <tt>`filename'</tt> where the extension starts,
or a pointer to the trailing null character if there is no filename or it
doesn't have extension.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#get_filename" title="Returns a pointer to the filename portion of a path.">get_filename</a>,
<a class="xref" href="#put_backslash" title="Puts a path separator at the end of a path if needed.">put_backslash</a>,
<a class="xref" href="#replace_extension" title="Replaces filename+extension with a new extension tail.">replace_extension</a>.</blockquote>
<div class="al-api"><b>void <a name="put_backslash">put_backslash</a>(char *filename);</b></div><br>
If the last character of the filename is not a <tt>`\'</tt>, <tt>`/'</tt>, `#' or a device
separator (ie. <tt>`:'</tt> under DOS), this routine will concatenate either a <tt>`\'</tt>
or <tt>`/'</tt> on to it (depending on the platform). Note: ignore the function
name, it's out of date.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#get_extension" title="Returns a pointer to the extension of a filename.">get_extension</a>,
<a class="xref" href="#get_filename" title="Returns a pointer to the filename portion of a path.">get_filename</a>.</blockquote>
<div class="al-api"><b>void <a name="set_filename_encoding">set_filename_encoding</a>(int encoding)</b></div><br>
Sets the encoding to use for filenames. By default, UTF-8 is assumed.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#get_filename_encoding" title="Returns the encoding currently assumed for filenames.">get_filename_encoding</a>.</blockquote>
<div class="al-api"><b>int <a name="get_filename_encoding">get_filename_encoding</a>(void)</b></div><br>
Returns the encoding currently assumed for filenames.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#set_filename_encoding" title="Sets the encoding to use for filenames.">set_filename_encoding</a>.</blockquote>
<div class="al-api"><b>int <a name="file_exists">file_exists</a>(const char *filename, int attrib, int *aret);</b></div><br>
Checks whether a file matching the given name and attributes (see
beginning of this chapter) exists. If <tt>`aret'</tt> is not NULL, it will be set
to the attributes of the matching file. Example:
<blockquote class="code"><pre>
/* Check for a normal file. */
if (<a href="#file_exists" class="autotype" title="Tells if a file exists.">file_exists</a>("franken.dat", 0, NULL))
<a href="alleg000.html#allegro_message" class="autotype" title="Used mainly to show error messages to users.">allegro_message</a>("It is alive!\n");</pre></blockquote>
<p><b>Return value:</b>
Returns non-zero if the file exists, or zero if it doesn't or the
specified attributes mask it out.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#exists" title="Shortcut version of file_exists() for normal files.">exists</a>,
<a class="xref" href="#file_size_ex" title="Returns the size of a file in bytes.">file_size_ex</a>,
<a class="xref" href="#file_time" title="Returns the modification time of a file.">file_time</a>.</blockquote>
<div class="al-api"><b>int <a name="exists">exists</a>(const char *filename);</b></div><br>
Shortcut version of file_exists(), which checks for normal files, which
may have the archive or read-only bits set, but are not hidden,
directories, system files, etc.
<p><b>Return value:</b>
Returns non-zero if the file exists, or zero if it doesn't.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#file_exists" title="Tells if a file exists.">file_exists</a>,
<a class="xref" href="#file_size_ex" title="Returns the size of a file in bytes.">file_size_ex</a>,
<a class="xref" href="#file_time" title="Returns the modification time of a file.">file_time</a>.</blockquote>
<div class="al-api"><b>uint64_t <a name="file_size_ex">file_size_ex</a>(const char *filename);</b></div><br>
Returns the size of a file, in bytes. If the file does not exist or an
error occurs, it will return zero and store the system error code in
errno.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#file_exists" title="Tells if a file exists.">file_exists</a>,
<a class="xref" href="#file_time" title="Returns the modification time of a file.">file_time</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#expackf" title="Using custom PACKFILE vtables.">expackf</a>.</blockquote>
<div class="al-api"><b>time_t <a name="file_time">file_time</a>(const char *filename);</b></div><br>
Returns the modification time (number of seconds since 00:00:00 GMT
1/1/1970) of a file. If the file does not exist or an error occurs, it
will return zero and store the system error code in errno.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#file_exists" title="Tells if a file exists.">file_exists</a>,
<a class="xref" href="#file_size_ex" title="Returns the size of a file in bytes.">file_size_ex</a>.</blockquote>
<div class="al-api"><b>int <a name="delete_file">delete_file</a>(const char *filename);</b></div><br>
Removes a file from the disk. You can't delete directories, though.
<p><b>Return value:</b>
Returns zero on success, non-zero on failure.
<p><br>
<div class="al-api"><b>int <a name="for_each_file_ex">for_each_file_ex</a>(const char *name, int in_attrib, int out_attrib,
int (*callback)(const char *filename, int attrib,
void *param), void *param);</b></div><br>
Finds all the files on disk which match the given wildcard specification
and file attributes, and executes callback() once for each. Basically, this
is a convenient wrapper around al_findfirst(), al_findnext() and
al_findclose(). <tt>`in_attrib'</tt> is a bitmask specifying the attributes the
files must carry, <tt>`out_attrib'</tt> is a bitmask specifying the attributes the
files must not carry; attributes which are not specified in either bitmasks
are not taken into account for deciding whether callback() is invoked or
not.
<p>
The callback function will be passed three arguments: the first is a string
which contains the completed filename (exactly the same string you passed
to for_each_file_ex() but with meta characters), the second is the actual
attributes of the file, and the third is a void pointer which is simply a
copy of <tt>`param'</tt> (you can use this for whatever you like). The callback must
return zero to let the enumeration proceed, or any non-zero value to stop
it. If an error occurs, the error code will be stored in <tt>`errno'</tt> but the
enumeration won't stop. Example:
<blockquote class="code"><pre>
int show_name(const char *filename, int attrib, void *param)
{
<a href="alleg000.html#allegro_message" class="autotype" title="Used mainly to show error messages to users.">allegro_message</a>("Caught `%s', attribs %d\n",
filename, attrib);
return 0;
}
...
count = <a href="#for_each_file_ex" class="autotype" title="Executes callback() for each file matching a wildcard.">for_each_file_ex</a>("data/level*", FA_DIREC,
0, show_name, 0);
<a href="alleg000.html#allegro_message" class="autotype" title="Used mainly to show error messages to users.">allegro_message</a>("%d game directories\n", count);</pre></blockquote>
<p><b>Return value:</b>
Returns the number of successful calls made to callback(), that is, the
number of times callback() was called and returned 0.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#al_findfirst" title="Low-level function for searching files.">al_findfirst</a>,
<a class="xref" href="#al_findnext" title="Finds the next file in a search started by al_findfirst().">al_findnext</a>,
<a class="xref" href="#al_findclose" title="Closes a previously opened search with al_findfirst().">al_findclose</a>.</blockquote>
<div class="al-api"><b>int <a name="al_findfirst">al_findfirst</a>(const char *pattern, struct <a class="autotype" href="alleg001.html#al_ffblk" title="Cross platform structure storing file information.">al_ffblk</a> *info, int attrib);</b></div><br>
Low-level function for searching files. This function finds the first
file which matches the given wildcard specification and file attributes
(see above). The information about the file (if any) will be put in the
al_ffblk structure which you have to provide. The al_ffblk structure
looks like:
<blockquote class="code"><pre>
struct <a href="alleg001.html#al_ffblk" class="autotype" title="Cross platform structure storing file information.">al_ffblk</a>
{
int attrib; - actual attributes of the file found
time_t time; - modification time of file
char name[512]; - name of file
};
</pre></blockquote>
There is some other stuff in the structure as well, but it is there for
internal use only. Example:
<blockquote class="code"><pre>
struct <a href="alleg001.html#al_ffblk" class="autotype" title="Cross platform structure storing file information.">al_ffblk</a> info;
if (<a href="#al_findfirst" class="autotype" title="Low-level function for searching files.">al_findfirst</a>("*.pcx", &info, FA_ALL) != 0) {
/* Tell user there are no PCX files. */
return;
}</pre></blockquote>
<p><b>Return value:</b>
The function returns non-zero if no match is found or if an error occurred
and, in the latter case, sets <tt>`errno'</tt> accordingly. It returns zero if a
match is found, allocating some memory for internal use in the structure.
Therefore you have to close your search when you are finished to avoid
memory leaks in your program.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#al_findnext" title="Finds the next file in a search started by al_findfirst().">al_findnext</a>,
<a class="xref" href="#al_findclose" title="Closes a previously opened search with al_findfirst().">al_findclose</a>,
<a class="xref" href="#al_ffblk_get_size" title="Get size of file returned by al_findfirst/al_findnext.">al_ffblk_get_size</a>.</blockquote>
<div class="al-api"><b>int <a name="al_findnext">al_findnext</a>(struct <a class="autotype" href="alleg001.html#al_ffblk" title="Cross platform structure storing file information.">al_ffblk</a> *info);</b></div><br>
This finds the next file in a search started by al_findfirst(). Example:
<blockquote class="code"><pre>
if (<a href="#al_findfirst" class="autotype" title="Low-level function for searching files.">al_findfirst</a>("*.pcx", &info, 0) != 0)
return;
do {
/* Do something useful here with info.name. */
} while (<a href="#al_findnext" class="autotype" title="Finds the next file in a search started by al_findfirst().">al_findnext</a>(&info) == 0);
<a href="#al_findclose" class="autotype" title="Closes a previously opened search with al_findfirst().">al_findclose</a>(&info);</pre></blockquote>
<p><b>Return value:</b>
Returns zero if a match is found, non-zero if none is found or if an
error occurred and, in the latter case, sets errno accordingly.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#al_findfirst" title="Low-level function for searching files.">al_findfirst</a>,
<a class="xref" href="#al_findclose" title="Closes a previously opened search with al_findfirst().">al_findclose</a>.</blockquote>
<div class="al-api"><b>void <a name="al_findclose">al_findclose</a>(struct <a class="autotype" href="alleg001.html#al_ffblk" title="Cross platform structure storing file information.">al_ffblk</a> *info);</b></div><br>
This closes a previously opened search with al_findfirst(). You need to
call this on all successfully opened searches to avoid memory leaks in
your program.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#al_findfirst" title="Low-level function for searching files.">al_findfirst</a>,
<a class="xref" href="#al_findnext" title="Finds the next file in a search started by al_findfirst().">al_findnext</a>.</blockquote>
<div class="al-api"><b>uint64_t <a name="al_ffblk_get_size">al_ffblk_get_size</a>(struct <a class="autotype" href="alleg001.html#al_ffblk" title="Cross platform structure storing file information.">al_ffblk</a> *info);</b></div><br>
This returns the size of the file returned by al_findfirst or al_findnext.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#al_findfirst" title="Low-level function for searching files.">al_findfirst</a>,
<a class="xref" href="#al_findnext" title="Finds the next file in a search started by al_findfirst().">al_findnext</a>,
<a class="xref" href="alleg001.html#al_ffblk" title="Cross platform structure storing file information.">al_ffblk</a>.</blockquote>
<div class="al-api"><b>int <a name="find_allegro_resource">find_allegro_resource</a>(char *dest, const char *resource,
const char *ext, const char *datafile,
const char *objectname, const char *envvar,
const char *subdir, int size);</b></div><br>
Searches for a support file, eg. <tt>`allegro.cfg'</tt> or <tt>`language.dat'</tt>. Passed a
resource string describing what you are looking for, along with extra
optional information such as the default extension, what datafile to look
inside, what the datafile object name is likely to be, any special
environment variable to check, and any subdirectory that you would like
to check as well as the default location, this function looks in a hell
of a lot of different places :-). Pass NULL for the parameters you are not
using.
<p>
Check the documentation chapter specific to your platform for information
on additional paths this function might search for. Also, don't forget
about set_allegro_resource_path() to extend the searches. Example:
<blockquote class="code"><pre>
char path[256];
int ret;
ret = <a href="#find_allegro_resource" class="autotype" title="Searches for a support file in many places.">find_allegro_resource</a>(path, "scores.cfg", NULL, NULL,
NULL, NULL, NULL, sizeof(path));
if (ret == 0) {
/* Found system wide scores file. */
} else {
/* No previous scores, create our own file. */
}</pre></blockquote>
<p><b>Return value:</b>
Returns zero on success, and stores a full path to the file (at most size
bytes) into the dest buffer.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#set_allegro_resource_path" title="Sets a specific resource search path.">set_allegro_resource_path</a>.</blockquote>
<div class="al-api"><b>int <a name="set_allegro_resource_path">set_allegro_resource_path</a>(int priority, const char *path);</b></div><br>
Sometimes Allegro doesn't look in enough places to find a resource. For
those special cases, you can call this function before loading your
resource with additional paths to search for. You set up the priorities,
higher numbers are searched for first. To modify an already setup path,
call this function with the same priority and the new path. To remove an
already setup path, call this function with the priority of the path and
NULL as the path parameter. Example:
<blockquote class="code"><pre>
<a href="#set_allegro_resource_path" class="autotype" title="Sets a specific resource search path.">set_allegro_resource_path</a>(10, "my_game/configs");
<a href="#set_allegro_resource_path" class="autotype" title="Sets a specific resource search path.">set_allegro_resource_path</a>(0, "users/configs/");
<a href="#set_allegro_resource_path" class="autotype" title="Sets a specific resource search path.">set_allegro_resource_path</a>(-45, "temp");
</pre></blockquote>
These custom paths will be valid until you call allegro_exit(). You can
call this function before install_allegro(), but after set_uformat() if
you want to use a text encoding format other than the default.
<p><b>Return value:</b>
Returns non-zero on success, zero if the path could not be added or you
wanted to remove a path and the priority used didn't have any associated
path. Modification of existing paths always succeeds.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#find_allegro_resource" title="Searches for a support file in many places.">find_allegro_resource</a>.</blockquote>
<div class="al-api"><b>void <a name="packfile_password">packfile_password</a>(const char *password);</b></div><br>
Sets the encryption password to be used for all read/write operations
on files opened in future using Allegro's packfile functions (whether
they are compressed or not), including all the save, load and config
routines. Files written with an encryption password cannot be read
unless the same password is selected, so be careful: if you forget the
key, nobody can make your data come back again! Pass NULL or an empty
string to return to the normal, non-encrypted mode. If you are using
this function to prevent people getting access to your datafiles, be
careful not to store an obvious copy of the password in your executable:
if there are any strings like "I'm the password for the datafile", it
would be fairly easy to get access to your data :-)
<p>
Note #1: when writing a packfile, you can change the password to whatever
you want after opening the file, without affecting the write operation.
On the contrary, when writing a sub-chunk of a packfile, you must make
sure that the password that was active at the time the sub-chunk was
opened is still active before closing the sub-chunk. This is guaranteed
to be true if you didn't call the packfile_password() routine in the
meantime. Read operations, either on packfiles or sub-chunks, have no
such restriction.
<p>
Note #2: as explained above, the password is used for all read/write
operations on files, including for several functions of the library that
operate on files without explicitly using packfiles (e.g. load_bitmap()).
The unencrypted mode is mandatory in order for those functions to work.
Therefore remember to call packfile_password(NULL) before using them if
you previously changed the password. As a rule of thumb, always call
packfile_password(NULL) when you are done with operations on packfiles.
The only exception to this is custom packfiles created with
pack_fopen_vtable().
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#pack_fopen" title="Opens a file according to mode.">pack_fopen</a>,
<a class="xref" href="alleg031.html#load_datafile" title="Loads a datafile into memory.">load_datafile</a>,
<a class="xref" href="#pack_fopen_vtable" title="">pack_fopen_vtable</a>.</blockquote>
<div class="al-api"><b><a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *<a name="pack_fopen">pack_fopen</a>(const char *filename, const char *mode);</b></div><br>
Opens a file according to mode, which may contain any of the flags:
<ul><li>
<tt>`r'</tt> - open file for reading.
<li>
<tt>`w'</tt> - open file for writing, overwriting any existing data.
<li>
<tt>`p'</tt> - open file in packed mode. Data will be compressed as it is
written to the file, and automatically uncompressed during read
operations. Files created in this mode will produce garbage if
they are read without this flag being set.
<li>
`!' - open file for writing in normal, unpacked mode, but add the
value F_NOPACK_MAGIC to the start of the file, so that it can
later be opened in packed mode and Allegro will automatically
detect that the data does not need to be decompressed.
</ul>
Instead of these flags, one of the constants F_READ, F_WRITE,
F_READ_PACKED, F_WRITE_PACKED or F_WRITE_NOPACK may be used as the mode
parameter.
<p>
The packfile functions also understand several "magic" filenames that are
used for special purposes. These are:
<ul><li>
`#' - read data that has been appended to your executable file with
the exedat utility, as if it was a regular independent disk file.
<li>
`filename.dat#object_name' - open a specific object from a datafile,
and read from it as if it was a regular file. You can treat nested
datafiles exactly like a normal directory structure, for example
you could open `filename.dat#graphics/level1/mapdata'.
<li>
`#object_name' - combination of the above, reading an object from a
datafile that has been appended onto your executable.
</ul>
With these special filenames, the contents of a datafile object or
appended file can be read in an identical way to a normal disk file, so
any of the file access functions in Allegro (eg. load_pcx() and
set_config_file()) can be used to read from them. Note that you can't
write to these special files, though: the fake file is read only. Also,
you must save your datafile uncompressed or with per-object compression
if you are planning on loading individual objects from it (otherwise
there will be an excessive amount of seeking when it is read).
<p>
Finally, be aware that the special Allegro object types aren't the same
format as the files you import the data from. When you import data like
bitmaps or samples into the grabber, they are converted into a special
Allegro-specific format, but the `#' marker file syntax reads the objects
as raw binary chunks. This means that if, for example, you want to use
load_pcx() to read an image from a datafile, you should import it as a
binary block rather than as a BITMAP object.
<p>
Example:
<blockquote class="code"><pre>
<a href="alleg001.html#PACKFILE" class="autotype" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *input_file;
input_file = <a href="#pack_fopen" class="autotype" title="Opens a file according to mode.">pack_fopen</a>("scores.dat", "rp");
if (!input_file)
abort_on_error("Couldn't read <tt>`scores.dat'</tt>!");</pre></blockquote>
<p><b>Return value:</b>
On success, pack_fopen() returns a pointer to a PACKFILE structure, and on
error it returns NULL and stores an error code in <tt>`errno'</tt>. An attempt to
read a normal file in packed mode will cause <tt>`errno'</tt> to be set to EDOM.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#pack_fclose" title="Closes a stream previously opened.">pack_fclose</a>,
<a class="xref" href="#pack_fopen_chunk" title="Opens a sub-chunk of a file.">pack_fopen_chunk</a>,
<a class="xref" href="#packfile_password" title="Sets the global I/O encryption password.">packfile_password</a>,
<a class="xref" href="#pack_fread" title="Reads n bytes from the stream.">pack_fread</a>,
<a class="xref" href="#pack_getc" title="Returns the next character from a stream.">pack_getc</a>,
<a class="xref" href="alleg035.html#file_select_ex" title="Displays the Allegro file selector with a caption.">file_select_ex</a>,
<a class="xref" href="#pack_fopen_vtable" title="">pack_fopen_vtable</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#expackf" title="Using custom PACKFILE vtables.">expackf</a>.</blockquote>
<div class="al-api"><b><a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *<a name="pack_fopen_vtable">pack_fopen_vtable</a>(const <a class="autotype" href="alleg001.html#PACKFILE_VTABLE" title="Packfile vtable structure, for custom packfiles.">PACKFILE_VTABLE</a> *vtable, void *userdata);</b></div><br>
Creates a new packfile structure that uses the functions specified in
the vtable instead of the standard functions. The data pointer by <tt>`vtable'</tt>
and <tt>`userdata'</tt> must remain available for the lifetime of the created
packfile.
<p>
While the created packfile structure can be used with other Allegro
functions, there are two limitations. First, opening chunks using
pack_fopen_chunk() on top of the returned packfile is not possible at this
time. And packfile_password() does not have any effect on packfiles opened
with pack_fopen_vtable().
<p><b>Return value:</b>
On success, it returns a pointer to a PACKFILE structure, and on error it
returns NULL and stores an error code in <tt>`errno'</tt>.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#pack_fopen" title="Opens a file according to mode.">pack_fopen</a>,
<a class="xref" href="#pack_fopen_chunk" title="Opens a sub-chunk of a file.">pack_fopen_chunk</a>,
<a class="xref" href="#packfile_password" title="Sets the global I/O encryption password.">packfile_password</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#expackf" title="Using custom PACKFILE vtables.">expackf</a>.</blockquote>
<div class="al-api"><b>int <a name="pack_fclose">pack_fclose</a>(<a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *f);</b></div><br>
Closes the stream <tt>`f'</tt> previously opened with pack_fopen() or
pack_fopen_vtable(). After you have closed the stream, performing
operations on it will yield errors in your application (e.g. crash it) or
even block your OS.
<p><b>Return value:</b>
Returns zero on success. On error, returns an error code which is also
stored in <tt>`errno'</tt>. This function can fail only when writing to files: if
the file was opened in read mode, it will always succeed.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#pack_fopen" title="Opens a file according to mode.">pack_fopen</a>,
<a class="xref" href="#pack_fopen_vtable" title="">pack_fopen_vtable</a>,
<a class="xref" href="#packfile_password" title="Sets the global I/O encryption password.">packfile_password</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#expackf" title="Using custom PACKFILE vtables.">expackf</a>.</blockquote>
<div class="al-api"><b>int <a name="pack_fseek">pack_fseek</a>(<a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *f, int offset);</b></div><br>
Moves the position indicator of the stream <tt>`f'</tt>. Unlike the standard fseek()
function, this only supports forward movements relative to the current
position and in read-only streams, so don't use negative offsets. Note that
seeking is very slow when reading compressed files, and so should be
avoided unless you are sure that the file is not compressed. Example:
<blockquote class="code"><pre>
input_file = <a href="#pack_fopen" class="autotype" title="Opens a file according to mode.">pack_fopen</a>("data.bin", "r");
if (!input_file)
abort_on_error("Couldn't open binary data!");
/* Skip some useless header before reading data. */
<a href="#pack_fseek" class="autotype" title="Seeks inside a stream.">pack_fseek</a>(input_file, 32);</pre></blockquote>
<p><b>Return value:</b>
Returns zero on success or a negative number on error, storing the error
code in <tt>`errno'</tt>.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#pack_fopen" title="Opens a file according to mode.">pack_fopen</a>,
<a class="xref" href="#pack_fopen_chunk" title="Opens a sub-chunk of a file.">pack_fopen_chunk</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#expackf" title="Using custom PACKFILE vtables.">expackf</a>.</blockquote>
<div class="al-api"><b>int <a name="pack_feof">pack_feof</a>(<a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *f);</b></div><br>
Finds out if you have reached the end of the file. It does not wait for you
to attempt to read beyond the end of the file, contrary to the ISO C feof()
function. The only way to know whether you have read beyond the end of the
file is to check the return value of the read operation you use (and be
wary of pack_*getl() as EOF is also a valid return value with these
functions).
<p><b>Return value:</b>
Returns non-zero if you are at the end of the file, zero otherwise.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#pack_fopen" title="Opens a file according to mode.">pack_fopen</a>,
<a class="xref" href="#pack_fopen_chunk" title="Opens a sub-chunk of a file.">pack_fopen_chunk</a>,
<a class="xref" href="#pack_ferror" title="Tells if an error occurred during an operation on the stream.">pack_ferror</a>.</blockquote>
<div class="al-api"><b>int <a name="pack_ferror">pack_ferror</a>(<a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *f);</b></div><br>
Since EOF is used to report errors by some functions, it's often better to
use the pack_feof() function to check explicitly for end of file and
pack_ferror() to check for errors. Both functions check indicators that
are part of the internal state of the stream to detect correctly the
different situations.
<p><b>Return value:</b>
Returns nonzero if the error indicator for the stream is set, meaning
that an error has occurred during a previous operation on the stream.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#pack_fopen" title="Opens a file according to mode.">pack_fopen</a>,
<a class="xref" href="#pack_fopen_chunk" title="Opens a sub-chunk of a file.">pack_fopen_chunk</a>.</blockquote>
<div class="al-api"><b>int <a name="pack_getc">pack_getc</a>(<a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *f);</b></div><br>
Returns the next character from the stream <tt>`f'</tt>, or EOF if the end of the
file has been reached.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#pack_fopen" title="Opens a file according to mode.">pack_fopen</a>,
<a class="xref" href="#pack_fopen_chunk" title="Opens a sub-chunk of a file.">pack_fopen_chunk</a>.</blockquote>
<div class="al-api"><b>int <a name="pack_ungetc">pack_ungetc</a>(int c, <a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *f);</b></div><br>
Puts a character back to the file's input buffer. Like with ungetc from
libc, only a single push back is guaranteed.
<p>
Note: pack_fgets internally uses pack_ungetc, so never use pack_ungetc
directly after using pack_fgets on a PACKFILE.
<p><b>Return value:</b>
Returns c on success, or EOF on error.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#pack_getc" title="Returns the next character from a stream.">pack_getc</a>,
<a class="xref" href="#pack_fgets" title="Reads a line from the stream.">pack_fgets</a>.</blockquote>
<div class="al-api"><b>int <a name="pack_putc">pack_putc</a>(int c, <a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *f);</b></div><br>
Puts a character in the stream f.
<p><b>Return value:</b>
Returns the character written on success, or EOF on error.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#pack_fopen" title="Opens a file according to mode.">pack_fopen</a>,
<a class="xref" href="#pack_fopen_chunk" title="Opens a sub-chunk of a file.">pack_fopen_chunk</a>.</blockquote>
<div class="al-api"><b>int <a name="pack_igetw">pack_igetw</a>(<a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *f);</b></div><br>
Like pack_getc, but reads a 16-bit word from a file, using Intel byte
ordering (least significant byte first, a.k.a. little-endian).
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#pack_getc" title="Returns the next character from a stream.">pack_getc</a>.</blockquote>
<div class="al-api"><b>int <a name="pack_iputw">pack_iputw</a>(int c, <a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *f);</b></div><br>
Like pack_putc, but writes a 16-bit word to a file, using Intel byte
ordering (least significant byte first, a.k.a. little-endian).
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#pack_putc" title="Puts a character in the stream.">pack_putc</a>.</blockquote>
<div class="al-api"><b>long <a name="pack_igetl">pack_igetl</a>(<a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *f);</b></div><br>
Like pack_getc, but reads a 32-bit long from a file, using Intel byte
ordering (least significant byte first, a.k.a. little-endian).
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#pack_getc" title="Returns the next character from a stream.">pack_getc</a>.</blockquote>
<div class="al-api"><b>long <a name="pack_iputl">pack_iputl</a>(long c, <a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *f);</b></div><br>
Like pack_putc, but writes a 32-bit long to a file, using Intel byte
ordering (least significant byte first, a.k.a. little-endian).
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#pack_putc" title="Puts a character in the stream.">pack_putc</a>.</blockquote>
<div class="al-api"><b>int <a name="pack_mgetw">pack_mgetw</a>(<a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *f);</b></div><br>
Like pack_getc, but reads a 16-bit word from a file, using Motorola byte
ordering (most significant byte first, a.k.a. big-endian).
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#pack_getc" title="Returns the next character from a stream.">pack_getc</a>.</blockquote>
<div class="al-api"><b>int <a name="pack_mputw">pack_mputw</a>(int c, <a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *f);</b></div><br>
Like pack_putc, but writes a 16-bit word to a file, using Motorola byte
ordering (most significant byte first, a.k.a. big-endian).
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#pack_putc" title="Puts a character in the stream.">pack_putc</a>.</blockquote>
<div class="al-api"><b>long <a name="pack_mgetl">pack_mgetl</a>(<a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *f);</b></div><br>
Like pack_getc, but reads a 32-bit long from a file, using Motorola byte
ordering (most significant byte first, a.k.a. big-endian).
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#pack_getc" title="Returns the next character from a stream.">pack_getc</a>.</blockquote>
<div class="al-api"><b>long <a name="pack_mputl">pack_mputl</a>(long c, <a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *f);</b></div><br>
Like pack_putc, but writes a 32-bit long to a file, using Motorola byte
ordering (most significant byte first, a.k.a. big-endian).
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#pack_putc" title="Puts a character in the stream.">pack_putc</a>.</blockquote>
<div class="al-api"><b>long <a name="pack_fread">pack_fread</a>(void *p, long n, <a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *f);</b></div><br>
Reads <tt>`n'</tt> bytes from the stream <tt>`f'</tt>, storing them at the memory location
pointed to by <tt>`p'</tt>. Example:
<blockquote class="code"><pre>
unsigned char buf[256];
...
if (<a href="#pack_fread" class="autotype" title="Reads n bytes from the stream.">pack_fread</a>(buf, 256, input_file) != 256)
abort_on_error("Truncated input file!");</pre></blockquote>
<p><b>Return value:</b>
Returns the number of bytes read, which will be less than <tt>`n'</tt> if EOF is
reached or an error occurs. Error codes are stored in errno.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#pack_fopen" title="Opens a file according to mode.">pack_fopen</a>,
<a class="xref" href="#pack_fopen_chunk" title="Opens a sub-chunk of a file.">pack_fopen_chunk</a>,
<a class="xref" href="#pack_feof" title="Returns nonzero as soon as you reach the end of the file.">pack_feof</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#expackf" title="Using custom PACKFILE vtables.">expackf</a>.</blockquote>
<div class="al-api"><b>long <a name="pack_fwrite">pack_fwrite</a>(const void *p, long n, <a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *f);</b></div><br>
Writes <tt>`n'</tt> bytes to the stream <tt>`f'</tt> from memory location pointed to by <tt>`p'</tt>.
<p><b>Return value:</b>
Returns the number of bytes written, which will be less than n if an
error occurs. Error codes are stored in errno.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#pack_fopen" title="Opens a file according to mode.">pack_fopen</a>,
<a class="xref" href="#pack_fopen_chunk" title="Opens a sub-chunk of a file.">pack_fopen_chunk</a>,
<a class="xref" href="#pack_feof" title="Returns nonzero as soon as you reach the end of the file.">pack_feof</a>.</blockquote>
<div class="al-api"><b>char *<a name="pack_fgets">pack_fgets</a>(char *p, int max, <a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *f);</b></div><br>
Reads a line from the stream <tt>`f'</tt>, storing it at location pointed to by
<tt>`p'</tt>. Stops when a linefeed is encountered, or <tt>`max'</tt> bytes have been read.
The end of line is handled by detecting the right combination of characters
for the platform. This supports CR-LF (DOS/Windows), LF (Unix), and CR
(Mac) formats. However, the trailing carriage return is not included in the
returned string, in order to provide easy code portability across
platforms. If you need the carriage return, use pack_fread() and/or
pack_getc() instead.
<p>
Note: This function internally may make calls to pack_ungetc, so you cannot
use pack_ungetc directly afterwards.
<p>
Example:
<blockquote class="code"><pre>
char buf[256];
...
while (<a href="#pack_fgets" class="autotype" title="Reads a line from the stream.">pack_fgets</a>(buf, sizeof(buf), input_file)) {
/* Process input <a href="alleg013.html#line" class="autotype" title="Draws a line onto the bitmap.">line</a>. */
}
fclose(input_file);</pre></blockquote>
<p><b>Return value:</b>
Returns the pointer <tt>`p'</tt> on success, or NULL on error.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#pack_fopen" title="Opens a file according to mode.">pack_fopen</a>,
<a class="xref" href="#pack_fopen_chunk" title="Opens a sub-chunk of a file.">pack_fopen_chunk</a>,
<a class="xref" href="#pack_fread" title="Reads n bytes from the stream.">pack_fread</a>,
<a class="xref" href="#pack_getc" title="Returns the next character from a stream.">pack_getc</a>,
<a class="xref" href="#pack_ungetc" title="Moves one single character back to the input buffer.">pack_ungetc</a>.</blockquote>
<div class="al-api"><b>int <a name="pack_fputs">pack_fputs</a>(const char *p, <a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *f);</b></div><br>
Writes a string to the stream <tt>`f'</tt>. The input string is converted from the
current text encoding format to UTF-8 before writing. Newline characters
are written as <tt>`\r\n'</tt> on DOS and Windows platforms. If you don't want this
behaviour, use pack_fwrite() and/or pack_putc() instead.
<p><b>Return value:</b>
Returns zero on success or a negative number on error.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#pack_fopen" title="Opens a file according to mode.">pack_fopen</a>,
<a class="xref" href="#pack_fopen_chunk" title="Opens a sub-chunk of a file.">pack_fopen_chunk</a>,
<a class="xref" href="#pack_fwrite" title="Writes n bytes to the stream.">pack_fwrite</a>,
<a class="xref" href="#pack_putc" title="Puts a character in the stream.">pack_putc</a>.</blockquote>
<div class="al-api"><b><a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *<a name="pack_fopen_chunk">pack_fopen_chunk</a>(<a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *f, int pack);</b></div><br>
Opens a sub-chunk of a file. Chunks are primarily intended for use by the
datafile code, but they may also be useful for your own file routines. A
chunk provides a logical view of part of a file, which can be compressed
as an individual entity and will automatically insert and check length
counts to prevent reading past the end of the chunk. The PACKFILE
parameter is a previously opened file, and <tt>`pack'</tt> is a boolean parameter
which will turn compression on for the sub-chunk if it is non-zero.
Example:
<blockquote class="code"><pre>
<a href="alleg001.html#PACKFILE" class="autotype" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *output = <a href="#pack_fopen" class="autotype" title="Opens a file according to mode.">pack_fopen</a>("out.raw", "w!");
...
/* Create a sub-chunk with compression. */
output = <a href="#pack_fopen_chunk" class="autotype" title="Opens a sub-chunk of a file.">pack_fopen_chunk</a>(output, 1);
if (!output)
abort_on_error("Error saving data!");
/* Write some data to the sub-chunk. */
...
/* Close the sub-chunk, recovering parent file. */
output = <a href="#pack_fclose_chunk" class="autotype" title="Closes a previously opened sub-chunk.">pack_fclose_chunk</a>(output);
</pre></blockquote>
The data written to the chunk will be prefixed with two length counts
(32-bit, a.k.a. big-endian). For uncompressed chunks these will both be
set to the size of the data in the chunk. For compressed chunks (created
by setting the <tt>`pack'</tt> flag), the first length will be the raw size of the
chunk, and the second will be the negative size of the uncompressed data.
<p>
To read the chunk, use the following code:
<blockquote class="code"><pre>
<a href="alleg001.html#PACKFILE" class="autotype" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *input = <a href="#pack_fopen" class="autotype" title="Opens a file according to mode.">pack_fopen</a>("out.raw", "rp");
...
input = <a href="#pack_fopen_chunk" class="autotype" title="Opens a sub-chunk of a file.">pack_fopen_chunk</a>(input, 1);
/* Read data from the sub-chunk and close it. */
...
input = <a href="#pack_fclose_chunk" class="autotype" title="Closes a previously opened sub-chunk.">pack_fclose_chunk</a>(input);
</pre></blockquote>
This sequence will read the length counts created when the chunk was
written, and automatically decompress the contents of the chunk if it
was compressed. The length will also be used to prevent reading past the
end of the chunk (Allegro will return EOF if you attempt this), and to
automatically skip past any unread chunk data when you call
pack_fclose_chunk().
<p>
Chunks can be nested inside each other by making repeated calls to
pack_fopen_chunk(). When writing a file, the compression status is
inherited from the parent file, so you only need to set the pack flag if
the parent is not compressed but you want to pack the chunk data. If the
parent file is already open in packed mode, setting the pack flag will
result in data being compressed twice: once as it is written to the
chunk, and again as the chunk passes it on to the parent file.
<p><b>Return value:</b>
Returns a pointer to the sub-chunked PACKFILE, or NULL if there was some
error (eg. you are using a custom PACKFILE vtable).
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#pack_fclose_chunk" title="Closes a previously opened sub-chunk.">pack_fclose_chunk</a>,
<a class="xref" href="#pack_fopen" title="Opens a file according to mode.">pack_fopen</a>.</blockquote>
<div class="al-api"><b><a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *<a name="pack_fclose_chunk">pack_fclose_chunk</a>(<a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *f);</b></div><br>
Closes a sub-chunk of a file, previously obtained by calling
pack_fopen_chunk().
<p><b>Return value:</b>
Returns a pointer to the parent of the sub-chunk you just closed. Returns
NULL if there was some error (eg. you tried to close a PACKFILE which
wasn't sub-chunked).
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#pack_fopen_chunk" title="Opens a sub-chunk of a file.">pack_fopen_chunk</a>.</blockquote>
<div class="al-api"><b><a class="autotype" href="alleg001.html#LZSS_PACK_DATA" title="Opaque structure for handling LZSS compression.">LZSS_PACK_DATA</a> *<a name="create_lzss_pack_data">create_lzss_pack_data</a>(void);</b></div><br>
Creates an LZSS_PACK_DATA structure, which can be used for LZSS
compression with PACKFILEs.
<p><b>Return value:</b>
Returns a pointer to the structure, or NULL if there was an error.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#free_lzss_pack_data" title="Frees an LZSS structure.">free_lzss_pack_data</a>.</blockquote>
<div class="al-api"><b>void <a name="free_lzss_pack_data">free_lzss_pack_data</a>(<a class="autotype" href="alleg001.html#LZSS_PACK_DATA" title="Opaque structure for handling LZSS compression.">LZSS_PACK_DATA</a> *dat);</b></div><br>
Frees an LZSS_PACK_DATA structure created with create_lzss_pack_data().
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#create_lzss_pack_data" title="Creates an LZSS structure for compression.">create_lzss_pack_data</a>.</blockquote>
<div class="al-api"><b>int <a name="lzss_write">lzss_write</a>(<a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *file, <a class="autotype" href="alleg001.html#LZSS_PACK_DATA" title="Opaque structure for handling LZSS compression.">LZSS_PACK_DATA</a> *dat, int size,
unsigned char *buf, int last);</b></div><br>
Packs <tt>`size'</tt> bytes from <tt>`buf'</tt>, using the pack information contained in
<tt>`dat'</tt>. The compressed bytes will be stored in <tt>`file'</tt>.
<p><b>Return value:</b>
Returns 0 on success, or EOF if there was an error.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#create_lzss_pack_data" title="Creates an LZSS structure for compression.">create_lzss_pack_data</a>,
<a class="xref" href="#free_lzss_pack_data" title="Frees an LZSS structure.">free_lzss_pack_data</a>.</blockquote>
<div class="al-api"><b><a class="autotype" href="alleg001.html#LZSS_UNPACK_DATA" title="Opaque structure for handling LZSS decompression.">LZSS_UNPACK_DATA</a> *<a name="create_lzss_unpack_data">create_lzss_unpack_data</a>(void);</b></div><br>
Creates an LZSS_UNPACK_DATA structure, which can be used for LZSS
decompression reading PACKFILEs.
<p><b>Return value:</b>
Returns a pointer to the structure, or NULL if there was an error.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#free_lzss_unpack_data" title="Frees an LZSS structure.">free_lzss_unpack_data</a>.</blockquote>
<div class="al-api"><b>void <a name="free_lzss_unpack_data">free_lzss_unpack_data</a>(<a class="autotype" href="alleg001.html#LZSS_UNPACK_DATA" title="Opaque structure for handling LZSS decompression.">LZSS_UNPACK_DATA</a> *dat);</b></div><br>
Frees an LZSS_UNPACK_DATA structure created with create_lzss_pack_data.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#create_lzss_unpack_data" title="Creates an LZSS structure for decompression.">create_lzss_unpack_data</a>.</blockquote>
<div class="al-api"><b>int <a name="lzss_read">lzss_read</a>(<a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *file, <a class="autotype" href="alleg001.html#LZSS_UNPACK_DATA" title="Opaque structure for handling LZSS decompression.">LZSS_UNPACK_DATA</a> *dat, int s,
unsigned char *buf);</b></div><br>
Unpacks from <tt>`dat'</tt> into <tt>`buf'</tt>, until either EOF is reached or <tt>`s'</tt> bytes
have been extracted from <tt>`file'</tt>.
<p><b>Return value:</b>
Returns the number of bytes added to the buffer <tt>`buf'</tt>.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#free_lzss_unpack_data" title="Frees an LZSS structure.">free_lzss_unpack_data</a>.</blockquote>
<hr><div class="al-back-to-contents"><a href="allegro.html">Back to contents</a></div>
</body>
</html>
distrib
>
Arklinux
>
devel
>
x86_64
>
media
>
main
>
by-pkgid
>
c13bc007afe382f898b3b1cfcaf62e82
>
files
>
803
