caca_importexport(3caca)

📦
version 0.99.beta20 · 13 versions
, in opensuse-leap 16.0

💅 caca_importexport — importers & exporters, the whole glow-up

Okay so bestie, welcome to caca_importexport(3caca) from libcaca — this is the page where your canvas learns to talk to the outside world (importing) and to post its whole look (exporting). Slay. 🦋

✨ NAME ✨

caca_importexport — libcaca importers/exporters from/to various formats. That's it, that's the vibe: formats in, formats out. 💫

🎀 SYNOPSIS 🎀

🌸 Topics

  • libcaca display functions

🫶 Functions

  • __extern ssize_t caca_import_canvas_from_memory (caca_canvas_t *, void const *, size_t, char const *) — import a memory buffer into a canvas.
  • __extern ssize_t caca_import_canvas_from_file (caca_canvas_t *, char const *, char const *) — import a file into a canvas.
  • __extern ssize_t caca_import_area_from_memory (caca_canvas_t *, int, int, void const *, size_t, char const *) — import a memory buffer into a canvas area.
  • __extern ssize_t caca_import_area_from_file (caca_canvas_t *, int, int, char const *, char const *) — import a file into a canvas area.
  • __extern char const *const * caca_get_import_list (void) — get available import formats.
  • __extern void * caca_export_canvas_to_memory (caca_canvas_t const *, char const *, size_t *) — export a canvas into a foreign format.
  • __extern void * caca_export_area_to_memory (caca_canvas_t const *, int, int, int, int, char const *, size_t *) — export a canvas portion into a foreign format.
  • __extern char const *const * caca_get_export_list (void) — get available export formats.

💖 DETAILED DESCRIPTION 💖

Literally what it says on the tin, queen: these functions import various file formats into a new canvas, or export the current canvas to various text formats. In and out. That's the whole main character arc. 🔥

👑 FUNCTION DOCUMENTATION 👑

🌈 __extern ssize_t caca_import_canvas_from_memory (caca_canvas_t * cv, void const * data, size_t len, char const * format)

Imports a memory buffer into the given libcaca canvas's current frame. The current frame gets resized accordingly and its contents are replaced with the imported data. No leftovers, no crumbs — full replacement energy. 💅

