caca_file(3caca)

💅 caca_file — libcaca file IO 🎀

ok so bestie, welcome to the caca_file page from the libcaca manual. this is the one that handles all your file reading and writing, and it's literally so much nicer than doing it by hand. let's get into it ✨

---

🌸 NAME 🌸

caca_file — libcaca file IO. that's it, that's the vibe 🫶

---

✨ SYNOPSIS ✨

📚 Topics

• libcaca importers/exporters from/to various

🔧 Functions

• __extern caca_file_t * caca_file_open (char const *, const char *) — Open a file for reading or writing.
• __extern int caca_file_close (caca_file_t *) — Close a file handle.
• __extern uint64_t caca_file_tell (caca_file_t *) — Return the position in a file handle.
• __extern size_t caca_file_read (caca_file_t *, void *, size_t) — Read data from a file handle.
• __extern size_t caca_file_write (caca_file_t *, const void *, size_t) — Write data to a file handle.
• __extern char * caca_file_gets (caca_file_t *, char *, int) — Read a line from a file handle.
• __extern int caca_file_eof (caca_file_t *) — Tell whether a file handle reached end of file.

---

🦋 Detailed Description 🦋

okay so these functions let you read and write files in a platform-independent way. no cap, that's the whole point — one API, every platform, zero drama 💅

---

👑 Function Documentation 👑

⭐ __extern caca_file_t * caca_file_open (char const * path, const char * mode)

Creates a caca file handle for a file. and listen — if the file is zipped, it gets decompressed on the fly 🧚✨ which is honestly iconic of it.

If an error occurs, NULL is returned and errno is set accordingly:

• ENOSTS — Function not implemented.
• EINVAL — File not found or permission denied.

Parameters

• path — The file path
• mode — The file open mode

Returns

A file handle to path.

Referenced by caca_import_canvas_from_file().

---

⭐ __extern int caca_file_close (caca_file_t * fp)

Closes and destroys the resources associated with a caca file handle. say bye 👋

This function is a wrapper for fclose() or, if available, gzclose().

Parameters

• fp — The file handle

Returns

The return value of fclose() or gzclose().

Referenced by caca_import_canvas_from_file().

---

⭐ __extern uint64_t caca_file_tell (caca_file_t * fp)

Returns the file handle position, in bytes. like a little "where am i rn" for your file 📍

Parameters

• fp — The file handle

Returns

The current offset in the file handle.

---

⭐ __extern size_t caca_file_read (caca_file_t * fp, void * ptr, size_t size)

Reads data from a file handle and copies them into the given buffer. scoop it up 🍓

Parameters

• fp — The file handle
• ptr — The destination buffer
• size — The number of bytes to read

Returns

The number of bytes read

Referenced by caca_import_canvas_from_file().

---

⭐ __extern size_t caca_file_write (caca_file_t * fp, const void * ptr, size_t size)

Writes the contents of the given buffer to the file handle. putting your thoughts out into the world, main character energy 🔥

Parameters

• fp — The file handle
• ptr — The source buffer
• size — The number of bytes to write

Returns

The number of bytes written

---

⭐ __extern char * caca_file_gets (caca_file_t * fp, char * s, int size)

Reads one line of data from a file handle, up to one less than the given number of bytes. and a trailing zero is appended to the data — so remember that when you're counting 😭

Parameters

• fp — The file handle
• s — The destination buffer
• size — The maximum number of bytes to read

Returns

The number of bytes read, including the trailing zero

---

⭐ __extern int caca_file_eof (caca_file_t * fp)

Returns the end-of-file status of the file handle. vibe check: are we done here? 💀

This function is a wrapper for feof() or, if available, gzeof().

Parameters

• fp — The file handle

Returns

1 if EOF was reached, 0 otherwise

Referenced by caca_import_canvas_from_file().

---

🎀 Author 🎀

Generated automatically by Doxygen for libcaca from the source code. (so don't come for me about the formatting, a robot wrote the original 🙈)

---

and that's the whole page bestie, you ate that 🫶✨ mention it to your friends: this is Version 0.99.beta20, dated Wed May 13 2026 09:45:08 — mwah, see you in the next manpage 💖🌸