NAME

       pack_fopen - Opens a file according to mode. Allegro game programming library.

SYNOPSIS

       #include <allegro.h>

       PACKFILE *pack_fopen(const char *filename, const char *mode);

DESCRIPTION

       Opens a file according to mode, which may contain any of the flags:

       `r' - open file for reading.

       `w' - open file for writing, overwriting any existing data.

       `p'  - 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.

       `!'  - 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.

       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.

       The packfile functions also understand several "magic" filenames that are used for special
       purposes. These are:

       `#' - read data that has been appended to your executable file with the exedat utility, as
       if it was a regular independent disk file.

       `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'.

       `#object_name' - combination of the above, reading an object from a datafile that has been
       appended onto your executable.

       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).

       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.

       Example:

          PACKFILE *input_file;

          input_file = pack_fopen("scores.dat", "rp");
          if (!input_file)
             abort_on_error("Couldn't read `scores.dat'!");

RETURN VALUE

       On success, pack_fopen() returns a pointer to  a  PACKFILE  structure,  and  on  error  it
       returns  NULL  and  stores  an  error code in `errno'. An attempt to read a normal file in
       packed mode will cause `errno' to be set to EDOM.

SEE ALSO

       pack_fclose(3alleg4),        pack_fopen_chunk(3alleg4),        packfile_password(3alleg4),
       pack_fread(3alleg4),              pack_getc(3alleg4),             file_select_ex(3alleg4),
       pack_fopen_vtable(3alleg4), expackf(3alleg4)