1 .\" $NetBSD: vis.3,v 1.49 2017/08/05 20:22:29 wiz Exp $
4 .\" Copyright (c) 1989, 1991, 1993
5 .\" The Regents of the University of California. All rights reserved.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
15 .\" 3. Neither the name of the University nor the names of its contributors
16 .\" may be used to endorse or promote products derived from this software
17 .\" without specific prior written permission.
19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31 .\" @(#)vis.3 8.1 (Berkeley) 6/9/93
52 .Nd visually encode characters
58 .Fn vis "char *dst" "int c" "int flag" "int nextc"
60 .Fn nvis "char *dst" "size_t dlen" "int c" "int flag" "int nextc"
62 .Fn strvis "char *dst" "const char *src" "int flag"
64 .Fn stravis "char **dst" "const char *src" "int flag"
66 .Fn strnvis "char *dst" "size_t dlen" "const char *src" "int flag"
68 .Fn strvisx "char *dst" "const char *src" "size_t len" "int flag"
70 .Fn strnvisx "char *dst" "size_t dlen" "const char *src" "size_t len" "int flag"
72 .Fn strenvisx "char *dst" "size_t dlen" "const char *src" "size_t len" "int flag" "int *cerr_ptr"
74 .Fn svis "char *dst" "int c" "int flag" "int nextc" "const char *extra"
76 .Fn snvis "char *dst" "size_t dlen" "int c" "int flag" "int nextc" "const char *extra"
78 .Fn strsvis "char *dst" "const char *src" "int flag" "const char *extra"
80 .Fn strsnvis "char *dst" "size_t dlen" "const char *src" "int flag" "const char *extra"
82 .Fn strsvisx "char *dst" "const char *src" "size_t len" "int flag" "const char *extra"
84 .Fn strsnvisx "char *dst" "size_t dlen" "const char *src" "size_t len" "int flag" "const char *extra"
86 .Fn strsenvisx "char *dst" "size_t dlen" "const char *src" "size_t len" "int flag" "const char *extra" "int *cerr_ptr"
93 a string which represents the character
97 needs no encoding, it is copied in unaltered.
98 The string is null terminated, and a pointer to the end of the string is
100 The maximum length of any encoding is four
101 bytes (not including the trailing
104 encoding a set of characters into a buffer, the size of the buffer should
105 be four times the number of bytes encoded, plus one for the trailing
107 The flag parameter is used for altering the default range of
108 characters considered for encoding and for altering the visual
110 The additional character,
112 is only used when selecting the
114 encoding format (explained below).
125 a visual representation of
132 functions encode characters from
141 functions encode exactly
146 is useful for encoding a block of data that may contain
154 must be four times the number
155 of bytes encoded from
160 forms return the number of characters in
162 (not including the trailing
166 function allocates space dynamically to hold the string.
169 versions of the functions also take an additional argument
171 that indicates the length of the
176 is not large enough to fit the converted string then the
180 functions return \-1 and set
186 function takes an additional argument,
188 that is used to pass in and out a multibyte conversion error flag.
189 This is useful when processing single characters at a time when
190 it is possible that the locale may be set to something other
191 than the locale of the characters in the input data.
211 but have an additional argument
215 terminated list of characters.
216 These characters will be copied encoded or backslash-escaped into
218 These functions are useful e.g. to remove the special meaning
219 of certain characters to shells.
221 The encoding is a unique, invertible representation composed entirely of
222 graphic characters; it can be decoded back into the original form using
230 There are two parameters that can be controlled: the range of
231 characters that are encoded (applies only to
239 and the type of representation used.
240 By default, all non-graphic characters,
241 except space, tab, and newline are encoded (see
245 .Bl -tag -width VIS_WHITEX
247 Also encode double quotes
249 Also encode the magic characters
258 Also encode the meta characters used by shells (in addition to the glob
285 .Dv VIS_SP | VIS_TAB | VIS_NL .
288 .Dv VIS_WHITE | VIS_GLOB | VIS_SHELL .
293 Unsafe means control characters which may cause common terminals to perform
294 unexpected functions.
295 Currently this form allows space, tab, newline, backspace, bell, and
296 return \(em in addition to all graphic characters \(em unencoded.
299 (The above flags have no effect for
307 When using these functions, place all graphic characters to be
308 encoded in an array pointed to by
310 In general, the backslash character should be included in this array, see the
311 warning on the use of the
315 There are six forms of encoding.
316 All forms use the backslash character
318 to introduce a special
319 sequence; two backslashes are used to represent a real backslash,
328 These are the visual formats:
329 .Bl -tag -width VIS_CSTYLE
333 to represent meta characters (characters with the 8th
334 bit set), and use caret
336 to represent control characters (see
338 The following formats are used:
339 .Bl -tag -width xxxxx
341 Represents the control character
354 with the 8th bit set.
360 Represents control character
362 with the 8th bit set.
376 Represents Meta-space.
379 Use C-style backslash sequences to represent standard non-printable
381 The following sequences are used to represent the indicated characters:
382 .Bd -unfilled -offset indent
383 .Li \ea Tn \(em BEL No (007)
384 .Li \eb Tn \(em BS No (010)
385 .Li \ef Tn \(em NP No (014)
386 .Li \en Tn \(em NL No (012)
387 .Li \er Tn \(em CR No (015)
388 .Li \es Tn \(em SP No (040)
389 .Li \et Tn \(em HT No (011)
390 .Li \ev Tn \(em VT No (013)
391 .Li \e0 Tn \(em NUL No (000)
394 When using this format, the
396 parameter is looked at to determine if a
398 character can be encoded as
404 is an octal digit, the latter representation is used to
407 Non-printable characters without C-style
408 backslash sequences use the default representation.
410 Use a three digit octal sequence.
415 represents an octal digit.
416 .It Dv VIS_CSTYLE \&| Dv VIS_OCTAL
419 except that non-printable characters without C-style
420 backslash sequences use a three digit octal sequence.
422 Use URI encoding as described in RFC 1738.
427 represents a lower case hexadecimal digit.
429 Use MIME Quoted-Printable encoding as described in RFC 2045, only don't
430 break lines and don't handle CRLF.
435 represents an upper case hexadecimal digit.
438 There is one additional flag,
441 doubling of backslashes and the backslash before the default
442 format (that is, control characters are represented by
447 With this flag set, the encoding is
448 ambiguous and non-invertible.
449 .Sh MULTIBYTE CHARACTER SUPPORT
450 These functions support multibyte character input.
451 The encoding conversion is influenced by the setting of the
453 environment variable which defines the set of characters
454 that can be copied without encoding.
458 is set, processing is done assuming the C locale and overriding
459 any other environment settings.
461 When 8-bit data is present in the input,
463 must be set to the correct locale or to the C locale.
464 If the locales of the data and the conversion are mismatched,
465 multibyte character recognition may fail and encoding will be performed
466 byte-by-byte instead.
470 must be four times the number of bytes processed from
472 But note that each multibyte character can be up to
476 .\" .Xr multibyte 3 )
477 so in terms of multibyte characters,
481 times the number of characters processed from
484 .Bl -tag -width ".Ev LC_CTYPE"
486 Specify the locale of the input data.
487 Set to C if the input data locale is unknown.
502 will return \-1 when the
504 destination buffer size is not enough to perform the conversion while
508 .Bl -tag -width ".Bq Er ENOSPC"
510 The destination buffer size is not large enough to perform the conversion.
516 .\" .Xr multibyte 3 ,
520 .%T Uniform Resource Locators (URL)
524 .%T "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies"
533 functions first appeared in
540 functions appeared in
544 The buffer size limited versions of the functions
556 Multibyte character support was added in