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)