NAME

       vis, strvis, strnvis, strvisx — visually encode characters

LIBRARY

       library “libbsd”

SYNOPSIS

       #include <stdlib.h>
       #include <vis.h>
       (See libbsd(7) for include usage.)

       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(3bsd)).  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(3bsd) or strunvis(3bsd) 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(3bsd), unvis(3bsd)

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(3bsd)