4.4BSD/usr/share/man/cat3/vis.0

VIS(3)                      BSD Programmer's Manual                     VIS(3)

NNAAMMEE
     vviiss - visually encode characters

SSYYNNOOPPSSIISS
     ##iinncclluuddee <<vviiss..hh>>

     _c_h_a_r _*
     vviiss(_c_h_a_r _*_d_s_t, _c_h_a_r _c, _i_n_t _f_l_a_g, _c_h_a_r _n_e_x_t_c);

     _i_n_t
     ssttrrvviiss(_c_h_a_r _*_d_s_t, _c_h_a_r _*_s_r_c, _i_n_t _f_l_a_g);

     _i_n_t
     ssttrrvviissxx(_c_h_a_r _*_d_s_t, _c_h_a_r _*_s_r_c, _i_n_t _l_e_n, _i_n_t _f_l_a_g);

DDEESSCCRRIIPPTTIIOONN
     The vviiss() function copies into _d_s_t a string which represents the charac-
     ter _c. If _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 NULL); thus, when encoding a set of characters into a buffer,
     the size of the buffer should be four times the number of characters en-
     coded, plus one for the trailing NULL. The flag parameter is used for al-
     tering the default range of characters considered for encoding and for
     altering the visual representation.  The additional character, _n_e_x_t_c, is
     only used when selecting the VIS_CSTYLE encoding format (explained be-
     low).

     The ssttrrvviiss() and ssttrrvviissxx() functions copy into _d_s_t a visual representa-
     tion of the string _s_r_c. The ssttrrvviiss() function encodes characters from _s_r_c
     up to the first NULL. The ssttrrvviissxx() function encodes exactly _l_e_n charac-
     ters from _s_r_c (this is useful for encoding a block of data that may con-
     tain NULL's). Both forms NULL terminate _d_s_t. The size of _d_s_t must be four
     times the number of characters encoded from _s_r_c (plus one for the NULL).
     Both forms return the number of characters in dst (not including the
     trailing NULL).

     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 char-
                 acters 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 repre-

     sent a real backslash.  These are the visual formats:

     (default)   Use an `M' to represent meta characters (characters with the
                 8th bit set), and use carat `^' to represent control charac-
                 ters 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 NULL character can be encoded as `\0' instead
                 of `\000'. If _n_e_x_t_c is an octal digit, the latter representa-
                 tion 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.

SSEEEE AALLSSOO
     unvis(1),  unvis(3) strunvis(3)

HHIISSTTOORRYY
     These functions first appeared in 4.4BSD.


4.4BSD                           June 9, 1993                                2