Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MCHARS_ALLOC(3)		 BSD Library Functions Manual	       MCHARS_ALLOC(3)

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) 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 ex-
     ample, 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 represen-
     tation.  If the input string is non-numeric or represents an ASCII	char-
     acter, 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 code-
     point.  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.

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

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

HISTORY
     These functions and their predecessors have been available	since the fol-
     lowing 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>

BSD				 July 7, 2016				   BSD

NAME | SYNOPSIS | DESCRIPTION | FILES | SEE ALSO | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=mchars_alloc&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help