xref: /dragonfly/lib/libc/gen/vis.3 (revision 2cd2d2b5) 
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.8.2.6 2001/12/14 18:33:51 ru Exp $
34.\" $DragonFly: src/lib/libc/gen/vis.3,v 1.2 2003/06/17 04:26:42 dillon Exp $
35.\"
36.Dd July 25, 1996
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 strvisx "char *dst" "const char *src" "size_t len" "int flag"
52.Sh DESCRIPTION
53The
54.Fn vis
55function
56copies into
57.Fa dst
58a string which represents the character
59.Fa c .
60If
61.Fa c
62needs no encoding, it is copied in unaltered.  The string is
63null terminated, and a pointer to the end of the string is
64returned.  The maximum length of any encoding is four
65characters (not including the trailing
66.Dv NUL ) ;
67thus, when
68encoding a set of characters into a buffer, the size of the buffer should
69be four times the number of characters encoded, plus one for the trailing
70.Dv NUL .
71The flag parameter is used for altering the default range of
72characters considered for encoding and for altering the visual
73representation.
74The additional character,
75.Fa nextc ,
76is only used when selecting the
77.Dv VIS_CSTYLE
78encoding format (explained below).
79.Pp
80The
81.Fn strvis
82and
83.Fn strvisx
84functions copy into
85.Fa dst
86a visual representation of
87the string
88.Fa src .
89The
90.Fn strvis
91function encodes characters from
92.Fa src
93up to the
94first
95.Dv NUL .
96The
97.Fn strvisx
98function encodes exactly
99.Fa len
100characters from
101.Fa src
102(this
103is useful for encoding a block of data that may contain
104.Dv NUL Ns 's ) .
105Both forms
106.Dv NUL
107terminate
108.Fa dst .
109The size of
110.Fa dst
111must be four times the number
112of characters encoded from
113.Fa src
114(plus one for the
115.Dv NUL ) .
116Both
117forms return the number of characters in dst (not including
118the trailing
119.Dv NUL ) .
120.Pp
121The encoding is a unique, invertible representation composed entirely of
122graphic characters; it can be decoded back into the original form using
123the
124.Xr unvis 3
125or
126.Xr strunvis 3
127functions.
128.Pp
129There are two parameters that can be controlled: the range of
130characters that are encoded, and the type
131of representation used.
132By default, all non-graphic characters
133except space, tab, and newline are encoded.
134(See
135.Xr isgraph 3 . )
136The following flags
137alter this:
138.Bl -tag -width VIS_WHITEX
139.It Dv VIS_SP
140Also encode space.
141.It Dv VIS_TAB
142Also encode tab.
143.It Dv VIS_NL
144Also encode newline.
145.It Dv VIS_WHITE
146Synonym for
147.Dv VIS_SP
148\&|
149.Dv VIS_TAB
150\&|
151.Dv VIS_NL .
152.It Dv VIS_SAFE
153Only encode "unsafe" characters.  Unsafe means control
154characters which may cause common terminals to perform
155unexpected functions.  Currently this form allows space,
156tab, newline, backspace, bell, and return - in addition
157to all graphic characters - unencoded.
158.El
159.Pp
160There are four forms of encoding.
161Most forms use the backslash character
162.Ql \e
163to introduce a special
164sequence; two backslashes are used to represent a real backslash.
165These are the visual formats:
166.Bl -tag -width VIS_HTTPSTYLE
167.It (default)
168Use an
169.Ql M
170to represent meta characters (characters with the 8th
171bit set), and use carat
172.Ql ^
173to represent control characters see
174.Pf ( Xr iscntrl 3 ) .
175The following formats are used:
176.Bl -tag -width xxxxx
177.It Dv \e^C
178Represents the control character
179.Ql C .
180Spans characters
181.Ql \e000
182through
183.Ql \e037 ,
184and
185.Ql \e177
186(as
187.Ql \e^? ) .
188.It Dv \eM-C
189Represents character
190.Ql C
191with the 8th bit set.
192Spans characters
193.Ql \e241
194through
195.Ql \e376 .
196.It Dv \eM^C
197Represents control character
198.Ql C
199with the 8th bit set.
200Spans characters
201.Ql \e200
202through
203.Ql \e237 ,
204and
205.Ql \e377
206(as
207.Ql \eM^? ) .
208.It Dv \e040
209Represents
210.Tn ASCII
211space.
212.It Dv \e240
213Represents Meta-space.
214.El
215.Pp
216.It Dv VIS_CSTYLE
217Use C-style backslash sequences to represent standard non-printable
218characters.
219The following sequences are used to represent the indicated characters:
220.Bd -unfilled -offset indent
221.Li \ea Tn  - BEL No (007)
222.Li \eb Tn  - BS No (010)
223.Li \ef Tn  - NP No (014)
224.Li \en Tn  - NL No (012)
225.Li \er Tn  - CR No (015)
226.Li \et Tn  - HT No (011)
227.Li \ev Tn  - VT No (013)
228.Li \e0 Tn  - NUL No (000)
229.Ed
230.Pp
231When using this format, the nextc parameter is looked at to determine
232if a
233.Dv NUL
234character can be encoded as
235.Ql \e0
236instead of
237.Ql \e000 .
238If
239.Fa nextc
240is an octal digit, the latter representation is used to
241avoid ambiguity.
242.It Dv VIS_HTTPSTYLE
243Use URI encoding as described in RFC 1808.
244The form is
245.Ql %dd
246where
247.Em d
248represents a hexadecimal digit.
249.It Dv VIS_OCTAL
250Use a three digit octal sequence.  The form is
251.Ql \eddd
252where
253.Em d
254represents an octal digit.
255.El
256.Pp
257There is one additional flag,
258.Dv VIS_NOSLASH ,
259which inhibits the
260doubling of backslashes and the backslash before the default
261format (that is, control characters are represented by
262.Ql ^C
263and
264meta characters as
265.Ql M-C ) .
266With this flag set, the encoding is
267ambiguous and non-invertible.
268.Sh SEE ALSO
269.Xr unvis 1 ,
270.Xr unvis 3
271.Rs
272.%A R. Fielding
273.%T Relative Uniform Resource Locators
274.%O RFC1808
275.Re
276.Sh HISTORY
277These functions first appeared in
278.Bx 4.4 .
279