[apple/libc.git] / gen / FreeBSD / vis.3

.\" Copyright (c) 1989, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     From: @(#)vis.3	8.1 (Berkeley) 6/9/93
.\" $FreeBSD: src/lib/libc/gen/vis.3,v 1.20 2002/12/19 09:40:21 ru Exp $
.\"
.Dd July 25, 1996
.Dt VIS 3
.Os
.Sh NAME
.Nm vis
.Nd visually encode characters
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In vis.h
.Ft char *
.Fn vis "char *dst" "int c" "int flag" "int nextc"
.Ft int
.Fn strvis "char *dst" "const char *src" "int flag"
.Ft int
.Fn strvisx "char *dst" "const char *src" "size_t len" "int flag"
.Sh DESCRIPTION
The
.Fn vis
function
copies into
.Fa dst
a string which represents the character
.Fa c .
If
.Fa c
needs no encoding, it is copied in unaltered.  The string is
null terminated, and a pointer to the end of the string is
returned.  The maximum length of any encoding is four
characters (not including the trailing
.Dv NUL ) ;
thus, when
encoding a set of characters into a buffer, the size of the buffer should
be four times the number of characters encoded, plus one for the trailing
.Dv NUL .
The
.Fa flag
argument is used for altering the default range of
characters considered for encoding and for altering the visual
representation.
The additional character,
.Fa nextc ,
is only used when selecting the
.Dv VIS_CSTYLE
encoding format (explained below).
.Pp
The
.Fn strvis
and
.Fn strvisx
functions copy into
.Fa dst
a visual representation of
the string
.Fa src .
The
.Fn strvis
function encodes characters from
.Fa src
up to the
first
.Dv NUL .
The
.Fn strvisx
function encodes exactly
.Fa len
characters from
.Fa src
(this
is useful for encoding a block of data that may contain
.Dv NUL Ns 's ) .
Both forms
.Dv NUL
terminate
.Fa dst .
The size of
.Fa dst
must be four times the number
of characters encoded from
.Fa src
(plus one for the
.Dv NUL ) .
Both
forms return the number of characters in dst (not including
the trailing
.Dv NUL ) .
.Pp
The encoding is a unique, invertible representation composed entirely of
graphic characters; it can be decoded back into the original form using
the
.Xr unvis 3
or
.Xr strunvis 3
functions.
.Pp
There are two parameters that can be controlled: the range of
characters that are encoded, and the type
of representation used.
By default, all non-graphic characters
except space, tab, and newline are encoded.
(See
.Xr isgraph 3 . )
The following flags
alter this:
.Bl -tag -width VIS_WHITEX
.It Dv VIS_SP
Also encode space.
.It Dv VIS_TAB
Also encode tab.
.It Dv VIS_NL
Also encode newline.
.It Dv VIS_WHITE
Synonym for
.Dv VIS_SP
\&|
.Dv VIS_TAB
\&|
.Dv VIS_NL .
.It Dv VIS_SAFE
Only encode "unsafe" characters.  Unsafe means control
characters which may cause common terminals to perform
unexpected functions.  Currently this form allows space,
tab, newline, backspace, bell, and return - in addition
to all graphic characters - unencoded.
.El
.Pp
There are four forms of encoding.
Most forms use the backslash character
.Ql \e
to introduce a special
sequence; two backslashes are used to represent a real backslash.
These are the visual formats:
.Bl -tag -width VIS_HTTPSTYLE
.It (default)
Use an
.Ql M
to represent meta characters (characters with the 8th
bit set), and use carat
.Ql ^
to represent control characters see
.Pf ( Xr iscntrl 3 ) .
The following formats are used:
.Bl -tag -width xxxxx
.It Dv \e^C
Represents the control character
.Ql C .
Spans characters
.Ql \e000
through
.Ql \e037 ,
and
.Ql \e177
(as
.Ql \e^? ) .
.It Dv \eM-C
Represents character
.Ql C
with the 8th bit set.
Spans characters
.Ql \e241
through
.Ql \e376 .
.It Dv \eM^C
Represents control character
.Ql C
with the 8th bit set.
Spans characters
.Ql \e200
through
.Ql \e237 ,
and
.Ql \e377
(as
.Ql \eM^? ) .
.It Dv \e040
Represents
.Tn ASCII
space.
.It Dv \e240
Represents Meta-space.
.El
.Pp
.It Dv VIS_CSTYLE
Use C-style backslash sequences to represent standard non-printable
characters.
The following sequences are used to represent the indicated characters:
.Bd -unfilled -offset indent
.Li \ea Tn  - BEL No (007)
.Li \eb Tn  - BS No (010)
.Li \ef Tn  - NP No (014)
.Li \en Tn  - NL No (012)
.Li \er Tn  - CR No (015)
.Li \et Tn  - HT No (011)
.Li \ev Tn  - VT No (013)
.Li \e0 Tn  - NUL No (000)
.Ed
.Pp
When using this format, the
.Fa nextc
argument is looked at to determine
if a
.Dv NUL
character can be encoded as
.Ql \e0
instead of
.Ql \e000 .
If
.Fa nextc
is an octal digit, the latter representation is used to
avoid ambiguity.
.It Dv VIS_HTTPSTYLE
Use URI encoding as described in RFC 1808.
The form is
.Ql %dd
where
.Ar d
represents a hexadecimal digit.
.It Dv VIS_OCTAL
Use a three digit octal sequence.  The form is
.Ql \eddd
where
.Ar d
represents an octal digit.
.El
.Pp
There is one additional flag,
.Dv VIS_NOSLASH ,
which inhibits the
doubling of backslashes and the backslash before the default
format (that is, control characters are represented by
.Ql ^C
and
meta characters as
.Ql M-C ) .
With this flag set, the encoding is
ambiguous and non-invertible.
.Sh SEE ALSO
.Xr unvis 1 ,
.Xr unvis 3
.Rs
.%A R. Fielding
.%T Relative Uniform Resource Locators
.%O RFC1808
.Re
.Sh HISTORY
These functions first appeared in
.Bx 4.4 .
Commit	Line	Data
5b2abdfb A	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
9385eb3d	33	.\" $FreeBSD: src/lib/libc/gen/vis.3,v 1.20 2002/12/19 09:40:21 ru Exp $
5b2abdfb A	34	.\"
	35	.Dd July 25, 1996
	36	.Dt VIS 3
	37	.Os
	38	.Sh NAME
	39	.Nm vis
	40	.Nd visually encode characters
	41	.Sh LIBRARY
	42	.Lb libc
	43	.Sh SYNOPSIS
	44	.In vis.h
	45	.Ft char *
	46	.Fn vis "char *dst" "int c" "int flag" "int nextc"
	47	.Ft int
	48	.Fn strvis "char dst" "const char src" "int flag"
	49	.Ft int
	50	.Fn strvisx "char dst" "const char src" "size_t len" "int flag"
	51	.Sh DESCRIPTION
	52	The
	53	.Fn vis
	54	function
	55	copies into
	56	.Fa dst
	57	a string which represents the character
	58	.Fa c .
	59	If
	60	.Fa c
	61	needs no encoding, it is copied in unaltered. The string is
	62	null terminated, and a pointer to the end of the string is
	63	returned. The maximum length of any encoding is four
	64	characters (not including the trailing
	65	.Dv NUL ) ;
	66	thus, when
	67	encoding a set of characters into a buffer, the size of the buffer should
	68	be four times the number of characters encoded, plus one for the trailing
	69	.Dv NUL .
9385eb3d A	70	The
	71	.Fa flag
	72	argument is used for altering the default range of
5b2abdfb A	73	characters considered for encoding and for altering the visual
	74	representation.
	75	The additional character,
	76	.Fa nextc ,
	77	is only used when selecting the
	78	.Dv VIS_CSTYLE
	79	encoding format (explained below).
	80	.Pp
	81	The
	82	.Fn strvis
	83	and
	84	.Fn strvisx
	85	functions copy into
	86	.Fa dst
	87	a visual representation of
	88	the string
	89	.Fa src .
	90	The
	91	.Fn strvis
	92	function encodes characters from
	93	.Fa src
	94	up to the
	95	first
	96	.Dv NUL .
	97	The
	98	.Fn strvisx
	99	function encodes exactly
	100	.Fa len
	101	characters from
	102	.Fa src
	103	(this
	104	is useful for encoding a block of data that may contain
	105	.Dv NUL Ns 's ) .
	106	Both forms
	107	.Dv NUL
	108	terminate
	109	.Fa dst .
	110	The size of
	111	.Fa dst
	112	must be four times the number
	113	of characters encoded from
	114	.Fa src
	115	(plus one for the
	116	.Dv NUL ) .
	117	Both
	118	forms return the number of characters in dst (not including
	119	the trailing
	120	.Dv NUL ) .
	121	.Pp
	122	The encoding is a unique, invertible representation composed entirely of
	123	graphic characters; it can be decoded back into the original form using
	124	the
	125	.Xr unvis 3
	126	or
	127	.Xr strunvis 3
	128	functions.
	129	.Pp
	130	There are two parameters that can be controlled: the range of
	131	characters that are encoded, and the type
	132	of representation used.
	133	By default, all non-graphic characters
	134	except space, tab, and newline are encoded.
	135	(See
	136	.Xr isgraph 3 . )
137	The following flags
138	alter this:
139	.Bl -tag -width VIS_WHITEX
140	.It Dv VIS_SP
141	Also encode space.
142	.It Dv VIS_TAB
143	Also encode tab.
144	.It Dv VIS_NL
145	Also encode newline.
146	.It Dv VIS_WHITE
147	Synonym for
148	.Dv VIS_SP
149	\&\|
150	.Dv VIS_TAB
151	\&\|
152	.Dv VIS_NL .
153	.It Dv VIS_SAFE
154	Only encode "unsafe" characters. Unsafe means control
155	characters which may cause common terminals to perform
156	unexpected functions. Currently this form allows space,
157	tab, newline, backspace, bell, and return - in addition
158	to all graphic characters - unencoded.
159	.El
160	.Pp
161	There are four forms of encoding.
162	Most forms use the backslash character
163	.Ql \e
164	to introduce a special
165	sequence; two backslashes are used to represent a real backslash.
166	These are the visual formats:
167	.Bl -tag -width VIS_HTTPSTYLE
168	.It (default)
169	Use an
170	.Ql M
171	to represent meta characters (characters with the 8th
172	bit set), and use carat
173	.Ql ^
174	to represent control characters see
175	.Pf ( Xr iscntrl 3 ) .
176	The following formats are used:
177	.Bl -tag -width xxxxx
178	.It Dv \e^C
179	Represents the control character
180	.Ql C .
181	Spans characters
182	.Ql \e000
183	through
184	.Ql \e037 ,
185	and
186	.Ql \e177
187	(as
188	.Ql \e^? ) .
189	.It Dv \eM-C
190	Represents character
191	.Ql C
192	with the 8th bit set.
193	Spans characters
194	.Ql \e241
195	through
196	.Ql \e376 .
197	.It Dv \eM^C
198	Represents control character
199	.Ql C
200	with the 8th bit set.
201	Spans characters
202	.Ql \e200
203	through
204	.Ql \e237 ,
205	and
206	.Ql \e377
207	(as
208	.Ql \eM^? ) .
209	.It Dv \e040
210	Represents
211	.Tn ASCII
212	space.
213	.It Dv \e240
214	Represents Meta-space.
215	.El
216	.Pp
217	.It Dv VIS_CSTYLE
218	Use C-style backslash sequences to represent standard non-printable
219	characters.
220	The following sequences are used to represent the indicated characters:
221	.Bd -unfilled -offset indent
222	.Li \ea Tn - BEL No (007)
223	.Li \eb Tn - BS No (010)
224	.Li \ef Tn - NP No (014)
225	.Li \en Tn - NL No (012)
226	.Li \er Tn - CR No (015)
227	.Li \et Tn - HT No (011)
228	.Li \ev Tn - VT No (013)
229	.Li \e0 Tn - NUL No (000)
230	.Ed
231	.Pp
9385eb3d A	232	When using this format, the
	233	.Fa nextc
	234	argument is looked at to determine
5b2abdfb A	235	if a
	236	.Dv NUL
	237	character can be encoded as
	238	.Ql \e0
	239	instead of
	240	.Ql \e000 .
	241	If
	242	.Fa nextc
	243	is an octal digit, the latter representation is used to
	244	avoid ambiguity.
	245	.It Dv VIS_HTTPSTYLE
	246	Use URI encoding as described in RFC 1808.
	247	The form is
	248	.Ql %dd
	249	where
9385eb3d	250	.Ar d
5b2abdfb A	251	represents a hexadecimal digit.
	252	.It Dv VIS_OCTAL
	253	Use a three digit octal sequence. The form is
	254	.Ql \eddd
	255	where
9385eb3d	256	.Ar d
5b2abdfb A	257	represents an octal digit.
	258	.El
	259	.Pp
	260	There is one additional flag,
	261	.Dv VIS_NOSLASH ,
	262	which inhibits the
	263	doubling of backslashes and the backslash before the default
	264	format (that is, control characters are represented by
	265	.Ql ^C
	266	and
	267	meta characters as
	268	.Ql M-C ) .
	269	With this flag set, the encoding is
	270	ambiguous and non-invertible.
	271	.Sh SEE ALSO
	272	.Xr unvis 1 ,
	273	.Xr unvis 3
	274	.Rs
	275	.%A R. Fielding
	276	.%T Relative Uniform Resource Locators
	277	.%O RFC1808
	278	.Re
	279	.Sh HISTORY
	280	These functions first appeared in
	281	.Bx 4.4 .