NAME

       vis, strvis, strnvis, strvisx — visually encode characters

LIBRARY

       library “libbsd”

SYNOPSIS

       #include <stdlib.h>
       #include <bsd/vis.h>

       char *
       vis(char *dst, int c, int flag, int nextc);

       int
       strvis(char *dst, const char *src, int flag);

       int
       strnvis(char *dst, const char *src, size_t size, int flag);

       int
       strvisx(char *dst, const char *src, size_t len, int flag);

DESCRIPTION

       The vis() function copies into dst a string which represents the character c.  If c needs no encoding, it
       is copied in unaltered.  The string is NUL 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, nextc, is only used when selecting the VIS_CSTYLE encoding format (explained below).

       The  strvis(), strnvis() and strvisx() functions copy into dst a visual representation of the string src.
       The strvis() function encodes characters from src up to the first NUL.  The  strnvis()  function  encodes
       characters  from src up to the first NUL or the end of dst, as indicated by size.  The strvisx() function
       encodes exactly len characters from src (this is useful for encoding a block of  data  that  may  contain
       NULs).   All  three forms NUL terminate dst, except for strnvis() when size is zero, in which case dst is
       not touched.  For strvis() and strvisx(), the size of dst must be four times  the  number  of  characters
       encoded  from  src (plus one for the NUL).  strvis() and strvisx() return the number of characters in dst
       (not including the trailing NUL).  strnvis() returns the length that dst  would  become  if  it  were  of
       unlimited size (similar to snprintf(3) or strlcpy(3)).  This can be used to detect truncation but it also
       means that the return value of strnvis() must not be used without checking it against size.

       The  encoding  is  a unique, invertible representation composed 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_GLOB    Also encode magic characters recognized by glob(3) (‘*’, ‘?’, ‘[’) and ‘#’.

       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.   These  are  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 a 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)
                         \s - SP (040)
                         \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 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.

SEE ALSO

       unvis(1), vis(1), snprintf(3), strlcpy(3), unvis(3)

HISTORY

       The vis(), strvis() and strvisx() functions first appeared  in  4.4BSD.   The  strnvis()  function  first
       appeared in OpenBSD 2.9.

Debian                                            May 31, 2007                                            VIS(3)