xref: /dragonfly/lib/libc/gen/vis.3 (revision 62f7f702) 
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.5 2007/11/23 23:16:36 swildner 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
55The
56.Fn vis
57function
58copies into
59.Fa dst
60a string which represents the character
61.Fa c .
62If
63.Fa c
64needs no encoding, it is copied in unaltered.
65The string is
66null terminated, and a pointer to the end of the string is
67returned.
68The maximum length of any encoding is four
69characters (not including the trailing
70.Dv NUL ) ;
71thus, when
72encoding a set of characters into a buffer, the size of the buffer should
73be four times the number of characters encoded, plus one for the trailing
74.Dv NUL .
75The
76.Fa flag
77argument is used for altering the default range of
78characters considered for encoding and for altering the visual
79representation.
80The additional character,
81.Fa nextc ,
82is only used when selecting the
83.Dv VIS_CSTYLE
84encoding format (explained below).
85.Pp
86The
87.Fn strvis ,
88.Fn strnvis
89and
90.Fn strvisx
91functions copy into
92.Fa dst
93a visual representation of
94the string
95.Fa src .
96The
97.Fn strvis
98function encodes characters from
99.Fa src
100up to the
101first
102.Dv NUL .
103The
104.Fn strnvis
105function works like
106.Fn strvis ,
107but writes at most
108.Fa len - 1
109characters to
110.Fa dst
111and terminates the string with
112.Dv NUL .
113The
114.Fn strvisx
115function encodes exactly
116.Fa len
117characters from
118.Fa src
119(this
120is useful for encoding a block of data that may contain
121.Dv NUL Ns 's ) .
122Both forms
123.Dv NUL
124terminate
125.Fa dst .
126The size of
127.Fa dst
128must be four times the number
129of characters encoded from
130.Fa src
131(plus one for the
132.Dv NUL ) .
133Both
134forms return the number of characters in dst (not including
135the trailing
136.Dv NUL ) .
137.Pp
138The encoding is a unique, invertible representation composed entirely of
139graphic characters; it can be decoded back into the original form using
140the
141.Xr unvis 3
142or
143.Xr strunvis 3
144functions.
145.Pp
146There are two parameters that can be controlled: the range of
147characters that are encoded, and the type
148of representation used.
149By default, all non-graphic characters
150except space, tab, and newline are encoded.
151(See
152.Xr isgraph 3 . )
153The following flags
154alter this:
155.Bl -tag -width VIS_WHITEX
156.It Dv VIS_GLOB
157Also encode magic characters
158.Ql ( * ,
159.Ql \&? ,
160.Ql \&[
161and
162.Ql # )
163recognized by
164.Xr glob 3 .
165.It Dv VIS_SP
166Also encode space.
167.It Dv VIS_TAB
168Also encode tab.
169.It Dv VIS_NL
170Also encode newline.
171.It Dv VIS_WHITE
172Synonym for
173.Dv VIS_SP
174\&|
175.Dv VIS_TAB
176\&|
177.Dv VIS_NL .
178.It Dv VIS_SAFE
179Only encode "unsafe" characters.
180Unsafe means control
181characters which may cause common terminals to perform
182unexpected functions.
183Currently this form allows space,
184tab, newline, backspace, bell, and return - in addition
185to all graphic characters - unencoded.
186.El
187.Pp
188There are four forms of encoding.
189Most forms use the backslash character
190.Ql \e
191to introduce a special
192sequence; two backslashes are used to represent a real backslash.
193These are the visual formats:
194.Bl -tag -width VIS_HTTPSTYLE
195.It (default)
196Use an
197.Ql M
198to represent meta characters (characters with the 8th
199bit set), and use caret
200.Ql ^
201to represent control characters see
202.Pf ( Xr iscntrl 3 ) .
203The following formats are used:
204.Bl -tag -width xxxxx
205.It Dv \e^C
206Represents the control character
207.Ql C .
208Spans characters
209.Ql \e000
210through
211.Ql \e037 ,
212and
213.Ql \e177
214(as
215.Ql \e^? ) .
216.It Dv \eM-C
217Represents character
218.Ql C
219with the 8th bit set.
220Spans characters
221.Ql \e241
222through
223.Ql \e376 .
224.It Dv \eM^C
225Represents control character
226.Ql C
227with the 8th bit set.
228Spans characters
229.Ql \e200
230through
231.Ql \e237 ,
232and
233.Ql \e377
234(as
235.Ql \eM^? ) .
236.It Dv \e040
237Represents
238.Tn ASCII
239space.
240.It Dv \e240
241Represents Meta-space.
242.El
243.Pp
244.It Dv VIS_CSTYLE
245Use C-style backslash sequences to represent standard non-printable
246characters.
247The 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
268When using this format, the
269.Fa nextc
270argument is looked at to determine
271if a
272.Dv NUL
273character can be encoded as
274.Ql \e0
275instead of
276.Ql \e000 .
277If
278.Fa nextc
279is an octal digit, the latter representation is used to
280avoid ambiguity.
281.It Dv VIS_HTTPSTYLE
282Use URI encoding as described in RFC 1808.
283The form is
284.Ql %dd
285where
286.Ar d
287represents a hexadecimal digit.
288.It Dv VIS_OCTAL
289Use a three digit octal sequence.
290The form is
291.Ql \eddd
292where
293.Ar d
294represents an octal digit.
295.El
296.Pp
297There is one additional flag,
298.Dv VIS_NOSLASH ,
299which inhibits the
300doubling of backslashes and the backslash before the default
301format (that is, control characters are represented by
302.Ql ^C
303and
304meta characters as
305.Ql M-C ) .
306With this flag set, the encoding is
307ambiguous 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 RFC 1808
315.Re
316.Sh HISTORY
317These functions first appeared in
318.Bx 4.4 .
319.Sh BUGS
320The
321.Nm
322family of functions do not recognize multibyte characters, and thus
323may consider them to be non-printable when they are in fact printable
324(and vice versa.)
325