---
name: "caca_file"
section: "3caca"
platform: "linux"
package: "libcaca"
version: "0.99.beta20-7"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/caca_file"
---

# caca\_file(3caca)

libcaca file IO

## NAME

caca\_file - libcaca file IO

## 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

These functions allow to read and write files in a platform-independent way.

## Function Documentation

### \_\_extern caca\_file\_t \* caca\_file\_open (char const \* path, const char \* mode)

Create a caca file handle for a file. If the file is zipped, it is decompressed on the fly.

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)

Close and destroy the resources associated with a caca file handle.

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)

Return the file handle position, in bytes.

**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)

Read data from a file handle and copy them into the given buffer.

**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)

Write the contents of the given buffer to the file handle.

**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)

Read one line of data from a file handle, up to one less than the given number of bytes. A trailing zero is appended to the data.

**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)

Return the end-of-file status of the file handle.

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.