1VIS(3bsd) LOCAL VIS(3bsd)
2
4 vis, nvis, strvis, stravis, strnvis, strvisx, strnvisx, strenvisx, svis,
5 snvis, strsvis, strsnvis, strsvisx, strsnvisx, strsenvisx — visually
6 encode characters
7
9 Utility functions from BSD systems (libbsd, -lbsd)
10
12 #include <vis.h>
13 (See libbsd(7) for include usage.)
14 char *
16 vis(char *dst, int c, int flag, int nextc);
17 char *
19 nvis(char *dst, size_t dlen, int c, int flag, int nextc);
20 int
22 strvis(char *dst, const char *src, int flag);
23 int
25 stravis(char **dst, const char *src, int flag);
26 int
28 strnvis(char *dst, size_t dlen, const char *src, int flag);
29 int
31 strvisx(char *dst, const char *src, size_t len, int flag);
32 int
34 strnvisx(char *dst, size_t dlen, const char *src, size_t len, int flag);
35 int
37 strenvisx(char *dst, size_t dlen, const char *src, size_t len, int flag,
38 int *cerr_ptr);
39 char *
41 svis(char *dst, int c, int flag, int nextc, const char *extra);
42 char *
44 snvis(char *dst, size_t dlen, int c, int flag, int nextc,
45 const char *extra);
46 int
48 strsvis(char *dst, const char *src, int flag, const char *extra);
49 int
51 strsnvis(char *dst, size_t dlen, const char *src, int flag,
52 const char *extra);
53 int
55 strsvisx(char *dst, const char *src, size_t len, int flag,
56 const char *extra);
57 int
59 strsnvisx(char *dst, size_t dlen, const char *src, size_t len, int flag,
60 const char *extra);
61 int
63 strsenvisx(char *dst, size_t dlen, const char *src, size_t len, int flag,
64 const char *extra, int *cerr_ptr);
65
67 The vis() function copies into dst a string which represents the charac‐
68 ter c. If c needs no encoding, it is copied in unaltered. The string is
69 null terminated, and a pointer to the end of the string is returned. The
70 maximum length of any encoding is four bytes (not including the trailing
71 NUL); thus, when encoding a set of characters into a buffer, the size of
72 the buffer should be four times the number of bytes encoded, plus one for
73 the trailing NUL. The flag parameter is used for altering the default
74 range of characters considered for encoding and for altering the visual
75 representation. The additional character, nextc, is only used when
76 selecting the VIS_CSTYLE encoding format (explained below).
77 The strvis(), stravis(), strnvis(), strvisx(), and strnvisx() functions
79 copy into dst a visual representation of the string src. The strvis()
80 and strnvis() functions encode characters from src up to the first NUL.
81 The strvisx() and strnvisx() functions encode exactly len characters from
82 src (this is useful for encoding a block of data that may contain NUL's).
83 Both forms NUL terminate dst. The size of dst must be four times the
84 number of bytes encoded from src (plus one for the NUL). Both forms
85 return the number of characters in dst (not including the trailing NUL).
86 The stravis() function allocates space dynamically to hold the string.
87 The “n” versions of the functions also take an additional argument dlen
88 that indicates the length of the dst buffer. If dlen is not large enough
89 to fit the converted string then the strnvis() and strnvisx() functions
90 return -1 and set errno to ENOSPC. The strenvisx() function takes an
91 additional argument, cerr_ptr, that is used to pass in and out a multi‐
92 byte conversion error flag. This is useful when processing single char‐
93 acters at a time when it is possible that the locale may be set to some‐
94 thing other than the locale of the characters in the input data.
95 The functions svis(), snvis(), strsvis(), strsnvis(), strsvisx(),
97 strsnvisx(), and strsenvisx() correspond to vis(), nvis(), strvis(),
98 strnvis(), strvisx(), strnvisx(), and strenvisx() but have an additional
99 argument extra, pointing to a NUL terminated list of characters. These
100 characters will be copied encoded or backslash-escaped into dst. These
101 functions are useful e.g. to remove the special meaning of certain char‐
102 acters to shells.
103 The encoding is a unique, invertible representation composed entirely of
105 graphic characters; it can be decoded back into the original form using
106 the unvis(3bsd), strunvis(3bsd) or strnunvis(3bsd) functions.
107 There are two parameters that can be controlled: the range of characters
109 that are encoded (applies only to vis(), nvis(), strvis(), strnvis(),
110 strvisx(), and strnvisx()), and the type of representation used. By
111 default, all non-graphic characters, except space, tab, and newline are
112 encoded (see isgraph(3)). The following flags alter this:
113 VIS_DQ Also encode double quotes
115 VIS_GLOB Also encode the magic characters (‘*’, ‘?’, ‘[’, and ‘#’)
117 recognized by glob(3).
118 VIS_SHELL Also encode the meta characters used by shells (in addition
120 to the glob characters): (‘'’, ‘`’, ‘"’, ‘;’, ‘&’, ‘<’, ‘>’,
121 ‘(’, ‘)’, ‘|’, ‘]’, ‘\’, ‘$’, ‘!’, ‘^’, and ‘~’).
122 VIS_SP Also encode space.
124 VIS_TAB Also encode tab.
126 VIS_NL Also encode newline.
128 VIS_WHITE Synonym for VIS_SP | VIS_TAB | VIS_NL.
130 VIS_META Synonym for VIS_WHITE | VIS_GLOB | VIS_SHELL.
132 VIS_SAFE Only encode “unsafe” characters. Unsafe means control char‐
134 acters which may cause common terminals to perform unexpected
135 functions. Currently this form allows space, tab, newline,
136 backspace, bell, and return — in addition to all graphic
137 characters — unencoded.
138 (The above flags have no effect for svis(), snvis(), strsvis(),
140 strsnvis(), strsvisx(), and strsnvisx(). When using these functions,
141 place all graphic characters to be encoded in an array pointed to by
142 extra. In general, the backslash character should be included in this
143 array, see the warning on the use of the VIS_NOSLASH flag below).
144 There are six forms of encoding. All forms use the backslash character
146 ‘\’ to introduce a special sequence; two backslashes are used to repre‐
147 sent a real backslash, except VIS_HTTPSTYLE that uses ‘%’, or
148 VIS_MIMESTYLE that uses ‘=’. These are the visual formats:
149 (default) Use an ‘M’ to represent meta characters (characters with the
151 8th bit set), and use caret ‘^’ to represent control charac‐
152 ters (see iscntrl(3)). The following formats are used:
153 \^C Represents the control character ‘C’. Spans charac‐
155 ters ‘\000’ through ‘\037’, and ‘\177’ (as ‘\^?’).
156 \M-C Represents character ‘C’ with the 8th bit set. Spans
158 characters ‘\241’ through ‘\376’.
159 \M^C Represents control character ‘C’ with the 8th bit set.
161 Spans characters ‘\200’ through ‘\237’, and ‘\377’ (as
162 ‘\M^?’).
163 \040 Represents ASCII space.
165 \240 Represents Meta-space.
167 VIS_CSTYLE Use C-style backslash sequences to represent standard non-
169 printable characters. The following sequences are used to
170 represent the indicated characters:
171 \a — BEL (007)
173 \b — BS (010)
174 \f — NP (014)
175 \n — NL (012)
176 \r — CR (015)
177 \s — SP (040)
178 \t — HT (011)
179 \v — VT (013)
180 \0 — NUL (000)
181 When using this format, the nextc parameter is looked at to
183 determine if a NUL character can be encoded as ‘\0’ instead
184 of ‘\000’. If nextc is an octal digit, the latter represen‐
185 tation is used to avoid ambiguity.
186 Non-printable characters without C-style backslash sequences
188 use the default representation.
189 VIS_OCTAL Use a three digit octal sequence. The form is ‘\ddd’ where d
191 represents an octal digit.
192 VIS_CSTYLE | VIS_OCTAL
194 Same as VIS_CSTYLE except that non-printable characters with‐
195 out C-style backslash sequences use a three digit octal
196 sequence.
197 VIS_HTTPSTYLE
199 Use URI encoding as described in RFC 1738. The form is ‘%xx’
200 where x represents a lower case hexadecimal digit.
201 VIS_MIMESTYLE
203 Use MIME Quoted-Printable encoding as described in RFC 2045,
204 only don't break lines and don't handle CRLF. The form is
205 ‘=XX’ where X represents an upper case hexadecimal digit.
206 There is one additional flag, VIS_NOSLASH, which inhibits the doubling of
208 backslashes and the backslash before the default format (that is, control
209 characters are represented by ‘^C’ and meta characters as ‘M-C’). With
210 this flag set, the encoding is ambiguous and non-invertible.
211
213 These functions support multibyte character input. The encoding conver‐
214 sion is influenced by the setting of the LC_CTYPE environment variable
215 which defines the set of characters that can be copied without encoding.
216 If VIS_NOLOCALE is set, processing is done assuming the C locale and
218 overriding any other environment settings.
219 When 8-bit data is present in the input, LC_CTYPE must be set to the cor‐
221 rect locale or to the C locale. If the locales of the data and the con‐
222 version are mismatched, multibyte character recognition may fail and
223 encoding will be performed byte-by-byte instead.
224 As noted above, dst must be four times the number of bytes processed from
226 src. But note that each multibyte character can be up to MB_LEN_MAX
227 bytes so in terms of multibyte characters, dst must be four times
228 MB_LEN_MAX times the number of characters processed from src.
229
231 LC_CTYPE Specify the locale of the input data. Set to C if the input
232 data locale is unknown.
233
235 The functions nvis() and snvis() will return NULL and the functions
236 strnvis(), strnvisx(), strsnvis(), and strsnvisx(), will return -1 when
237 the dlen destination buffer size is not enough to perform the conversion
238 while setting errno to:
239 [ENOSPC] The destination buffer size is not large enough to perform the
241 conversion.
242
244 unvis(1), vis(1), glob(3), unvis(3bsd)
245 T. Berners-Lee, Uniform Resource Locators (URL), RFC 1738.
247 Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet
249 Message Bodies, RFC 2045.
250
252 The vis(), strvis(), and strvisx() functions first appeared in 4.4BSD.
253 The svis(), strsvis(), and strsvisx() functions appeared in NetBSD 1.5.
254 The buffer size limited versions of the functions (nvis(), strnvis(),
255 strnvisx(), snvis(), strsnvis(), and strsnvisx()) appeared in NetBSD 6.0
256 and FreeBSD 9.2. Multibyte character support was added in NetBSD 7.0 and
257 FreeBSD 9.2.
258BSD April 22, 2017 BSD