VIS

Section: C Library Functions (3)
Index Return to Main Contents

BSD mandoc

NAME

vis - visually encode characters

SYNOPSIS

Fd #include <vis.h> Ft char * Fn vis char *dst char c int flag char nextc Ft int Fn strvis char *dst char *src int flag Ft int Fn strvisx char *dst char *src int len int flag

DESCRIPTION

The Fn vis function copies into Fa dst a string which represents the character Fa c . If Fa c needs no encoding, it is copied in unaltered. The string is null terminated, and a pointer to the end of the string is returned. The maximum length of any encoding is four characters (not including the trailing NUL ) ; thus, when encoding a set of characters into a buffer, the size of the buffer should be four times the number of characters encoded, plus one for the trailing NUL . The flag parameter is used for altering the default range of characters considered for encoding and for altering the visual representation. The additional character, Fa nextc , is only used when selecting the VIS_CSTYLE encoding format (explained below).

The Fn strvis and Fn strvisx functions copy into Fa dst a visual representation of the string Fa src . The Fn strvis function encodes characters from Fa src up to the first NUL . The Fn strvisx function encodes exactly Fa len characters from Fa src (this is useful for encoding a block of data that may contain NUL 's). Both forms NUL terminate Fa dst . The size of Fa dst must be four times the number of characters encoded from Fa src (plus one for the NUL ) . Both forms return the number of characters in dst (not including the trailing NUL ) .

The encoding is a unique, invertible representation comprised entirely of graphic characters; it can be decoded back into the original form using the unvis(3) or strunvis(3) functions.

There are two parameters that can be controlled: the range of characters that are encoded, and the type of representation used. By default, all non-graphic characters. except space, tab, and newline are encoded. (See isgraph(3).) The following flags alter this:

VIS_SP: Also encode space.
VIS_TAB: Also encode tab.
VIS_NL: Also encode newline.
VIS_WHITE: Synonym for
VIS_SP | VIS_TAB | VIS_NL
VIS_SAFE: Only encode "unsafe" characters. Unsafe means control
characters which may cause common terminals to perform unexpected functions. Currently this form allows space, tab, newline, backspace, bell, and return - in addition to all graphic characters - unencoded.

There are three forms of encoding. All forms use the backslash character `\' to introduce a special sequence; two backslashes are used to represent a real backslash. These are the visual formats:

(default)

Use an `M' to represent meta characters (characters with the 8th bit set), and use caret `^' to represent control characters see ( iscntrl(3)) The following formats are used:

\^C: Represents the control character `C' Spans characters `\000' through `\037' , and `\177' (as `\^?' ) .
\M-C: Represents character `C' with the 8th bit set. Spans characters `\241' through `\376'
\M^C: Represents control character `C' with the 8th bit set. Spans characters `\200' through `\237' , and `\377' (as `\M^?' ) .
\040: Represents ASCII space.
\240: Represents Meta-space.

VIS_CSTYLE

Use C-style backslash sequences to represent standard non-printable characters. The following sequences are used to represent the indicated characters:

\a - BEL (007)


\b - BS (010)


\f - NP (014)


\n - NL (012)


\r - CR (015)


\t - HT (011)


\v - VT (013)


\0 - NUL (000)

When using this format, the nextc parameter is looked at to determine if a NUL character can be encoded as `\0' instead of `\000' If Fa nextc is an octal digit, the latter representation is used to avoid ambiguity.

VIS_OCTAL

Use a three digit octal sequence. The form is `\ddd' where d represents an octal digit.

There is one additional flag, VIS_NOSLASH which inhibits the doubling of backslashes and the backslash before the default format (that is, control characters are represented by `^C' and meta characters as `M-C' ) . With this flag set, the encoding is ambiguous and non-invertible.

HISTORY

These functions first appeared in 4.4BSD.

This document was created by man2html, using the manual pages.
Time: 15:52:51 GMT, January 15, 2023

VIS

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO

HISTORY

Index