GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
MCHARS_ALLOC(3) FreeBSD Library Functions Manual MCHARS_ALLOC(3)

mchars_alloc, mchars_free, mchars_num2char, mchars_num2uc, mchars_spec2cp, mchars_spec2str, mchars_uc2str
character table for mandoc

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

These functions translate Unicode character numbers and roff(7) character names into glyphs. See mandoc_char(7) for a list of roff(7) special characters. These functions are intended for external use by programs formatting mdoc(7) and man(7) pages for output, for example the mandoc(1) output formatter modules and makewhatis(8). The decimal, hexadecimal, name, and size input arguments are usually obtained from the mandoc_escape(3) 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) -Tascii, -Tutf8, and -Thtml output modules use this function to render roff(7) \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) -Tutf8 and -Thtml output modules use this function to render roff(7) \[uXXXX] and \C'uXXXX' 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) 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) -Tutf8 and -Thtml output modules use this function to render roff(7) \[name] and \C'name' escape sequences.

The function mchars_spec2str() looks up a roff(7) 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) 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) and the mandoc(1) -Tascii output module use this function to render roff(7) \[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.

These funtions are implemented in the file chars.c.

mandoc(1), mandoc_escape(3), ohash_init(3), mandoc_char(7), roff(7)

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

Kristaps Dzonsons <kristaps@bsd.lv>
Ingo Schwarze <schwarze@openbsd.org>
July 7, 2016 FreeBSD 13.1-RELEASE

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.