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