---
name: "char"
section: "3caca"
platform: "linux"
package: "libcaca-dev"
version: "0.9-4"
release: "Debian 3.1 (Sarge)"
platforms: ["linux"]
url: "https://new.carta.tech/char"
---

# char(3caca)

## NAME

Character printing -

### Functions

void **caca\_set\_color** (enum **caca\_color**, enum **caca\_color**)\
 *Set the default colour pair.*  enum **caca\_color** **caca\_get\_fg\_color** (void)\
 *Get the current foreground colour.*  enum **caca\_color** **caca\_get\_bg\_color** (void)\
 *Get the current background colour.*  char const \* **caca\_get\_color\_name** (enum **caca\_color**)\
 *Translate a colour index into the colour's name.*  void **caca\_putchar** (int, int, char)\
 *Print a character.*  void **caca\_putstr** (int, int, char const \*)\
 *Print a string.*  void **caca\_printf** (int, int, char const \*,...)\
 *Format a string.*  void **caca\_clear** (void)\
 *Clear the screen.*

## Detailed Description

These functions provide low-level character printing routines.

## Function Documentation

### void caca\_clear (void)

This function clears the screen using a black background.

### enum caca\_color caca\_get\_bg\_color (void)

This function returns the current background colour that was set with **caca\_set\_color()**.

**Returns:**

The current background colour.

### char const\* caca\_get\_color\_name (enum caca\_color color)

This function translates a caca\_color enum into a human-readable description string of the associated colour.

**Parameters:**

*color* The colour value.

**Returns:**

A static string containing the colour's name.

### enum caca\_color caca\_get\_fg\_color (void)

This function returns the current foreground colour that was set with **caca\_set\_color()**.

**Returns:**

The current foreground colour.

### void caca\_printf (int x, int y, char const \* format, ...)

This function formats a string at the given coordinates, using the default foreground and background values. The coordinates may be outside the screen boundaries (eg. a negative Y coordinate) and the string will be cropped accordingly if it is too long. The syntax of the format string is the same as for the C printf() function.

**Parameters:**

*x* X coordinate. \
 *y* Y coordinate. \
 *format* The format string to print. \
 *...* Arguments to the format string.

### void caca\_putchar (int x, int y, char c)

This function prints a character at the given coordinates, using the default foreground and background values. If the coordinates are outside the screen boundaries, nothing is printed.

**Parameters:**

*x* X coordinate. \
 *y* Y coordinate. \
 *c* The character to print.

### void caca\_putstr (int x, int y, char const \* s)

This function prints a string at the given coordinates, using the default foreground and background values. The coordinates may be outside the screen boundaries (eg. a negative Y coordinate) and the string will be cropped accordingly if it is too long.

**Parameters:**

*x* X coordinate. \
 *y* Y coordinate. \
 *s* The string to print.

### void caca\_set\_color (enum caca\_color fgcolor, enum caca\_color bgcolor)

This function sets the default colour pair. String functions such as **caca\_printf()** and graphical primitive functions such as **caca\_draw\_line()** will use these colour pairs.

**Parameters:**

*fgcolor* The requested foreground colour. \
 *bgcolor* The requested background colour.