1pack_fopen_chunk(3)             Allegro manual             pack_fopen_chunk(3)
2
3
4

NAME

6       pack_fopen_chunk  -  Opens a sub-chunk of a file. Allegro game program‐
7       ming library.
8

SYNOPSIS

10       #include <allegro.h>
11
12
13       PACKFILE *pack_fopen_chunk(PACKFILE *f, int pack);
14

DESCRIPTION

16       Opens a sub-chunk of a file. Chunks are primarily intended for  use  by
17       the  datafile  code, but they may also be useful for your own file rou‐
18       tines. A chunk provides a logical view of part of a file, which can  be
19       compressed  as  an  individual entity and will automatically insert and
20       check length counts to prevent reading past the end of the  chunk.  The
21       PACKFILE parameter is a previously opened file, and `pack' is a boolean
22       parameter which will turn compression on for the  sub-chunk  if  it  is
23       non-zero.  Example:
24
25          PACKFILE *output = pack_fopen("out.raw", "w!");
26          ...
27          /* Create a sub-chunk with compression. */
28          output = pack_fopen(chunk(output, 1);
29          if (!output)
30             abort_on_error("Error saving data!");
31          /* Write some data to the sub-chunk. */
32          ...
33          /* Close the sub-chunk, recovering parent file. */
34          output = pack_fclose_chunk(output);
35
36       The  data  written to the chunk will be prefixed with two length counts
37       (32-bit, a.k.a. big-endian). For uncompressed chunks these will both be
38       set  to  the size of the data in the chunk. For compressed chunks (cre‐
39       ated by setting the `pack' flag), the first length will be the raw size
40       of  the  chunk,  and the second will be the negative size of the uncom‐
41       pressed data.
42
43       To read the chunk, use the following code:
44
45          PACKFILE *input = pack_fopen("out.raw", "rp");
46          ...
47          input = pack_fopen_chunk(input, 1);
48          /* Read data from the sub-chunk and close it. */
49          ...
50          input = pack_fclose_chunk(input);
51
52       This sequence will read the length counts created when  the  chunk  was
53       written,  and  automatically decompress the contents of the chunk if it
54       was compressed. The length will also be used to  prevent  reading  past
55       the end of the chunk (Allegro will return EOF if you attempt this), and
56       to automatically  skip  past  any  unread  chunk  data  when  you  call
57       pack_fclose_chunk().
58
59       Chunks  can  be  nested  inside  each other by making repeated calls to
60       pack_fopen_chunk(). When writing a  file,  the  compression  status  is
61       inherited  from  the parent file, so you only need to set the pack flag
62       if the parent is not compressed but you want to pack the chunk data. If
63       the  parent  file is already open in packed mode, setting the pack flag
64       will result in data being compressed twice: once as it  is  written  to
65       the chunk, and again as the chunk passes it on to the parent file.
66

RETURN VALUE

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

SEE ALSO

73       pack_fclose_chunk(3), pack_fopen(3)
74
75
76
77Allegro                          version 4.2.3             pack_fopen_chunk(3)
Impressum