strvis(3)                                                     strvis(3)

  vis()

  NAME

    vis(), strvis(), strnvis(), strvisx() - visually encode characters

  SYNOPSIS

    #include 

    char * vis (char *dst, char c, int flag, char nextc)
    int strvis (char *dst, char *src, int flag)
    int strnvis (char *dst, char *src, size_t siz, int flag)
    int strvisx (char *dst, char *src, int len, int flag)

  DESCRIPTION

    The vis(3) function copies into dst a string which represents the
    character 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 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(3), strnvis(3), and strvisx(3) functions copy into dst a visual
    representation of the string src. The strvis(3) function encodes
    characters from src up to the first NUL. The strnvis(3) function encodes
    characters from src up to the first NUL or the end of dst, as indicated by
    siz. The strvisx(3) 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. For strvis(3) and strvisx(3), the size of dst
    must be four times the number of characters encoded from src (plus one for
    the NUL). Both strvis(3) and strvisx(3) return the number of characters in
    dst (not including the trailing NUL). The strnvis(3) function returns the
    length that dst would become if it were of unlimited size (similar to
    snprintf(3)). This can be used to detect truncation but it also means that
    the return value of strnvis(3) must not be used without checking it
    against siz.

    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_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:
        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 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(3)

    vis(1)

    unvis(1)

  USAGE NOTES

    All of these functions are thread safe.

    None of these functions are async-signal safe.