xref: /dragonfly/lib/libc/gen/unvis.3 (revision 25a2db75) 
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.\" 4. Neither the name of the University nor the names of its contributors
13.\"    may be used to endorse or promote products derived from this software
14.\"    without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\"     @(#)unvis.3	8.2 (Berkeley) 12/11/93
29.\" $FreeBSD: src/lib/libc/gen/unvis.3,v 1.18 2007/01/09 00:27:56 imp Exp $
30.\" $DragonFly: src/lib/libc/gen/unvis.3,v 1.2 2003/06/17 04:26:42 dillon Exp $
31.\"
32.Dd April 23, 2009
33.Dt UNVIS 3
34.Os
35.Sh NAME
36.Nm unvis ,
37.Nm strunvis ,
38.Nm strunvisx
39.Nd decode a visual representation of characters
40.Sh LIBRARY
41.Lb libc
42.Sh SYNOPSIS
43.In vis.h
44.Ft int
45.Fn unvis "char *cp" "int c" "int *astate" "int flag"
46.Ft int
47.Fn strunvis "char *dst" "const char *src"
48.Ft int
49.Fn strunvisx "char *dst" "const char *src" "int flag"
50.Sh DESCRIPTION
51The
52.Fn unvis ,
53.Fn strunvis
54and
55.Fn strunvisx
56functions
57are used to decode a visual representation of characters, as produced
58by the
59.Xr vis 3
60function, back into
61the original form.
62Unvis is called with successive characters in
63.Fa c
64until a valid
65sequence is recognized, at which time the decoded character is
66available at the character pointed to by
67.Fa cp .
68Strunvis decodes the
69characters pointed to by
70.Fa src
71into the buffer pointed to by
72.Fa dst .
73.Pp
74The
75.Fn strunvis
76function
77simply copies
78.Fa src
79to
80.Fa dst ,
81decoding any escape sequences along the way,
82and returns the number of characters placed into
83.Fa dst ,
84or \-1 if an
85invalid escape sequence was detected.
86The size of
87.Fa dst
88should be
89equal to the size of
90.Fa src
91(that is, no expansion takes place during
92decoding).
93.Pp
94The
95.Fn strunvisx
96function does the same as the
97.Fn strunvis
98function,
99but it allows you to add a flag that specifies the style the string
100.Fa src
101is encoded with.
102Currently, the only supported flag is
103.Dv VIS_HTTPSTYLE .
104.Pp
105The
106.Fn unvis
107function
108implements a state machine that can be used to decode an arbitrary
109stream of bytes.
110All state associated with the bytes being decoded
111is stored outside the
112.Fn unvis
113function (that is, a pointer to the state is passed in), so
114calls decoding different streams can be freely intermixed.
115To
116start decoding a stream of bytes, first initialize an integer
117to zero.
118Call
119.Fn unvis
120with each successive byte, along with a pointer
121to this integer, and a pointer to a destination character.
122The
123.Fn unvis
124function
125has several return codes that must be handled properly.
126They are:
127.Bl -tag -width ".Dv UNVIS_VALIDPUSH"
128.It Li \&0 (zero)
129Another character is necessary; nothing has been recognized yet.
130.It Dv UNVIS_VALID
131A valid character has been recognized and is available at the location
132pointed to by cp.
133.It Dv UNVIS_VALIDPUSH
134A valid character has been recognized and is available at the location
135pointed to by cp; however, the character currently passed in should
136be passed in again.
137.It Dv UNVIS_NOCHAR
138A valid sequence was detected, but no character was produced.
139This
140return code is necessary to indicate a logical break between characters.
141.It Dv UNVIS_SYNBAD
142An invalid escape sequence was detected, or the decoder is in an
143unknown state.
144The decoder is placed into the starting state.
145.El
146.Pp
147When all bytes in the stream have been processed, call
148.Fn unvis
149one more time with
150.Fa flag
151set to
152.Dv UNVIS_END
153to extract any remaining character (the character passed in is ignored).
154.Pp
155The
156.Fa flag
157argument is also used to specify the encoding style of the source.
158If set to
159.Dv VIS_HTTPSTYLE ,
160.Fn unvis
161will decode URI strings as specified in RFC 1808.
162.Pp
163The following code fragment illustrates a proper use of
164.Fn unvis .
165.Bd -literal -offset indent
166int state = 0;
167char out;
168
169while ((ch = getchar()) != EOF) {
170again:
171	switch(unvis(&out, ch, &state, 0)) {
172	case 0:
173	case UNVIS_NOCHAR:
174		break;
175	case UNVIS_VALID:
176		(void) putchar(out);
177		break;
178	case UNVIS_VALIDPUSH:
179		(void) putchar(out);
180		goto again;
181	case UNVIS_SYNBAD:
182		(void)fprintf(stderr, "bad sequence!\en");
183	exit(1);
184	}
185}
186if (unvis(&out, (char)0, &state, UNVIS_END) == UNVIS_VALID)
187	(void) putchar(out);
188.Ed
189.Sh SEE ALSO
190.Xr vis 1 ,
191.Xr vis 3
192.Rs
193.%A R. Fielding
194.%T Relative Uniform Resource Locators
195.%O RFC 1808
196.Re
197.Sh HISTORY
198The
199.Fn unvis
200function
201first appeared in
202.Bx 4.4 .
203