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)