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