Valid values for format are, and I need you to note these down:

  • "" — attempt to autodetect the file format (she'll figure it out herself).
  • "caca" — import native libcaca files.
  • "text" — import ASCII text files.
  • "ansi" — import ANSI files.
  • "utf8" — import UTF-8 files with ANSI colour codes.
  • "bin" — import BIN files.

The number of bytes read is returned. If the file format is valid but there wasn't enough data, 0 is returned. (Not an error, just an "mmkay bestie, send more" moment.)

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

  • ENOMEM — not enough memory to allocate canvas.
  • EOVERFLOW — importing data caused a value overflow.
  • EINVAL — invalid format requested.

🍓 Parameters

  • cv — a libcaca canvas in which to import the file.
  • data — a memory area containing the data to be loaded into the canvas.
  • len — the size in bytes of the memory area.
  • format — a string describing the input format.

💜 Returns

The number of bytes read, or 0 if there was not enough data, or -1 if an error occurred.

⭐ Referenced by

caca_import_area_from_memory(), and caca_import_canvas_from_file().

🧚 __extern ssize_t caca_import_canvas_from_file (caca_canvas_t * cv, char const * filename, char const * format)

Imports a file into the given libcaca canvas's current frame. The current frame is resized accordingly and its contents are replaced with the imported data. Same energy as above, except she's reading from disk now. 📂

Valid values for format are:

  • "" — attempt to autodetect the file format.
  • "caca" — import native libcaca files.
  • "text" — import ASCII text files.
  • "ansi" — import ANSI files.
  • "utf8" — import UTF-8 files with ANSI colour codes.
  • "bin" — import BIN files.

The number of bytes read is returned. If the file format is valid, but not enough data was available, 0 is returned.

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

  • ENOSYS — file access is not implemented on this system.
  • ENOMEM — not enough memory to allocate canvas.
  • EINVAL — invalid format requested. caca_import_file() may also fail and set errno for any of the errors specified for the routine fopen().

🍓 Parameters

  • cv — a libcaca canvas in which to import the file.
  • filename — the name of the file to load.
  • format — a string describing the input format.

💜 Returns

The number of bytes read, or 0 if there was not enough data, or -1 if an error occurred.

⭐ References

caca_file_close(), caca_file_eof(), caca_file_open(), caca_file_read(), and caca_import_canvas_from_memory().

👀 Referenced by

caca_import_area_from_file().

🌸 __extern ssize_t caca_import_area_from_memory (caca_canvas_t * cv, int x, int y, void const * data, size_t len, char const * format)

Imports a memory buffer into the given libcaca canvas's current frame, at the specified position. It's the canvas version of ✨dropping a sticker exactly where you want it✨. For more info, see caca_import_canvas_from_memory().

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

  • EINVAL — unsupported format requested or invalid coordinates.
  • ENOMEM — not enough memory to allocate canvas.

🍓 Parameters

  • cv — a libcaca canvas in which to import the file.
  • x — the leftmost coordinate of the area to import to.
  • y — the topmost coordinate of the area to import to.
  • data — a memory area containing the data to be loaded into the canvas.
  • len — the size in bytes of the memory area.
  • format — a string describing the input format.

💜 Returns

The number of bytes read, or 0 if there was not enough data, or -1 if an error occurred.

⭐ References

caca_blit(), caca_create_canvas(), caca_free_canvas(), and caca_import_canvas_from_memory().

🦋 __extern ssize_t caca_import_area_from_file (caca_canvas_t * cv, int x, int y, char const * filename, char const * format)

Imports a file into the given libcaca canvas's current frame, at the specified position. For more information, see caca_import_canvas_from_file().

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

  • ENOSYS — file access is not implemented on this system.
  • ENOMEM — not enough memory to allocate canvas.
  • EINVAL — unsupported format requested or invalid coordinates. caca_import_file() may also fail and set errno for any of the errors specified for the routine fopen().

🍓 Parameters

  • cv — a libcaca canvas in which to import the file.
  • x — the leftmost coordinate of the area to import to.
  • y — the topmost coordinate of the area to import to.
  • filename — the name of the file to load.
  • format — a string describing the input format.

💜 Returns

The number of bytes read, or 0 if there was not enough data, or -1 if an error occurred.

⭐ References

caca_blit(), caca_create_canvas(), caca_free_canvas(), and caca_import_canvas_from_file().

🎀 __extern char const *const * caca_get_import_list (void )

Returns a list of available import formats. The list is a NULL-terminated array of strings, interleaving a string containing the internal value for the import format (to be used with caca_import_canvas()) and a string containing the natural language description for that import format. So it's like: value, pretty name, value, pretty name, …, NULL. Two at a time, always paired. iykyk. 💫

This function never fails. Iconic behaviour honestly. 👑

💜 Returns

An array of strings.

🔥 __extern void * caca_export_canvas_to_memory (caca_canvas_t const * cv, char const * format, size_t * bytes)

This function exports a libcaca canvas into various foreign formats such as ANSI art, HTML, IRC colours, etc. The returned pointer should be passed to free() to release the allocated storage when it is no longer needed. Do not forget the free(), bestie, that's a memory leak and we don't do those. 😭

Valid values for format are:

  • "caca" — export native libcaca files.
  • "ansi" — export ANSI art (CP437 charset with ANSI colour codes).
  • "html" — export an HTML page with CSS information.
  • "html3" — export an HTML table that should be compatible with most navigators, including textmode ones.
  • "irc" — export UTF-8 text with mIRC colour codes.
  • "ps" — export a PostScript document.
  • "svg" — export an SVG vector image.
  • "tga" — export a TGA image.
  • "troff" — export a troff source.

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

  • EINVAL — unsupported format requested.
  • ENOMEM — not enough memory to allocate output buffer.

🍓 Parameters

  • cv — a libcaca canvas.
  • format — a string describing the requested output format.
  • bytes — a pointer to a size_t where the number of allocated bytes will be written.

💜 Returns

A pointer to the exported memory area, or NULL in case of error.

⭐ Referenced by

caca_export_area_to_memory().

🌟 __extern void * caca_export_area_to_memory (caca_canvas_t const * cv, int x, int y, int w, int h, char const * format, size_t * bytes)

This function exports a portion of a libcaca canvas into various formats — like cropping your pic before you post it. 💅 For more information, see caca_export_canvas_to_memory().

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

  • EINVAL — unsupported format requested or invalid coordinates.
  • ENOMEM — not enough memory to allocate output buffer.

🍓 Parameters

  • cv — a libcaca canvas.
  • x — the leftmost coordinate of the area to export.
  • y — the topmost coordinate of the area to export.
  • w — the width of the area to export.
  • h — the height of the area to export.
  • format — a string describing the requested output format.
  • bytes — a pointer to a size_t where the number of allocated bytes will be written.

💜 Returns

A pointer to the exported memory area, or NULL in case of error.

⭐ References

caca_blit(), caca_create_canvas(), caca_export_canvas_to_memory(), and caca_free_canvas().

🌈 __extern char const *const * caca_get_export_list (void )

Returns a list of available export formats. The list is a NULL-terminated array of strings, interleaving a string containing the internal value for the export format (to be used with caca_export_memory()) and a string containing the natural language description for that export format. Same pairing situation as the import list, just the outgoing direction. 🎁

This function never fails either. Flawless. 💯

💜 Returns

An array of strings.

🫶 AUTHOR 🫶

Generated automatically by Doxygen for libcaca from the source code. Not a human, just a very diligent robot doing its little doc thing. 🤖✨

Okay and that's the whole page, bestie — every flag, every errno, every reference, all of it. Now go import something cute and export it somewhere cuter. 🎀💖

Version 0.99.beta20 · Wed May 13 2026 09:45:08 · page caca_importexport(3caca) — mwah, that's a wrap, periodt. 💅🦋

📦 where this page comes from