1pack_fopen_chunk(3) Allegro manual pack_fopen_chunk(3)
2
6 pack_fopen_chunk - Opens a sub-chunk of a file. Allegro game program‐
7 ming library.
8
10 #include <allegro.h>
11 PACKFILE *pack_fopen_chunk(PACKFILE *f, int pack);
14
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 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 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 To read the chunk, use the following code:
44 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 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 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
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
73 pack_fclose_chunk(3), pack_fopen(3)
74Allegro version 4.2.3 pack_fopen_chunk(3)