| blob | 166316d1f9aec59a48c95cb58a0fbfab804a2279 |
1 .\" $NetBSD: vis.3,v 1.39 2013/02/20 20:05:26 christos 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 .\" @(#)vis.3 8.1 (Berkeley) 6/9/93
31 .\"
32 .Dd February 19, 2013
33 .Dt VIS 3
34 .Os
35 .Sh NAME
36 .Nm vis ,
37 .Nm nvis ,
38 .Nm strvis ,
39 .Nm strnvis ,
40 .Nm strvisx ,
41 .Nm strnvisx ,
42 .Nm strenvisx ,
43 .Nm svis ,
44 .Nm snvis ,
45 .Nm strsvis ,
46 .Nm strsnvis ,
47 .Nm strsvisx ,
48 .Nm strsnvisx ,
49 .Nm strsenvisx
50 .Nd visually encode characters
51 .Sh LIBRARY
52 .Lb libc
53 .Sh SYNOPSIS
54 .In vis.h
55 .Ft char *
56 .Fn vis "char *dst" "int c" "int flag" "int nextc"
57 .Ft char *
58 .Fn nvis "char *dst" "size_t dlen" "int c" "int flag" "int nextc"
59 .Ft int
60 .Fn strvis "char *dst" "const char *src" "int flag"
61 .Ft int
62 .Fn strnvis "char *dst" "size_t dlen" "const char *src" "int flag"
63 .Ft int
64 .Fn strvisx "char *dst" "const char *src" "size_t len" "int flag"
65 .Ft int
66 .Fn strnvisx "char *dst" "size_t dlen" "const char *src" "size_t len" "int flag"
67 .Ft int
68 .Fn strenvisx "char *dst" "size_t dlen" "const char *src" "size_t len" "int flag" "int *cerr_ptr"
69 .Ft char *
70 .Fn svis "char *dst" "int c" "int flag" "int nextc" "const char *extra"
71 .Ft char *
72 .Fn snvis "char *dst" "size_t dlen" "int c" "int flag" "int nextc" "const char *extra"
73 .Ft int
74 .Fn strsvis "char *dst" "const char *src" "int flag" "const char *extra"
75 .Ft int
76 .Fn strsnvis "char *dst" "size_t dlen" "const char *src" "int flag" "const char *extra"
77 .Ft int
78 .Fn strsvisx "char *dst" "const char *src" "size_t len" "int flag" "const char *extra"
79 .Ft int
80 .Fn strsnvisx "char *dst" "size_t dlen" "const char *src" "size_t len" "int flag" "const char *extra"
81 .Ft int
82 .Fn strsenvisx "char *dst" "size_t dlen" "const char *src" "size_t len" "int flag" "const char *extra" "int *cerr_ptr"
83 .Sh DESCRIPTION
84 The
85 .Fn vis
86 function
87 copies into
88 .Fa dst
89 a string which represents the character
90 .Fa c .
91 If
92 .Fa c
93 needs no encoding, it is copied in unaltered.
94 The string is null terminated, and a pointer to the end of the string is
95 returned.
96 The maximum length of any encoding is four
97 bytes (not including the trailing
98 .Dv NUL ) ;
99 thus, when
100 encoding a set of characters into a buffer, the size of the buffer should
101 be four times the number of bytes encoded, plus one for the trailing
102 .Dv NUL .
103 The flag parameter is used for altering the default range of
104 characters considered for encoding and for altering the visual
105 representation.
106 The additional character,
107 .Fa nextc ,
108 is only used when selecting the
109 .Dv VIS_CSTYLE
110 encoding format (explained below).
111 .Pp
112 The
113 .Fn strvis ,
114 .Fn strnvis ,
115 .Fn strvisx ,
116 and
117 .Fn strnvisx
118 functions copy into
119 .Fa dst
120 a visual representation of
121 the string
122 .Fa src .
123 The
124 .Fn strvis
125 and
126 .Fn strnvis
127 functions encode characters from
128 .Fa src
129 up to the
130 first
131 .Dv NUL .
132 The
133 .Fn strvisx
134 and
135 .Fn strnvisx
136 functions encode exactly
137 .Fa len
138 characters from
139 .Fa src
140 (this
141 is useful for encoding a block of data that may contain
142 .Dv NUL Ns 's ) .
143 Both forms
144 .Dv NUL
145 terminate
146 .Fa dst .
147 The size of
148 .Fa dst
149 must be four times the number
150 of bytes encoded from
151 .Fa src
152 (plus one for the
153 .Dv NUL ) .
154 Both
155 forms return the number of characters in
156 .Fa dst
157 (not including the trailing
158 .Dv NUL ) .
159 The
160 .Dq Nm n
161 versions of the functions also take an additional argument
162 .Fa dlen
163 that indicates the length of the
164 .Fa dst
165 buffer.
166 If
167 .Fa dlen
168 is not large enough to fit the converted string then the
169 .Fn strnvis
170 and
171 .Fn strnvisx
172 functions return \-1 and set
173 .Va errno
174 to
175 .Dv ENOSPC .
176 The
177 .Fn strenvisx
178 function takes an additional argument,
179 .Fa cerr_ptr ,
180 that is used to pass in and out a multibyte conversion error flag.
181 This is useful when processing single characters at a time when
182 it is possible that the locale may be set to something other
183 than the locale of the characters in the input data.
184 .Pp
185 The functions
186 .Fn svis ,
187 .Fn snvis ,
188 .Fn strsvis ,
189 .Fn strsnvis ,
190 .Fn strsvisx ,
191 .Fn strsnvisx ,
192 and
193 .Fn strsenvisx
194 correspond to
195 .Fn vis ,
196 .Fn nvis ,
197 .Fn strvis ,
198 .Fn strnvis ,
199 .Fn strvisx ,
200 .Fn strnvisx ,
201 and
202 .Fn strenvisx
203 but have an additional argument
204 .Fa extra ,
205 pointing to a
206 .Dv NUL
207 terminated list of characters.
208 These characters will be copied encoded or backslash-escaped into
209 .Fa dst .
210 These functions are useful e.g. to remove the special meaning
211 of certain characters to shells.
212 .Pp
213 The encoding is a unique, invertible representation composed entirely of
214 graphic characters; it can be decoded back into the original form using
215 the
216 .Xr unvis 3 ,
217 .Xr strunvis 3
218 or
219 .Xr strnunvis 3
220 functions.
221 .Pp
222 There are two parameters that can be controlled: the range of
223 characters that are encoded (applies only to
224 .Fn vis ,
225 .Fn nvis ,
226 .Fn strvis ,
227 .Fn strnvis ,
228 .Fn strvisx ,
229 and
230 .Fn strnvisx ) ,
231 and the type of representation used.
232 By default, all non-graphic characters,
233 except space, tab, and newline are encoded (see
234 .Xr isgraph 3 ) .
235 The following flags
236 alter this:
237 .Bl -tag -width VIS_WHITEX
238 .It Dv VIS_GLOB
239 Also encode the magic characters
240 .Ql ( * ,
241 .Ql \&? ,
242 .Ql \&[
243 and
244 .Ql # )
245 recognized by
246 .Xr glob 3 .
247 .It Dv VIS_SP
248 Also encode space.
249 .It Dv VIS_TAB
250 Also encode tab.
251 .It Dv VIS_NL
252 Also encode newline.
253 .It Dv VIS_WHITE
254 Synonym for
255 .Dv VIS_SP
256 \&|
257 .Dv VIS_TAB
258 \&|
259 .Dv VIS_NL .
260 .It Dv VIS_SAFE
261 Only encode
262 .Dq unsafe
263 characters.
264 Unsafe means control characters which may cause common terminals to perform
265 unexpected functions.
266 Currently this form allows space, tab, newline, backspace, bell, and
267 return \(em in addition to all graphic characters \(em unencoded.
268 .El
269 .Pp
270 (The above flags have no effect for
271 .Fn svis ,
272 .Fn snvis ,
273 .Fn strsvis ,
274 .Fn strsnvis ,
275 .Fn strsvisx ,
276 and
277 .Fn strsnvisx .
278 When using these functions, place all graphic characters to be
279 encoded in an array pointed to by
280 .Fa extra .
281 In general, the backslash character should be included in this array, see the
282 warning on the use of the
283 .Dv VIS_NOSLASH
284 flag below).
285 .Pp
286 There are four forms of encoding.
287 All forms use the backslash character
288 .Ql \e
289 to introduce a special
290 sequence; two backslashes are used to represent a real backslash,
291 except
292 .Dv VIS_HTTPSTYLE
293 that uses
294 .Ql % ,
295 or
296 .Dv VIS_MIMESTYLE
297 that uses
298 .Ql = .
299 These are the visual formats:
300 .Bl -tag -width VIS_CSTYLE
301 .It (default)
302 Use an
303 .Ql M
304 to represent meta characters (characters with the 8th
305 bit set), and use caret
306 .Ql ^
307 to represent control characters (see
308 .Xr iscntrl 3 ) .
309 The following formats are used:
310 .Bl -tag -width xxxxx
311 .It Dv \e^C
312 Represents the control character
313 .Ql C .
314 Spans characters
315 .Ql \e000
316 through
317 .Ql \e037 ,
318 and
319 .Ql \e177
320 (as
321 .Ql \e^? ) .
322 .It Dv \eM-C
323 Represents character
324 .Ql C
325 with the 8th bit set.
326 Spans characters
327 .Ql \e241
328 through
329 .Ql \e376 .
330 .It Dv \eM^C
331 Represents control character
332 .Ql C
333 with the 8th bit set.
334 Spans characters
335 .Ql \e200
336 through
337 .Ql \e237 ,
338 and
339 .Ql \e377
340 (as
341 .Ql \eM^? ) .
342 .It Dv \e040
343 Represents
344 .Tn ASCII
345 space.
346 .It Dv \e240
347 Represents Meta-space.
348 .El
349 .Pp
350 .It Dv VIS_CSTYLE
351 Use C-style backslash sequences to represent standard non-printable
352 characters.
353 The following sequences are used to represent the indicated characters:
354 .Bd -unfilled -offset indent
355 .Li \ea Tn \(em BEL No (007)
356 .Li \eb Tn \(em BS No (010)
357 .Li \ef Tn \(em NP No (014)
358 .Li \en Tn \(em NL No (012)
359 .Li \er Tn \(em CR No (015)
360 .Li \es Tn \(em SP No (040)
361 .Li \et Tn \(em HT No (011)
362 .Li \ev Tn \(em VT No (013)
363 .Li \e0 Tn \(em NUL No (000)
364 .Ed
365 .Pp
366 When using this format, the
367 .Fa nextc
368 parameter is looked at to determine if a
369 .Dv NUL
370 character can be encoded as
371 .Ql \e0
372 instead of
373 .Ql \e000 .
374 If
375 .Fa nextc
376 is an octal digit, the latter representation is used to
377 avoid ambiguity.
378 .It Dv VIS_OCTAL
379 Use a three digit octal sequence.
380 The form is
381 .Ql \eddd
382 where
383 .Em d
384 represents an octal digit.
385 .It Dv VIS_HTTPSTYLE
386 Use URI encoding as described in RFC 1738.
387 The form is
388 .Ql %xx
389 where
390 .Em x
391 represents a lower case hexadecimal digit.
392 .It Dv VIS_MIMESTYLE
393 Use MIME Quoted-Printable encoding as described in RFC 2045, only don't
394 break lines and don't handle CRLF.
395 The form is
396 .Ql =XX
397 where
398 .Em X
399 represents an upper case hexadecimal digit.
400 .El
401 .Pp
402 There is one additional flag,
403 .Dv VIS_NOSLASH ,
404 which inhibits the
405 doubling of backslashes and the backslash before the default
406 format (that is, control characters are represented by
407 .Ql ^C
408 and
409 meta characters as
410 .Ql M-C ) .
411 With this flag set, the encoding is
412 ambiguous and non-invertible.
413 .Sh MULTIBYTE CHARACTER SUPPORT
414 These functions support multibyte character input.
415 The encoding conversion is influenced by the setting of the
416 .Ev LC_CTYPE
417 environment variable which defines the set of characters
418 that can be copied without encoding.
419 .Pp
420 When 8-bit data is present in the input,
421 .Ev LC_CTYPE
422 must be set to the correct locale or to the C locale.
423 If the locales of the data and the conversion are mismatched,
424 multibyte character recognition may fail and encoding will be performed
425 byte-by-byte instead.
426 .Pp
427 As noted above,
428 .Fa dst
429 must be four times the number of bytes processed from
430 .Fa src .
431 But note that each multibyte character can be up to
432 .Dv MB_LEN_MAX
433 bytes
434 .\" (see
435 .\" .Xr multibyte 3 )
436 so in terms of multibyte characters,
437 .Fa dst
438 must be four times
439 .Dv MB_LEN_MAX
440 times the number of characters processed from
441 .Fa src .
442 .Sh ENVIRONMENT
443 .Bl -tag -width ".Ev LC_CTYPE"
444 .It Ev LC_CTYPE
445 Specify the locale of the input data.
446 Set to C if the input data locale is unknown.
447 .El
448 .Sh ERRORS
449 The functions
450 .Fn nvis
451 and
452 .Fn snvis
453 will return
454 .Dv NULL
455 and the functions
456 .Fn strnvis ,
457 .Fn strnvisx ,
458 .Fn strsnvis ,
459 and
460 .Fn strsnvisx ,
461 will return \-1 when the
462 .Fa dlen
463 destination buffer size is not enough to perform the conversion while
464 setting
465 .Va errno
466 to:
467 .Bl -tag -width ".Bq Er ENOSPC"
468 .It Bq Er ENOSPC
469 The destination buffer size is not large enough to perform the conversion.
470 .El
471 .Sh SEE ALSO
472 .Xr unvis 1 ,
473 .Xr vis 1 ,
474 .Xr glob 3 ,
475 .\" .Xr multibyte 3 ,
476 .Xr unvis 3
477 .Rs
478 .%A T. Berners-Lee
479 .%T Uniform Resource Locators (URL)
480 .%O "RFC 1738"
481 .Re
482 .Rs
483 .%T "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies"
484 .%O "RFC 2045"
485 .Re
486 .Sh HISTORY
487 The
488 .Fn vis ,
489 .Fn strvis ,
490 and
491 .Fn strvisx
492 functions first appeared in
493 .Bx 4.4 .
494 The
495 .Fn svis ,
496 .Fn strsvis ,
497 and
498 .Fn strsvisx
499 functions appeared in
500 .Nx 1.5 .
501 The buffer size limited versions of the functions
502 .Po Fn nvis ,
503 .Fn strnvis ,
504 .Fn strnvisx ,
505 .Fn snvis ,
506 .Fn strsnvis ,
507 and
508 .Fn strsnvisx Pc
509 appeared in
510 .Nx 6.0
511 and
512 .Fx 9.2 .
513 Myltibyte character support was added in
514 .Nx 7.0
515 and
516 .Fx 9.2 .