Merge from vendor branch BZIP:
[dragonfly.git] / lib / libc / gen / vis.3
1 .\" Copyright (c) 1989, 1991, 1993
2 .\"     The Regents of the University of California.  All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\"    notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\"    notice, this list of conditions and the following disclaimer in the
11 .\"    documentation and/or other materials provided with the distribution.
12 .\" 3. All advertising materials mentioning features or use of this software
13 .\"    must display the following acknowledgement:
14 .\"     This product includes software developed by the University of
15 .\"     California, Berkeley and its contributors.
16 .\" 4. Neither the name of the University nor the names of its contributors
17 .\"    may be used to endorse or promote products derived from this software
18 .\"    without specific prior written permission.
19 .\"
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" SUCH DAMAGE.
31 .\"
32 .\"     From: @(#)vis.3 8.1 (Berkeley) 6/9/93
33 .\" $FreeBSD: src/lib/libc/gen/vis.3,v 1.27 2005/01/15 11:40:33 ru Exp $
34 .\" $DragonFly: src/lib/libc/gen/vis.3,v 1.4 2005/09/03 16:25:42 joerg Exp $
35 .\"
36 .Dd March 21, 2004
37 .Dt VIS 3
38 .Os
39 .Sh NAME
40 .Nm vis
41 .Nd visually encode characters
42 .Sh LIBRARY
43 .Lb libc
44 .Sh SYNOPSIS
45 .In vis.h
46 .Ft char *
47 .Fn vis "char *dst" "int c" "int flag" "int nextc"
48 .Ft int
49 .Fn strvis "char *dst" "const char *src" "int flag"
50 .Ft int
51 .Fn strnvis "char *dst" "const char *src" "size_t len" "int flag"
52 .Ft int
53 .Fn strvisx "char *dst" "const char *src" "size_t len" "int flag"
54 .Sh DESCRIPTION
55 The
56 .Fn vis
57 function
58 copies into
59 .Fa dst
60 a string which represents the character
61 .Fa c .
62 If
63 .Fa c
64 needs no encoding, it is copied in unaltered.
65 The string is
66 null terminated, and a pointer to the end of the string is
67 returned.
68 The maximum length of any encoding is four
69 characters (not including the trailing
70 .Dv NUL ) ;
71 thus, when
72 encoding a set of characters into a buffer, the size of the buffer should
73 be four times the number of characters encoded, plus one for the trailing
74 .Dv NUL .
75 The
76 .Fa flag
77 argument is used for altering the default range of
78 characters considered for encoding and for altering the visual
79 representation.
80 The additional character,
81 .Fa nextc ,
82 is only used when selecting the
83 .Dv VIS_CSTYLE
84 encoding format (explained below).
85 .Pp
86 The
87 .Fn strvis ,
88 .Fn strnvis
89 and
90 .Fn strvisx
91 functions copy into
92 .Fa dst
93 a visual representation of
94 the string
95 .Fa src .
96 The
97 .Fn strvis
98 function encodes characters from
99 .Fa src
100 up to the
101 first
102 .Dv NUL .
103 The
104 .Fn strnvis
105 function works like
106 .Fn strvis ,
107 but writes at most
108 .Fa len - 1
109 characters to
110 .Fa dst
111 and terminates the string with
112 .Dv NUL .
113 The
114 .Fn strvisx
115 function encodes exactly
116 .Fa len
117 characters from
118 .Fa src
119 (this
120 is useful for encoding a block of data that may contain
121 .Dv NUL Ns 's ) .
122 Both forms
123 .Dv NUL
124 terminate
125 .Fa dst .
126 The size of
127 .Fa dst
128 must be four times the number
129 of characters encoded from
130 .Fa src
131 (plus one for the
132 .Dv NUL ) .
133 Both
134 forms return the number of characters in dst (not including
135 the trailing
136 .Dv NUL ) .
137 .Pp
138 The encoding is a unique, invertible representation composed entirely of
139 graphic characters; it can be decoded back into the original form using
140 the
141 .Xr unvis 3
142 or
143 .Xr strunvis 3
144 functions.
145 .Pp
146 There are two parameters that can be controlled: the range of
147 characters that are encoded, and the type
148 of representation used.
149 By default, all non-graphic characters
150 except space, tab, and newline are encoded.
151 (See
152 .Xr isgraph 3 . )
153 The following flags
154 alter this:
155 .Bl -tag -width VIS_WHITEX
156 .It Dv VIS_GLOB
157 Also encode magic characters
158 .Ql ( * ,
159 .Ql \&? ,
160 .Ql \&[
161 and
162 .Ql # )
163 recognized by
164 .Xr glob 3 .
165 .It Dv VIS_SP
166 Also encode space.
167 .It Dv VIS_TAB
168 Also encode tab.
169 .It Dv VIS_NL
170 Also encode newline.
171 .It Dv VIS_WHITE
172 Synonym for
173 .Dv VIS_SP
174 \&|
175 .Dv VIS_TAB
176 \&|
177 .Dv VIS_NL .
178 .It Dv VIS_SAFE
179 Only encode "unsafe" characters.
180 Unsafe means control
181 characters which may cause common terminals to perform
182 unexpected functions.
183 Currently this form allows space,
184 tab, newline, backspace, bell, and return - in addition
185 to all graphic characters - unencoded.
186 .El
187 .Pp
188 There are four forms of encoding.
189 Most forms use the backslash character
190 .Ql \e
191 to introduce a special
192 sequence; two backslashes are used to represent a real backslash.
193 These are the visual formats:
194 .Bl -tag -width VIS_HTTPSTYLE
195 .It (default)
196 Use an
197 .Ql M
198 to represent meta characters (characters with the 8th
199 bit set), and use caret
200 .Ql ^
201 to represent control characters see
202 .Pf ( Xr iscntrl 3 ) .
203 The following formats are used:
204 .Bl -tag -width xxxxx
205 .It Dv \e^C
206 Represents the control character
207 .Ql C .
208 Spans characters
209 .Ql \e000
210 through
211 .Ql \e037 ,
212 and
213 .Ql \e177
214 (as
215 .Ql \e^? ) .
216 .It Dv \eM-C
217 Represents character
218 .Ql C
219 with the 8th bit set.
220 Spans characters
221 .Ql \e241
222 through
223 .Ql \e376 .
224 .It Dv \eM^C
225 Represents control character
226 .Ql C
227 with the 8th bit set.
228 Spans characters
229 .Ql \e200
230 through
231 .Ql \e237 ,
232 and
233 .Ql \e377
234 (as
235 .Ql \eM^? ) .
236 .It Dv \e040
237 Represents
238 .Tn ASCII
239 space.
240 .It Dv \e240
241 Represents Meta-space.
242 .El
243 .Pp
244 .It Dv VIS_CSTYLE
245 Use C-style backslash sequences to represent standard non-printable
246 characters.
247 The following sequences are used to represent the indicated characters:
248 .Pp
249 .Bl -tag -width ".Li \e0" -offset indent -compact
250 .It Li \ea
251 .Dv BEL No (007)
252 .It Li \eb
253 .Dv BS No (010)
254 .It Li \ef
255 .Dv NP No (014)
256 .It Li \en
257 .Dv NL No (012)
258 .It Li \er
259 .Dv CR No (015)
260 .It Li \et
261 .Dv HT No (011)
262 .It Li \ev
263 .Dv VT No (013)
264 .It Li \e0
265 .Dv NUL No (000)
266 .El
267 .Pp
268 When using this format, the
269 .Fa nextc
270 argument is looked at to determine
271 if a
272 .Dv NUL
273 character can be encoded as
274 .Ql \e0
275 instead of
276 .Ql \e000 .
277 If
278 .Fa nextc
279 is an octal digit, the latter representation is used to
280 avoid ambiguity.
281 .It Dv VIS_HTTPSTYLE
282 Use URI encoding as described in RFC 1808.
283 The form is
284 .Ql %dd
285 where
286 .Ar d
287 represents a hexadecimal digit.
288 .It Dv VIS_OCTAL
289 Use a three digit octal sequence.
290 The form is
291 .Ql \eddd
292 where
293 .Ar d
294 represents an octal digit.
295 .El
296 .Pp
297 There is one additional flag,
298 .Dv VIS_NOSLASH ,
299 which inhibits the
300 doubling of backslashes and the backslash before the default
301 format (that is, control characters are represented by
302 .Ql ^C
303 and
304 meta characters as
305 .Ql M-C ) .
306 With this flag set, the encoding is
307 ambiguous and non-invertible.
308 .Sh SEE ALSO
309 .Xr unvis 1 ,
310 .Xr unvis 3
311 .Rs
312 .%A R. Fielding
313 .%T Relative Uniform Resource Locators
314 .%O RFC1808
315 .Re
316 .Sh HISTORY
317 These functions first appeared in
318 .Bx 4.4 .
319 .Sh BUGS
320 The
321 .Nm
322 family of functions do not recognize multibyte characters, and thus
323 may consider them to be non-printable when they are in fact printable
324 (and vice versa.)