April 9, 2006 VIS 3

### NAME

vis, strvis, strvisx, svis, strsvis, strsvisx - visually encode characters

### LIBRARY

Standard C Library (libc, -lc)

### SYNOPSIS

```char``*` vis(```char *dst``, int c``, int flag``, int nextc`)
```int` strvis(```char *dst``, const char *src``, int flag`)
```int` strvisx(```char *dst``, const char *src``, size_t len``, int flag`)
```char``*` svis(```char *dst``, int c``, int flag``, int nextc``, const char *extra`)
```int` strsvis(```char *dst``, const char *src``, int flag``, const char *extra`)
```int` strsvisx(```char *dst``, const char *src``, size_t len``, int flag``, const char *extra`)

### 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 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(``) 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 strvisx(``) function encodes exactly ```len` characters from ```src` (this is useful for encoding a block of data that may contain ```NUL`'s). Both forms ```NUL` terminate ```dst`. The size of ```dst` must be four times the number of characters encoded from ```src` (plus one for the ```NUL`). Both forms return the number of characters in dst (not including the trailing ```NUL`).

The functions svis(``), strsvis(``), and strsvisx(``) correspond to vis(``), strvis(``), and strvisx(``) but have an additional argument ```extra`, pointing to a ```NUL` terminated list of characters. These characters will be copied encoded or backslash-escaped into ```dst`. These functions are useful e.g. to remove the special meaning of certain characters to shells.

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 (applies only to vis(``), strvis(``), and strvisx(``)), 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.

(The above flags have no effect for svis(``), strsvis(``), and strsvisx(``). When using these functions, place all graphic characters to be encoded in an array pointed to by ```extra`. In general, the backslash character should be included in this array, see the warning on the use of the ```VIS_NOSLASH` flag below).

There are four forms of encoding. All forms use the backslash character `\' to introduce a special sequence; two backslashes are used to represent a real backslash, except ```VIS_HTTPSTYLE` that uses `%'. 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)
        \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.

```VIS_HTTPSTYLE`
  Use URI encoding as described in RFC 1738. The form is `%xx' where x represents a hexadecimal 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), unvis(3)

### HISTORY

The ```vis`, ```strvis`, and ```strvisx` functions first appeared in 4.4BSD. The ```svis`, ```strsvis`, and ```strsvisx` functions appeared in NetBSD1.5.