pack_fopen(3)

✨ pack_fopen(3) ✨

okay bestie, sit down, we're opening files today 💅 this one lives in the Allegro manual, and it's literally the gateway drug to every single file in your game. group-chat energy: ON.

---

🌸 NAME 🌸

pack_fopen — opens a file according to mode. Allegro game programming library. no cap. 📂

---

🦋 SYNOPSIS 🦋

#include <allegro.h>

PACKFILE *pack_fopen(const char *filename, const char *mode);

---

💖 DESCRIPTION 💖

So, like, it opens a file according to mode, and mode is a little string of flags that can contain any of these cuties:

• r — open file for reading. just vibes, no writing, we're just looking 👀
• w — open file for writing, and it overwrites any existing data. gone. bye. periodt 💀
• p — open file in packed mode. the data gets compressed as it's written, and automatically uncompressed during read operations. it's giving magic. BUT: files created in this mode will produce garbage if they're read without this flag being set. so don't do that, bestie, that's a trap 🙈
• ! — open file for writing in normal, unpacked mode, but it adds the value F_NOPACK_MAGIC to the start of the file, so that it can later be opened in packed mode and Allegro will automatically detect that the data does not need to be decompressed. it's a little note-to-self, iconic behavior 🎀

Instead of these flags, you can also use one of the constants F_READ, F_WRITE, F_READ_PACKED, F_WRITE_PACKED or F_WRITE_NOPACK as the mode parameter. same energy, different spelling ✨

---

🧚 the magic filenames 🧚

The packfile functions also understand several "magic" filenames that are used for special purposes. these are:

• # — read data that has been appended to your executable file with the exedat utility, as if it was a regular independent disk file. your .exe is now also a .zip, we love a multitasker 🫶
• filename.dat#object_name — open a specific object from a datafile, and read from it as if it was a regular file. and the nested datafiles? you can treat them exactly like a normal directory structure. for example you could open filename.dat#graphics/level1/mapdata. directories inside files inside executables, it's giving inception 🌈
• #object_name — combination of the above two, reading an object from a datafile that has been appended onto your executable. the mashup nobody asked for but everybody needed 👑

With these special filenames, the contents of a datafile object or appended file can be read in an identical way to a normal disk file, so any of the file access functions in Allegro (eg. load_pcx() and set_config_file()) can be used to read from them. like, free real estate.

⚠️ big note: you can't write to these special files. the fake file is read only. that's the rule, that's the boundary, respect it 💅

⚠️ also: you must save your datafile uncompressed or with per-object compression if you are planning on loading individual objects from it. otherwise there will be an excessive amount of seeking when it is read. nobody wants that. it's giving slow. 😭

---

🎀 one more thing, fr fr 🎀

Finally, be aware that the special Allegro object types aren't the same format as the files you import the data from. When you import data like bitmaps or samples into the grabber, they get converted into a special Allegro-specific format, but the # marker file syntax reads the objects as raw binary chunks. so if, for example, you want to use load_pcx() to read an image from a datafile, you should import it as a binary block rather than as a BITMAP object. iykyk ⭐

---

🍓 example 🍓

PACKFILE *input_file;

input_file = pack_fopen("scores.dat", "rp");
if (!input_file)
   abort_on_error("Couldn't read `scores.dat'!");

look at that. clean. rp = read + packed. chef's kiss 👑✨

---

💜 RETURN VALUE 💜

On success, pack_fopen() returns a pointer to a PACKFILE structure. on error it returns NULL and stores an error code in errno.

heads up: an attempt to read a normal file in packed mode will cause errno to be set to EDOM. so if you see EDOM, that's why. it's not a you problem, it's a mode problem 🙈

---

🔥 SEE ALSO 🔥

• pack_fclose(3)
• pack_fopen_chunk(3)
• packfile_password(3)
• pack_fread(3)
• pack_getc(3)
• file_select_ex(3)
• pack_fopen_vtable(3)
• expackf(3)

---

and that's the whole page, bestie!! this was Allegro, version 4.4.3, and yes, the page is literally called pack_fopen(3), we love a self-titled moment 🎀 go forth and open files responsibly. mwah 💋