1MCHARS_ALLOC(3) BSD Library Functions Manual MCHARS_ALLOC(3)
2
4 mchars_alloc, mchars_free, mchars_num2char, mchars_num2uc,
5 mchars_spec2cp, mchars_spec2str, mchars_uc2str — character table for man‐
6 doc
7
9 #include <sys/types.h>
10 #include <mandoc.h>
11 void
13 mchars_alloc(void);
14 void
16 mchars_free(void);
17 char
19 mchars_num2char(const char *decimal, size_t sz);
20 int
22 mchars_num2uc(const char *hexadecimal, size_t sz);
23 int
25 mchars_spec2cp(const char *name, size_t sz);
26 const char *
28 mchars_spec2str(const char *name, size_t sz, size_t *rsz);
29 const char *
31 mchars_uc2str(int codepoint);
32
34 These functions translate Unicode character numbers and roff(7) character
35 names into glyphs. See mandoc_char(7) for a list of roff(7) special
36 characters. These functions are intended for external use by programs
37 formatting mdoc(7) and man(7) pages for output, for example the mandoc(1)
38 output formatter modules and makewhatis(8). The decimal, hexadecimal,
39 name, and size input arguments are usually obtained from the
40 mandoc_escape(3) parser function.
41 The function mchars_num2char() converts a decimal string representation
43 of a character number consisting of sz digits into a printable ASCII
44 character. If the input string is non-numeric or does not represent a
45 printable ASCII character, the NUL character (‘\0’) is returned. For
46 example, the mandoc(1) -Tascii, -Tutf8, and -Thtml output modules use
47 this function to render roff(7) \N escape sequences.
48 The function mchars_num2uc() converts a hexadecimal string representation
50 of a Unicode codepoint consisting of sz digits into an integer represen‐
51 tation. If the input string is non-numeric or represents an ASCII char‐
52 acter, the NUL character (‘\0’) is returned. For example, the mandoc(1)
53 -Tutf8 and -Thtml output modules use this function to render roff(7)
54 \[uXXXX] and \C'uXXXX' escape sequences.
55 The function mchars_alloc() initializes a static struct ohash object for
57 subsequent use by the following two lookup functions. When no longer
58 needed, this object can be destroyed with mchars_free().
59 The function mchars_spec2cp() looks up a roff(7) special character name
61 consisting of sz characters and returns the corresponding Unicode code‐
62 point. If the name is not recognized, -1 is returned. For example, the
63 mandoc(1) -Tutf8 and -Thtml output modules use this function to render
64 roff(7) \[name] and \C'name' escape sequences.
65 The function mchars_spec2str() looks up a roff(7) special character name
67 consisting of sz characters and returns an ASCII string representation.
68 The length of the representation is returned in rsz. In many cases, the
69 meaning of such ASCII representations is not quite obvious, so using
70 roff(7) special characters in documents intended for ASCII rendering is
71 usually a bad idea. If the name is not recognized, NULL is returned.
72 For example, makewhatis(8) and the mandoc(1) -Tascii output module use
73 this function to render roff(7) \[name] and \C'name' escape sequences.
74 The function mchars_uc2str() performs a reverse lookup of the Unicode
76 codepoint and returns an ASCII string representation, or the string "<?>"
77 if none is available.
78
80 These funtions are implemented in the file chars.c.
81
83 mandoc(1), mandoc_escape(3), ohash_init(3), mandoc_char(7), roff(7)
84
86 These functions and their predecessors have been available since the fol‐
87 lowing mandoc versions:
88 function since predecessor since
90 mchars_alloc() 1.11.3 ascii2htab() 1.5.3
91 mchars_free() 1.11.2 asciifree() 1.6.0
92 mchars_num2char() 1.11.2 chars_num2char() 1.10.10
93 mchars_num2uc() 1.11.3 — —
94 mchars_spec2cp() 1.11.2 chars_spec2cp() 1.10.5
95 mchars_spec2str() 1.11.2 a2ascii() 1.5.3
96 mchars_uc2str() 1.13.2 — —
97
99 Kristaps Dzonsons <kristaps@bsd.lv>
100 Ingo Schwarze <schwarze@openbsd.org>
101BSD June 20, 2019 BSD