Annotation of src/lib/libc/gen/vis.3, Revision 1.25
1.25 ! wiz 1: .\" $NetBSD: vis.3,v 1.24 2011/03/12 19:52:48 christos Exp $
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.
1.19 agc 14: .\" 3. Neither the name of the University nor the names of its contributors
1.1 cgd 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: .\"
1.6 cgd 30: .\" @(#)vis.3 8.1 (Berkeley) 6/9/93
1.1 cgd 31: .\"
1.24 christos 32: .Dd March 12, 2011
1.1 cgd 33: .Dt VIS 3
34: .Os
35: .Sh NAME
1.8 mrg 36: .Nm vis ,
1.24 christos 37: .Nm nvis ,
1.8 mrg 38: .Nm strvis ,
1.24 christos 39: .Nm strnvis ,
1.12 wennmach 40: .Nm strvisx ,
1.24 christos 41: .Nm strnvisx ,
1.12 wennmach 42: .Nm svis ,
1.24 christos 43: .Nm snvis ,
1.12 wennmach 44: .Nm strsvis ,
1.24 christos 45: .Nm strsnvis ,
1.12 wennmach 46: .Nm strsvisx
1.24 christos 47: .Nm strsnvisx
1.1 cgd 48: .Nd visually encode characters
1.10 perry 49: .Sh LIBRARY
50: .Lb libc
1.1 cgd 51: .Sh SYNOPSIS
1.18 wiz 52: .In vis.h
1.1 cgd 53: .Ft char *
1.12 wennmach 54: .Fn vis "char *dst" "int c" "int flag" "int nextc"
1.24 christos 55: .Ft char *
56: .Fn nvis "char *dst" "size_t dlen" "int c" "int flag" "int nextc"
1.13 wiz 57: .Ft int
1.12 wennmach 58: .Fn strvis "char *dst" "const char *src" "int flag"
1.13 wiz 59: .Ft int
1.24 christos 60: .Fn strnvis "char *dst" "size_t dlen" "const char *src" "int flag"
61: .Ft int
1.12 wennmach 62: .Fn strvisx "char *dst" "const char *src" "size_t len" "int flag"
1.24 christos 63: .Ft int
64: .Fn strnvisx "char *dst" "size_t dlen" "const char *src" "size_t len" "int flag"
1.12 wennmach 65: .Ft char *
66: .Fn svis "char *dst" "int c" "int flag" "int nextc" "const char *extra"
1.24 christos 67: .Ft char *
68: .Fn snvis "char *dst" "size_t dlen" "int c" "int flag" "int nextc" "const char *extra"
1.13 wiz 69: .Ft int
1.12 wennmach 70: .Fn strsvis "char *dst" "const char *src" "int flag" "const char *extra"
1.13 wiz 71: .Ft int
1.24 christos 72: .Fn strsnvis "char *dst" "size_t dlen" "const char *src" "int flag" "const char *extra"
73: .Ft int
1.12 wennmach 74: .Fn strsvisx "char *dst" "const char *src" "size_t len" "int flag" "const char *extra"
1.24 christos 75: .Ft int
76: .Fn strsnvisx "char *dst" "size_t dlen" "const char *src" "size_t len" "int flag" "const char *extra"
1.1 cgd 77: .Sh DESCRIPTION
78: The
79: .Fn vis
80: function
81: copies into
82: .Fa dst
83: a string which represents the character
84: .Fa c .
85: If
86: .Fa c
1.17 wiz 87: needs no encoding, it is copied in unaltered.
88: The string is null terminated, and a pointer to the end of the string is
89: returned.
90: The maximum length of any encoding is four
1.1 cgd 91: characters (not including the trailing
1.13 wiz 92: .Dv NUL ) ;
1.1 cgd 93: thus, when
94: encoding a set of characters into a buffer, the size of the buffer should
95: be four times the number of characters encoded, plus one for the trailing
1.13 wiz 96: .Dv NUL .
1.1 cgd 97: The flag parameter is used for altering the default range of
98: characters considered for encoding and for altering the visual
99: representation.
100: The additional character,
101: .Fa nextc ,
102: is only used when selecting the
103: .Dv VIS_CSTYLE
104: encoding format (explained below).
105: .Pp
106: The
1.24 christos 107: .Fn strvis ,
108: .Fn strnvis ,
109: .Fn strvisx ,
1.1 cgd 110: and
1.24 christos 111: .Fn strnvisx
1.1 cgd 112: functions copy into
113: .Fa dst
114: a visual representation of
115: the string
116: .Fa src .
117: The
118: .Fn strvis
1.24 christos 119: and
120: .Fn strnvis
121: functions encode characters from
1.1 cgd 122: .Fa src
123: up to the
124: first
1.13 wiz 125: .Dv NUL .
1.1 cgd 126: The
127: .Fn strvisx
1.24 christos 128: and
129: .Fn strnvisx
130: functions encode exactly
1.1 cgd 131: .Fa len
132: characters from
133: .Fa src
134: (this
135: is useful for encoding a block of data that may contain
1.13 wiz 136: .Dv NUL Ns 's ) .
1.1 cgd 137: Both forms
1.5 mycroft 138: .Dv NUL
1.1 cgd 139: terminate
140: .Fa dst .
141: The size of
142: .Fa dst
143: must be four times the number
144: of characters encoded from
145: .Fa src
146: (plus one for the
1.13 wiz 147: .Dv NUL ) .
1.1 cgd 148: Both
149: forms return the number of characters in dst (not including
150: the trailing
1.13 wiz 151: .Dv NUL ) .
1.24 christos 152: The
153: .Dq n
154: versions of the functions also take an additional argument
155: .Fa dlen
156: that indicates the length of the
157: .Fa dst
158: buffer.
159: If
160: .Fa dlen
161: is not large enough to fix the converted string then the
162: .Fn strnvis
163: and
164: .Fn strnvisx
1.25 ! wiz 165: functions return \-1 and set
1.24 christos 166: .Va errno
167: to
168: .Dv ENOSPC .
1.1 cgd 169: .Pp
1.12 wennmach 170: The functions
171: .Fn svis ,
1.24 christos 172: .Fn snvis ,
1.12 wennmach 173: .Fn strsvis ,
1.24 christos 174: .Fn strsnvis ,
175: .Fn strsvisx ,
1.12 wennmach 176: and
1.24 christos 177: .Fn strsnvisx
1.12 wennmach 178: correspond to
179: .Fn vis ,
1.24 christos 180: .Fn nvis ,
1.12 wennmach 181: .Fn strvis ,
1.24 christos 182: .Fn strnvis ,
1.25 ! wiz 183: .Fn strvisx ,
1.12 wennmach 184: and
1.24 christos 185: .Fn strnvisx
1.12 wennmach 186: but have an additional argument
187: .Fa extra ,
188: pointing to a
189: .Dv NUL
1.17 wiz 190: terminated list of characters.
191: These characters will be copied encoded or backslash-escaped into
1.12 wennmach 192: .Fa dst .
1.17 wiz 193: These functions are useful e.g. to remove the special meaning
1.12 wennmach 194: of certain characters to shells.
195: .Pp
1.7 scottr 196: The encoding is a unique, invertible representation composed entirely of
1.13 wiz 197: graphic characters; it can be decoded back into the original form using
1.1 cgd 198: the
1.24 christos 199: .Xr unvis 3 ,
200: .Xr strunvis 3
1.1 cgd 201: or
1.24 christos 202: .Xr strnunvis 3
1.1 cgd 203: functions.
204: .Pp
205: There are two parameters that can be controlled: the range of
1.12 wennmach 206: characters that are encoded (applies only to
207: .Fn vis ,
1.24 christos 208: .Fn nvis ,
1.12 wennmach 209: .Fn strvis ,
1.24 christos 210: .Fn strnvis ,
211: .Fn strvisx ,
1.12 wennmach 212: and
1.24 christos 213: .Fn strnvisx ) ,
1.13 wiz 214: and the type of representation used.
1.12 wennmach 215: By default, all non-graphic characters,
1.1 cgd 216: except space, tab, and newline are encoded.
217: (See
218: .Xr isgraph 3 . )
219: The following flags
220: alter this:
221: .Bl -tag -width VIS_WHITEX
222: .It Dv VIS_SP
223: Also encode space.
1.13 wiz 224: .It Dv VIS_TAB
1.1 cgd 225: Also encode tab.
226: .It Dv VIS_NL
227: Also encode newline.
1.13 wiz 228: .It Dv VIS_WHITE
1.1 cgd 229: Synonym for
230: .Dv VIS_SP
231: \&|
232: .Dv VIS_TAB
233: \&|
234: .Dv VIS_NL .
1.13 wiz 235: .It Dv VIS_SAFE
1.17 wiz 236: Only encode "unsafe" characters.
237: Unsafe means control characters which may cause common terminals to perform
238: unexpected functions.
239: Currently this form allows space, tab, newline, backspace, bell, and
240: return - in addition to all graphic characters - unencoded.
1.1 cgd 241: .El
242: .Pp
1.12 wennmach 243: (The above flags have no effect for
244: .Fn svis ,
1.24 christos 245: .Fn snvis ,
1.12 wennmach 246: .Fn strsvis ,
1.24 christos 247: .Fn strsnvis ,
1.25 ! wiz 248: .Fn strsvisx ,
1.12 wennmach 249: and
1.24 christos 250: .Fn strsnvisx .
1.12 wennmach 251: When using these functions, place all graphic characters to be
252: encoded in an array pointed to by
253: .Fa extra .
254: In general, the backslash character should be included in this array, see the
255: warning on the use of the
256: .Dv VIS_NOSLASH
257: flag below).
258: .Pp
1.16 christos 259: There are four forms of encoding.
1.1 cgd 260: All forms use the backslash character
261: .Ql \e
262: to introduce a special
1.16 christos 263: sequence; two backslashes are used to represent a real backslash,
264: except
265: .Dv VIS_HTTPSTYLE
266: that uses
1.23 christos 267: .Ql % ,
268: or
269: .Dv VIS_MIMESTYLE
270: that uses
271: .Ql = .
1.1 cgd 272: These are the visual formats:
273: .Bl -tag -width VIS_CSTYLE
274: .It (default)
275: Use an
276: .Ql M
277: to represent meta characters (characters with the 8th
1.4 jtc 278: bit set), and use caret
1.1 cgd 279: .Ql ^
280: to represent control characters see
281: .Pf ( Xr iscntrl 3 ) .
282: The following formats are used:
283: .Bl -tag -width xxxxx
284: .It Dv \e^C
285: Represents the control character
286: .Ql C .
287: Spans characters
288: .Ql \e000
289: through
290: .Ql \e037 ,
291: and
292: .Ql \e177
293: (as
294: .Ql \e^? ) .
295: .It Dv \eM-C
296: Represents character
297: .Ql C
298: with the 8th bit set.
299: Spans characters
300: .Ql \e241
301: through
302: .Ql \e376 .
303: .It Dv \eM^C
304: Represents control character
305: .Ql C
306: with the 8th bit set.
307: Spans characters
308: .Ql \e200
309: through
310: .Ql \e237 ,
311: and
312: .Ql \e377
313: (as
314: .Ql \eM^? ) .
315: .It Dv \e040
316: Represents
317: .Tn ASCII
318: space.
319: .It Dv \e240
320: Represents Meta-space.
321: .El
322: .Pp
323: .It Dv VIS_CSTYLE
324: Use C-style backslash sequences to represent standard non-printable
325: characters.
326: The following sequences are used to represent the indicated characters:
327: .Bd -unfilled -offset indent
328: .Li \ea Tn - BEL No (007)
329: .Li \eb Tn - BS No (010)
330: .Li \ef Tn - NP No (014)
331: .Li \en Tn - NL No (012)
332: .Li \er Tn - CR No (015)
1.22 jschauma 333: .Li \es Tn - SP No (040)
1.1 cgd 334: .Li \et Tn - HT No (011)
335: .Li \ev Tn - VT No (013)
336: .Li \e0 Tn - NUL No (000)
337: .Ed
338: .Pp
339: When using this format, the nextc parameter is looked at to determine
340: if a
1.5 mycroft 341: .Dv NUL
1.1 cgd 342: character can be encoded as
343: .Ql \e0
344: instead of
345: .Ql \e000 .
346: If
347: .Fa nextc
348: is an octal digit, the latter representation is used to
349: avoid ambiguity.
350: .It Dv VIS_OCTAL
1.17 wiz 351: Use a three digit octal sequence.
352: The form is
1.1 cgd 353: .Ql \eddd
354: where
355: .Em d
356: represents an octal digit.
1.16 christos 357: .It Dv VIS_HTTPSTYLE
1.20 lukem 358: Use URI encoding as described in RFC 1738.
1.16 christos 359: The form is
360: .Ql %xx
361: where
362: .Em x
1.23 christos 363: represents a lower case hexadecimal digit.
364: .It Dv VIS_MIMESTYLE
365: Use MIME Quoted-Printable encoding as described in RFC 2045, only don't
366: break lines and don't handle CRLF.
367: The form is:
368: .Ql %XX
369: where
370: .Em X
371: represents an upper case hexadecimal digit.
1.1 cgd 372: .El
373: .Pp
374: There is one additional flag,
375: .Dv VIS_NOSLASH ,
376: which inhibits the
377: doubling of backslashes and the backslash before the default
378: format (that is, control characters are represented by
379: .Ql ^C
380: and
381: meta characters as
382: .Ql M-C ) .
383: With this flag set, the encoding is
384: ambiguous and non-invertible.
1.24 christos 385: .Sh ERRORS
386: The functions
387: .Fn nvis
388: and
389: .Fn snvis
390: will return
391: .Dv NULL
392: and the functions
393: .Fn strnvis ,
394: .Fn strnvisx ,
395: .Fn strsnvis ,
396: and
397: .Fn strsnvisx ,
1.25 ! wiz 398: will return \-1 when the
1.24 christos 399: .Fa dlen
400: destination buffer length size is not enough to perform the conversion while
401: setting
402: .Va errno
403: to:
404: .Bl -tag -width Er
405: .It Bq Er ENOSPC
406: The destination buffer size is not large enough to perform the conversion.
407: .El
1.1 cgd 408: .Sh SEE ALSO
1.14 wiz 409: .Xr unvis 1 ,
1.3 jtc 410: .Xr vis 1 ,
1.1 cgd 411: .Xr unvis 3
1.16 christos 412: .Rs
1.20 lukem 413: .%A T. Berners-Lee
414: .%T Uniform Resource Locators (URL)
415: .%O RFC1738
1.16 christos 416: .Re
1.1 cgd 417: .Sh HISTORY
1.12 wennmach 418: The
1.24 christos 419: .Fn vis ,
420: .Fn strvis ,
1.12 wennmach 421: and
422: .Fa strvisx
423: functions first appeared in
1.9 perry 424: .Bx 4.4 .
1.12 wennmach 425: The
1.24 christos 426: .Fn svis ,
427: .Fn strsvis ,
1.12 wennmach 428: and
1.24 christos 429: .Fn strsvisx
1.13 wiz 430: functions appeared in
431: .Nx 1.5 .
1.24 christos 432: The buffer size limited versions of the functions (
433: .Fn nvis ,
434: .Fn strnvis ,
435: .Fn strnvisx ,
436: .Fn snvis ,
437: .Fn strsnvis ,
438: and
439: .Fn strsnvisx )
440: appeared in
1.25 ! wiz 441: .Nx 6.0 .
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to vis.3 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / lib / libc / gen