---
name: "mchars_alloc"
section: "3"
platform: "linux"
package: "libmandoc-dev"
version: "1.14.6-4"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/mchars_alloc"
---

# mchars\_alloc(3)

character table for mandoc

## NAME

**mchars\_alloc**, **mchars\_free**, **mchars\_num2char**, **mchars\_num2uc**, **mchars\_spec2cp**, **mchars\_spec2str**, **mchars\_uc2str** – character table for mandoc

## SYNOPSIS

**#include \<sys/types.h\>**

**#include \<mandoc.h\>**

*void*\

**mchars\_alloc**(*void*);

*void*\

**mchars\_free**(*void*);

*char*\

**mchars\_num2char**(*const char \*decimal*, *size\_t sz*);

*int*\

**mchars\_num2uc**(*const char \*hexadecimal*, *size\_t sz*);

*int*\

**mchars\_spec2cp**(*const char \*name*, *size\_t sz*);

*const char \**\

**mchars\_spec2str**(*const char \*name*, *size\_t sz*, *size\_t \*rsz*);

*const char \**\

**mchars\_uc2str**(*int codepoint*);

## DESCRIPTION

These functions translate Unicode character numbers and [roff(7)](/roff/7.md) character names into glyphs. See [mandoc\_char(7)](/mandoc_char/7.md) for a list of [roff(7)](/roff/7.md) special characters. These functions are intended for external use by programs formatting [mdoc(7)](/mdoc/7.md) and [man(7)](/man/7.md) pages for output, for example the [mandoc(1)](/mandoc/1.md) output formatter modules and [makewhatis(8)](/makewhatis/8.md). The *decimal*, *hexadecimal*, *name*, and *size* input arguments are usually obtained from the [mandoc\_escape(3)](/mandoc_escape/3.md) parser function.

The function **mchars\_num2char**() converts a *decimal* string representation of a character number consisting of *sz* digits into a printable ASCII character. If the input string is non-numeric or does not represent a printable ASCII character, the NUL character (‘\\0’) is returned. For example, the [mandoc(1)](/mandoc/1.md) **-Tascii**, **-Tutf8**, and **-Thtml** output modules use this function to render [roff(7)](/roff/7.md) **\\N** escape sequences.

The function **mchars\_num2uc**() converts a *hexadecimal* string representation of a Unicode codepoint consisting of *sz* digits into an integer representation. If the input string is non-numeric or represents an ASCII character, the NUL character (‘\\0’) is returned. For example, the [mandoc(1)](/mandoc/1.md) **-Tutf8** and **-Thtml** output modules use this function to render [roff(7)](/roff/7.md) **\\\[u***XXXX***\]** and **\\C'u***XXXX***'** escape sequences.

The function **mchars\_alloc**() initializes a static *struct ohash* object for subsequent use by the following two lookup functions. When no longer needed, this object can be destroyed with **mchars\_free**().

The function **mchars\_spec2cp**() looks up a [roff(7)](/roff/7.md) special character *name* consisting of *sz* characters and returns the corresponding Unicode codepoint. If the *name* is not recognized, -1 is returned. For example, the [mandoc(1)](/mandoc/1.md) **-Tutf8** and **-Thtml** output modules use this function to render [roff(7)](/roff/7.md) **\\\[***name***\]** and **\\C'***name***'** escape sequences.

The function **mchars\_spec2str**() looks up a [roff(7)](/roff/7.md) special character *name* consisting of *sz* characters and returns an ASCII string representation. The length of the representation is returned in *rsz*. In many cases, the meaning of such ASCII representations is not quite obvious, so using [roff(7)](/roff/7.md) special characters in documents intended for ASCII rendering is usually a bad idea. If the *name* is not recognized, NULL is returned. For example, [makewhatis(8)](/makewhatis/8.md) and the [mandoc(1)](/mandoc/1.md) **-Tascii** output module use this function to render [roff(7)](/roff/7.md) **\\\[***name***\]** and **\\C'***name***'** escape sequences.

The function **mchars\_uc2str**() performs a reverse lookup of the Unicode *codepoint* and returns an ASCII string representation, or the string "\<?\>" if none is available.

## FILES

These funtions are implemented in the file *chars.c*.

## SEE ALSO

[mandoc(1)](/mandoc/1.md), [mandoc\_escape(3)](/mandoc_escape/3.md), ohash\_init(3), [mandoc\_char(7)](/mandoc_char/7.md), [roff(7)](/roff/7.md)

## HISTORY

These functions and their predecessors have been available since the following mandoc versions:

| | | | |
| --- | --- | --- | --- |
| **function** | since | **predecessor** | since |
| **mchars\_alloc**() | 1.11.3 | **ascii2htab**() | 1.5.3 |
| **mchars\_free**() | 1.11.2 | **asciifree**() | 1.6.0 |
| **mchars\_num2char**() | 1.11.2 | **chars\_num2char**() | 1.10.10 |
| **mchars\_num2uc**() | 1.11.3 | — | — |
| **mchars\_spec2cp**() | 1.11.2 | **chars\_spec2cp**() | 1.10.5 |
| **mchars\_spec2str**() | 1.11.2 | **a2ascii**() | 1.5.3 |
| **mchars\_uc2str**() | 1.13.2 | — | — |

## AUTHORS

Kristaps Dzonsons ⟨*kristaps@bsd.lv*⟩ Ingo Schwarze ⟨*schwarze@openbsd.org*⟩