| blob | 77c711ede47609e94de0ab584e1ae5d1b864decb |
1 .\" $NetBSD: vis.3,v 1.43 2015/05/23 11:47:56 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 May 23, 2015
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_SHELL
248 Also encode the meta characters used by shells (in addition to the glob
249 characters):
250 .Ql ( ' ,
251 .Ql ` ,
252 .Ql \&" ,
253 .Ql \&; ,
254 .Ql & ,
255 .Ql < ,
256 .Ql > ,
257 .Ql \&( ,
258 .Ql \&) ,
259 .Ql \&| ,
260 .Ql \&] ,
261 .Ql \e ,
262 .Ql $ ,
263 .Ql \&! ,
264 .Ql \&^ ,
265 and
266 .Ql ~ ) .
267 .It Dv VIS_SP
268 Also encode space.
269 .It Dv VIS_TAB
270 Also encode tab.
271 .It Dv VIS_NL
272 Also encode newline.
273 .It Dv VIS_WHITE
274 Synonym for
275 .Dv VIS_SP | VIS_TAB | VIS_NL .
276 .It Dv VIS_META
277 Synonym for
278 .Dv VIS_WHITE | VIS_GLOB | VIS_SHELL .
279 .It Dv VIS_SAFE
280 Only encode
281 .Dq unsafe
282 characters.
283 Unsafe means control characters which may cause common terminals to perform
284 unexpected functions.
285 Currently this form allows space, tab, newline, backspace, bell, and
286 return \(em in addition to all graphic characters \(em unencoded.
287 .El
288 .Pp
289 (The above flags have no effect for
290 .Fn svis ,
291 .Fn snvis ,
292 .Fn strsvis ,
293 .Fn strsnvis ,
294 .Fn strsvisx ,
295 and
296 .Fn strsnvisx .
297 When using these functions, place all graphic characters to be
298 encoded in an array pointed to by
299 .Fa extra .
300 In general, the backslash character should be included in this array, see the
301 warning on the use of the
302 .Dv VIS_NOSLASH
303 flag below).
304 .Pp
305 There are four forms of encoding.
306 All forms use the backslash character
307 .Ql \e
308 to introduce a special
309 sequence; two backslashes are used to represent a real backslash,
310 except
311 .Dv VIS_HTTPSTYLE
312 that uses
313 .Ql % ,
314 or
315 .Dv VIS_MIMESTYLE
316 that uses
317 .Ql = .
318 These are the visual formats:
319 .Bl -tag -width VIS_CSTYLE
320 .It (default)
321 Use an
322 .Ql M
323 to represent meta characters (characters with the 8th
324 bit set), and use caret
325 .Ql ^
326 to represent control characters (see
327 .Xr iscntrl 3 ) .
328 The following formats are used:
329 .Bl -tag -width xxxxx
330 .It Dv \e^C
331 Represents the control character
332 .Ql C .
333 Spans characters
334 .Ql \e000
335 through
336 .Ql \e037 ,
337 and
338 .Ql \e177
339 (as
340 .Ql \e^? ) .
341 .It Dv \eM-C
342 Represents character
343 .Ql C
344 with the 8th bit set.
345 Spans characters
346 .Ql \e241
347 through
348 .Ql \e376 .
349 .It Dv \eM^C
350 Represents control character
351 .Ql C
352 with the 8th bit set.
353 Spans characters
354 .Ql \e200
355 through
356 .Ql \e237 ,
357 and
358 .Ql \e377
359 (as
360 .Ql \eM^? ) .
361 .It Dv \e040
362 Represents
363 .Tn ASCII
364 space.
365 .It Dv \e240
366 Represents Meta-space.
367 .El
368 .Pp
369 .It Dv VIS_CSTYLE
370 Use C-style backslash sequences to represent standard non-printable
371 characters.
372 The following sequences are used to represent the indicated characters:
373 .Bd -unfilled -offset indent
374 .Li \ea Tn \(em BEL No (007)
375 .Li \eb Tn \(em BS No (010)
376 .Li \ef Tn \(em NP No (014)
377 .Li \en Tn \(em NL No (012)
378 .Li \er Tn \(em CR No (015)
379 .Li \es Tn \(em SP No (040)
380 .Li \et Tn \(em HT No (011)
381 .Li \ev Tn \(em VT No (013)
382 .Li \e0 Tn \(em NUL No (000)
383 .Ed
384 .Pp
385 When using this format, the
386 .Fa nextc
387 parameter is looked at to determine if a
388 .Dv NUL
389 character can be encoded as
390 .Ql \e0
391 instead of
392 .Ql \e000 .
393 If
394 .Fa nextc
395 is an octal digit, the latter representation is used to
396 avoid ambiguity.
397 .It Dv VIS_OCTAL
398 Use a three digit octal sequence.
399 The form is
400 .Ql \eddd
401 where
402 .Em d
403 represents an octal digit.
404 .It Dv VIS_HTTPSTYLE
405 Use URI encoding as described in RFC 1738.
406 The form is
407 .Ql %xx
408 where
409 .Em x
410 represents a lower case hexadecimal digit.
411 .It Dv VIS_MIMESTYLE
412 Use MIME Quoted-Printable encoding as described in RFC 2045, only don't
413 break lines and don't handle CRLF.
414 The form is
415 .Ql =XX
416 where
417 .Em X
418 represents an upper case hexadecimal digit.
419 .El
420 .Pp
421 There is one additional flag,
422 .Dv VIS_NOSLASH ,
423 which inhibits the
424 doubling of backslashes and the backslash before the default
425 format (that is, control characters are represented by
426 .Ql ^C
427 and
428 meta characters as
429 .Ql M-C ) .
430 With this flag set, the encoding is
431 ambiguous and non-invertible.
432 .Sh MULTIBYTE CHARACTER SUPPORT
433 These functions support multibyte character input.
434 The encoding conversion is influenced by the setting of the
435 .Ev LC_CTYPE
436 environment variable which defines the set of characters
437 that can be copied without encoding.
438 .Pp
439 If
440 .Dv VIS_NOLOCALE
441 is set, processing is done assuming the C locale and overriding
442 any other environment settings.
443 .Pp
444 When 8-bit data is present in the input,
445 .Ev LC_CTYPE
446 must be set to the correct locale or to the C locale.
447 If the locales of the data and the conversion are mismatched,
448 multibyte character recognition may fail and encoding will be performed
449 byte-by-byte instead.
450 .Pp
451 As noted above,
452 .Fa dst
453 must be four times the number of bytes processed from
454 .Fa src .
455 But note that each multibyte character can be up to
456 .Dv MB_LEN_MAX
457 bytes
458 .\" (see
459 .\" .Xr multibyte 3 )
460 so in terms of multibyte characters,
461 .Fa dst
462 must be four times
463 .Dv MB_LEN_MAX
464 times the number of characters processed from
465 .Fa src .
466 .Sh ENVIRONMENT
467 .Bl -tag -width ".Ev LC_CTYPE"
468 .It Ev LC_CTYPE
469 Specify the locale of the input data.
470 Set to C if the input data locale is unknown.
471 .El
472 .Sh ERRORS
473 The functions
474 .Fn nvis
475 and
476 .Fn snvis
477 will return
478 .Dv NULL
479 and the functions
480 .Fn strnvis ,
481 .Fn strnvisx ,
482 .Fn strsnvis ,
483 and
484 .Fn strsnvisx ,
485 will return \-1 when the
486 .Fa dlen
487 destination buffer size is not enough to perform the conversion while
488 setting
489 .Va errno
490 to:
491 .Bl -tag -width ".Bq Er ENOSPC"
492 .It Bq Er ENOSPC
493 The destination buffer size is not large enough to perform the conversion.
494 .El
495 .Sh SEE ALSO
496 .Xr unvis 1 ,
497 .Xr vis 1 ,
498 .Xr glob 3 ,
499 .\" .Xr multibyte 3 ,
500 .Xr unvis 3
501 .Rs
502 .%A T. Berners-Lee
503 .%T Uniform Resource Locators (URL)
504 .%O "RFC 1738"
505 .Re
506 .Rs
507 .%T "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies"
508 .%O "RFC 2045"
509 .Re
510 .Sh HISTORY
511 The
512 .Fn vis ,
513 .Fn strvis ,
514 and
515 .Fn strvisx
516 functions first appeared in
517 .Bx 4.4 .
518 The
519 .Fn svis ,
520 .Fn strsvis ,
521 and
522 .Fn strsvisx
523 functions appeared in
524 .Nx 1.5 .
525 The buffer size limited versions of the functions
526 .Po Fn nvis ,
527 .Fn strnvis ,
528 .Fn strnvisx ,
529 .Fn snvis ,
530 .Fn strsnvis ,
531 and
532 .Fn strsnvisx Pc
533 appeared in
534 .Nx 6.0
535 and
536 .Fx 9.2 .
537 Myltibyte character support was added in
538 .Nx 7.0
539 and
540 .Fx 9.2 .