pack_fopen_chunk(3)

✨ pack_fopen_chunk ✨

okay bestie, welcome to the Allegro manual 💖 this one is pack_fopen_chunk(3) and it's genuinely so useful. sit down, grab a strawberry 🍓, we're opening sub-chunks today.

---

🌸 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 👑

so like. 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. no gatekeeping here 💅

A chunk gives you 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. it's giving little self-contained bubble of data, fr fr 🫧

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. yes, negative. iconic behavior honestly 😌

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(). so it cleans up after itself, unlike some people 🙈

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.

⚠️ bestie listen. 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. double compression, double the vibe tax 💀 not what you want.

---

💜 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). so always vibe check your return value, okay? 🫶

---

🌈 SEE ALSO 🌈

• pack_fclose_chunk(3)
• pack_fopen(3)

---

that's the whole page, no cap ✨ this was the Allegro manual for pack_fopen_chunk(3), and the footer is serving Allegro, version 4.4.3 — go read the source date on the real page if you need it, bc that's all the footer gave us. mwah, go forth and chunk responsibly 💅🎀🦋