NAME
vis
, strvis
,
strnvis
, strvisx
,
stravis
—
visually encode characters
SYNOPSIS
#include
<stdlib.h>
#include <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
dstsize, int
flag);
int
strvisx
(char
*dst, const char
*src, size_t
srclen, int
flag);
int
stravis
(char
**outp, const char
*src, 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. dst will be
NUL-terminated and must be at least 5 bytes long (maximum encoding requires
4 bytes plus the NUL). 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, into a buffer dst (which must be at least 4 *
strlen(src) + 1 long).
The
strnvis
()
function encodes characters from src up to the first
NUL or the end of the buffer dst, as indicated by
dstsize.
The
strvisx
()
function encodes exactly srclen characters from
src into a buffer dst (which
must be at least 4 * srclen + 1 long). This is useful for encoding a block
of data that may contain NULs.
The
stravis
()
function writes a visual representation of the string
src into a newly allocated string
outp; it does not attempt to
realloc(3) outp. outp
should be passed to free(3) to release the allocated storage when it is no longer needed.
stravis
() checks for integer overflow when
allocating memory.
All forms NUL-terminate dst,
except for
strnvis
()
when dstsize is zero, in which case
dst is not touched.
The flag parameter is used for altering the default range of characters considered for encoding and for altering the visual representation.
Encodings
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_ALL
- Encode all characters, whether visible or not.
VIS_DQ
- Also encode double quote characters
(‘
"
’). 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.
\-C
- Represents character ‘
C
’. Only used withVIS_ALL
.
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.
RETURN VALUES
vis
() returns a pointer to the terminating
NUL character of the string dst.
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 dstsize.
Upon successful completion, stravis
()
returns the number of characters in *outp (not
including the trailing NUL). Otherwise, stravis
()
returns -1 and sets errno to
ENOMEM
.
EXAMPLES
strvis
() has unusual storage requirements
that can lead to stack or heap corruption if the destination is not
carefully constructed. A common mistake is to use the same size for the
source and destination when the destination actually needs up to 4 *
strlen(source) + 1 bytes.
If the length of a string to be encoded is not known at compile
time, use stravis
():
char *src, *dst; ... if (stravis(&dst, src, VIS_OCTAL) == -1) err(1, "stravis"); ... free(dst);
To encode a fixed size buffer, strnvis
()
can be used with a fixed size target buffer:
char src[MAXPATHLEN]; char dst[4 * MAXPATHLEN + 1]; ... if (strnvis(dst, src, sizeof(dst), VIS_OCTAL) >= sizeof(dst)) err(1, "strnvis");
SEE ALSO
unvis(1), vis(1), free(3), snprintf(3), strlcpy(3), unvis(3)
HISTORY
The vis
(),
strvis
() and strvisx
()
functions first appeared in 4.3BSD-Reno,
strnvis
() in OpenBSD 2.9 and
stravis
() in OpenBSD
5.7.
The VIS_ALL
flag first appeared in
OpenBSD 4.9.