bionic (3) pack_fopen_chunk.3alleg4.gz

NAME

       pack_fopen_chunk - Opens a sub-chunk of a file. Allegro game programming library.

SYNOPSIS

       #include <allegro.h>

       PACKFILE *pack_fopen_chunk(PACKFILE *f, int pack);

DESCRIPTION

       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  `pack'  is  a
       boolean parameter which will turn compression on for the sub-chunk if it is non-zero.  Example:

          PACKFILE *output = pack_fopen("out.raw", "w!");
          ...
          /* Create a sub-chunk with compression. */
          output = pack_fopen_chunk(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 = pack_fclose_chunk(output);

       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 `pack' flag), the first length will be the raw size of the chunk, and the second
       will be the negative size of the uncompressed data.

       To read the chunk, use the following code:

          PACKFILE *input = pack_fopen("out.raw", "rp");
          ...
          input = pack_fopen_chunk(input, 1);
          /* Read data from the sub-chunk and close it. */
          ...
          input = pack_fclose_chunk(input);

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

       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.

RETURN VALUE

       Returns  a  pointer  to  the  sub-chunked  PACKFILE, or NULL if there was some error (eg. you are using a
       custom PACKFILE vtable).

SEE ALSO

       pack_fclose_chunk(3alleg4), pack_fopen(3alleg4)