| blob | 405c62d74dea4363d71634da7dfad7f4c26c11ed |
1 .\" $OpenBSD: vis.3,v 1.35 2015/07/20 01:52:28 millert Exp $
2 .\"
3 .\" Copyright (c) 1989, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .Dd $Mdocdate: February 3 2017 $
31 .Dt VIS 3
32 .Os
33 .Sh NAME
34 .Nm vis ,
35 .Nm strvis ,
36 .Nm strnvis ,
37 .Nm strvisx ,
38 .Nm stravis
39 .Nd visually encode characters
40 .Sh SYNOPSIS
41 .In stdlib.h
42 .In vis.h
43 .Ft char *
44 .Fn vis "char *dst" "int c" "int flag" "int nextc"
45 .Ft int
46 .Fn strvis "char *dst" "const char *src" "int flag"
47 .Ft int
48 .Fn strnvis "char *dst" "const char *src" "size_t dstsize" "int flag"
49 .Ft int
50 .Fn strvisx "char *dst" "const char *src" "size_t srclen" "int flag"
51 .Ft int
52 .Fn stravis "char **outp" "const char *src" "int flag"
53 .Sh DESCRIPTION
54 The
55 .Fn vis
56 function copies into
57 .Fa dst
58 a string which represents the character
59 .Fa c .
60 If
61 .Fa c
62 needs no encoding, it is copied in unaltered.
63 .Fa dst
64 will be NUL-terminated and must be at least 5 bytes long
65 (maximum encoding requires 4 bytes plus the NUL).
66 The additional character,
67 .Fa nextc ,
68 is only used when selecting the
69 .Dv VIS_CSTYLE
70 encoding format (explained below).
71 .Pp
72 The
73 .Fn strvis ,
74 .Fn strnvis
75 and
76 .Fn strvisx
77 functions copy into
78 .Fa dst
79 a visual representation of
80 the string
81 .Fa src .
82 .Pp
83 The
84 .Fn strvis
85 function encodes characters from
86 .Fa src
87 up to the first NUL, into a buffer
88 .Fa dst
89 (which must be at least 4 * strlen(src) + 1 long).
90 .Pp
91 The
92 .Fn strnvis
93 function encodes characters from
94 .Fa src
95 up to the first NUL or the end of the buffer
96 .Fa dst ,
97 as indicated by
98 .Fa dstsize .
99 .Pp
100 The
101 .Fn strvisx
102 function encodes exactly
103 .Fa srclen
104 characters from
105 .Fa src
106 into a buffer
107 .Fa dst
108 (which must be at least 4 * srclen + 1 long).
109 This
110 is useful for encoding a block of data that may contain NULs.
111 .Pp
112 The
113 .Fn stravis
114 function writes a visual representation of the string
115 .Fa src
116 into a newly allocated string
117 .Fa outp ;
118 it does not attempt to
119 .Xr realloc 3
120 .Fa outp .
121 .Fa outp
122 should be passed to
123 .Xr free 3
124 to release the allocated storage when it is no longer needed.
125 .Fn stravis
126 checks for integer overflow when allocating memory.
127 .Pp
128 All forms NUL-terminate
129 .Fa dst ,
130 except for
131 .Fn strnvis
132 when
133 .Fa dstsize
134 is zero, in which case
135 .Fa dst
136 is not touched.
137 .Pp
138 The
139 .Fa flag
140 parameter is used for altering the default range of
141 characters considered for encoding and for altering the visual
142 representation.
143 .Ss Encodings
144 The encoding is a unique, invertible representation composed entirely of
145 graphic characters; it can be decoded back into the original form using
146 the
147 .Xr unvis 3
148 or
149 .Xr strunvis 3
150 functions.
151 .Pp
152 There are two parameters that can be controlled: the range of
153 characters that are encoded, and the type
154 of representation used.
155 By default, all non-graphic characters
156 except space, tab, and newline are encoded
157 (see
158 .Xr isgraph 3 ) .
159 The following flags
160 alter this:
161 .Bl -tag -width VIS_WHITEX
162 .It Dv VIS_ALL
163 Encode all characters, whether visible or not.
164 .It Dv VIS_DQ
165 Also encode double quote characters
166 .Pf ( Ql \&" ) .
167 .It Dv VIS_GLOB
168 Also encode magic characters recognized by
169 .Xr glob 3
170 .Pf ( Ql * ,
171 .Ql \&? ,
172 .Ql \&[ )
173 and
174 .Ql # .
175 .It Dv VIS_SP
176 Also encode space.
177 .It Dv VIS_TAB
178 Also encode tab.
179 .It Dv VIS_NL
180 Also encode newline.
181 .It Dv VIS_WHITE
182 Synonym for
183 .Dv VIS_SP | VIS_TAB | VIS_NL .
184 .It Dv VIS_SAFE
185 Only encode
186 .Dq unsafe
187 characters.
188 These are control characters which may cause common terminals to perform
189 unexpected functions.
190 Currently this form allows space,
191 tab, newline, backspace, bell, and return -- in addition
192 to all graphic characters -- unencoded.
193 .El
194 .Pp
195 There are three forms of encoding.
196 All forms use the backslash
197 .Ql \e
198 character to introduce a special
199 sequence; two backslashes are used to represent a real backslash.
200 These are the visual formats:
201 .Bl -tag -width VIS_CSTYLE
202 .It (default)
203 Use an
204 .Ql M
205 to represent meta characters (characters with the 8th
206 bit set), and use a caret
207 .Ql ^
208 to represent control characters (see
209 .Xr iscntrl 3 ) .
210 The following formats are used:
211 .Bl -tag -width xxxxx
212 .It Dv \e^C
213 Represents the control character
214 .Ql C .
215 Spans characters
216 .Ql \e000
217 through
218 .Ql \e037 ,
219 and
220 .Ql \e177
221 (as
222 .Ql \e^? ) .
223 .It Dv \eM-C
224 Represents character
225 .Ql C
226 with the 8th bit set.
227 Spans characters
228 .Ql \e241
229 through
230 .Ql \e376 .
231 .It Dv \eM^C
232 Represents control character
233 .Ql C
234 with the 8th bit set.
235 Spans characters
236 .Ql \e200
237 through
238 .Ql \e237 ,
239 and
240 .Ql \e377
241 (as
242 .Ql \eM^? ) .
243 .It Dv \e040
244 Represents
245 .Tn ASCII
246 space.
247 .It Dv \e240
248 Represents Meta-space.
249 .It Dv \e-C
250 Represents character
251 .Ql C .
252 Only used with
253 .Dv VIS_ALL .
254 .El
255 .It Dv VIS_CSTYLE
256 Use C-style backslash sequences to represent standard non-printable
257 characters.
258 The following sequences are used to represent the indicated characters:
259 .Bd -unfilled -offset indent
260 .Li \ea Tn - BEL No (007)
261 .Li \eb Tn - BS No (010)
262 .Li \ef Tn - NP No (014)
263 .Li \en Tn - NL No (012)
264 .Li \er Tn - CR No (015)
265 .Li \es Tn - SP No (040)
266 .Li \et Tn - HT No (011)
267 .Li \ev Tn - VT No (013)
268 .Li \e0 Tn - NUL No (000)
269 .Ed
270 .Pp
271 When using this format, the
272 .Fa nextc
273 parameter is looked at to determine
274 if a NUL character can be encoded as
275 .Ql \e0
276 instead of
277 .Ql \e000 .
278 If
279 .Fa nextc
280 is an octal digit, the latter representation is used to
281 avoid ambiguity.
282 .It Dv VIS_OCTAL
283 Use a three digit octal sequence.
284 The form is
285 .Ql \eddd
286 where
287 .Ar d
288 represents an octal digit.
289 .El
290 .Pp
291 There is one additional flag,
292 .Dv VIS_NOSLASH ,
293 which inhibits the
294 doubling of backslashes and the backslash before the default
295 format (that is, control characters are represented by
296 .Ql ^C
297 and
298 meta characters as
299 .Ql M-C ) .
300 With this flag set, the encoding is
301 ambiguous and non-invertible.
302 .Sh RETURN VALUES
303 .Fn vis
304 returns a pointer to the terminating NUL character of the string
305 .Fa dst .
306 .Pp
307 .Fn strvis
308 and
309 .Fn strvisx
310 return the number of characters in
311 .Fa dst
312 (not including the trailing NUL).
313 .Pp
314 .Fn strnvis
315 returns the length that
316 .Fa dst
317 would become if it were of unlimited size (similar to
318 .Xr snprintf 3
319 or
320 .Xr strlcpy 3 ) .
321 This can be used to detect truncation, but it also means that
322 the return value of
323 .Fn strnvis
324 must not be used without checking it against
325 .Fa dstsize .
326 .Pp
327 Upon successful completion,
328 .Fn stravis
329 returns the number of characters in
330 .Pf * Fa outp
331 (not including the trailing NUL).
332 Otherwise,
333 .Fn stravis
334 returns -1 and sets
335 .Va errno
336 to
337 .Er ENOMEM .
338 .Sh EXAMPLES
339 .Fn strvis
340 has unusual storage requirements that can lead to stack or heap corruption
341 if the destination is not carefully constructed.
342 A common mistake is to use the same size for the source and destination
343 when the destination actually needs up to 4 * strlen(source) + 1 bytes.
344 .Pp
345 If the length of a string to be encoded is not known at compile time, use
346 .Fn stravis :
347 .Bd -literal -offset indent
348 char *src, *dst;
350 \&...
351 if (stravis(&dst, src, VIS_OCTAL) == -1)
352 err(1, "stravis");
354 \&...
355 free(dst);
356 .Ed
357 .Pp
358 To encode a fixed size buffer,
359 .Fn strnvis
360 can be used with a fixed size target buffer:
361 .Bd -literal -offset indent
362 char src[MAXPATHLEN];
363 char dst[4 * MAXPATHLEN + 1];
365 \&...
366 if (strnvis(dst, src, sizeof(dst), VIS_OCTAL) >= sizeof(dst))
367 err(1, "strnvis");
368 .Ed
369 .Sh SEE ALSO
370 .Xr free 3 ,
371 .Xr snprintf 3 ,
372 .Xr strlcpy 3 ,
373 .Xr unvis 3
374 .Sh HISTORY
375 The
376 .Fn vis ,
377 .Fn strvis
378 and
379 .Fn strvisx
380 functions first appeared in
381 .Bx 4.4 ,
382 .Fn strnvis
383 in
384 .Ox 2.9
385 and
386 .Fn stravis
387 in
388 .Ox 5.7 .
389 .Pp
390 The
391 .Dv VIS_ALL
392 flag first appeared in
393 .Ox 4.9 .