---
name: "vis"
section: "3"
platform: "linux"
package: "libbsd-dev"
version: "0.8.3-1"
release: "Debian 9 (Stretch)"
platforms: ["linux", "freebsd", "macos"]
url: "https://new.carta.tech/vis/3"
---

# vis(3)

visually encode characters

## 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)](/snprintf/3.md) or [strlcpy(3)](/strlcpy/3.md)). 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)](/unvis/3.md) or [strunvis(3)](/strunvis/3.md) 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)](/isgraph/3.md)). The following flags alter this:

- VIS\_GLOB

  Also encode magic characters recognized by [glob(3)](/glob/3.md) (‘\*’, ‘?’, ‘\[’) 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)](/iscntrl/3.md)). 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)](/unvis/1.md), [vis(1)](/vis/1.md), [snprintf(3)](/snprintf/3.md), [strlcpy(3)](/strlcpy/3.md), [unvis(3)](/unvis/3.md)

## HISTORY

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