| blob | b856a730e11262195e4a621e13c0a584e3a40f5d |
1 .\" $NetBSD: unvis.3,v 1.27 2012/12/15 07:34:36 wiz 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. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)unvis.3 8.2 (Berkeley) 12/11/93
31 .\"
32 .Dd March 12, 2011
33 .Dt UNVIS 3
34 .Os
35 .Sh NAME
36 .Nm unvis ,
37 .Nm strunvis
38 .Nd decode a visual representation of characters
39 .Sh LIBRARY
40 .Lb libc
41 .Sh SYNOPSIS
42 .In vis.h
43 .Ft int
44 .Fn unvis "char *cp" "int c" "int *astate" "int flag"
45 .Ft int
46 .Fn strunvis "char *dst" "const char *src"
47 .Ft int
48 .Fn strnunvis "char *dst" "size_t dlen" "const char *src"
49 .Ft int
50 .Fn strunvisx "char *dst" "const char *src" "int flag"
51 .Ft int
52 .Fn strnunvisx "char *dst" "size_t dlen" "const char *src" "int flag"
53 .Sh DESCRIPTION
54 The
55 .Fn unvis ,
56 .Fn strunvis
57 and
58 .Fn strunvisx
59 functions
60 are used to decode a visual representation of characters, as produced
61 by the
62 .Xr vis 3
63 function, back into
64 the original form.
65 .Pp
66 The
67 .Fn unvis
68 function is called with successive characters in
69 .Ar c
70 until a valid sequence is recognized, at which time the decoded
71 character is available at the character pointed to by
72 .Ar cp .
73 .Pp
74 The
75 .Fn strunvis
76 function decodes the characters pointed to by
77 .Ar src
78 into the buffer pointed to by
79 .Ar dst .
80 The
81 .Fn strunvis
82 function simply copies
83 .Ar src
84 to
85 .Ar dst ,
86 decoding any escape sequences along the way,
87 and returns the number of characters placed into
88 .Ar dst ,
89 or \-1 if an
90 invalid escape sequence was detected.
91 The size of
92 .Ar dst
93 should be equal to the size of
94 .Ar src
95 (that is, no expansion takes place during decoding).
96 .Pp
97 The
98 .Fn strunvisx
99 function does the same as the
100 .Fn strunvis
101 function,
102 but it allows you to add a flag that specifies the style the string
103 .Ar src
104 is encoded with.
105 Currently, the supported flags are:
106 .Dv VIS_HTTPSTYLE
107 and
108 .Dv VIS_MIMESTYLE .
109 .Pp
110 The
111 .Fn unvis
112 function implements a state machine that can be used to decode an
113 arbitrary stream of bytes.
114 All state associated with the bytes being decoded is stored outside the
115 .Fn unvis
116 function (that is, a pointer to the state is passed in), so
117 calls decoding different streams can be freely intermixed.
118 To start decoding a stream of bytes, first initialize an integer to zero.
119 Call
120 .Fn unvis
121 with each successive byte, along with a pointer
122 to this integer, and a pointer to a destination character.
123 The
124 .Fn unvis
125 function has several return codes that must be handled properly.
126 They are:
127 .Bl -tag -width UNVIS_VALIDPUSH
128 .It Li \&0 No (zero)
129 Another character is necessary; nothing has been recognized yet.
130 .It Dv UNVIS_VALID
131 A valid character has been recognized and is available at the location
132 pointed to by
133 .Fa cp .
134 .It Dv UNVIS_VALIDPUSH
135 A valid character has been recognized and is available at the location
136 pointed to by
137 .Fa cp ;
138 however, the character currently passed in should be passed in again.
139 .It Dv UNVIS_NOCHAR
140 A valid sequence was detected, but no character was produced.
141 This return code is necessary to indicate a logical break between characters.
142 .It Dv UNVIS_SYNBAD
143 An invalid escape sequence was detected, or the decoder is in an unknown state.
144 The decoder is placed into the starting state.
145 .El
146 .Pp
147 When all bytes in the stream have been processed, call
148 .Fn unvis
149 one more time with flag set to
150 .Dv UNVIS_END
151 to extract any remaining character (the character passed in is ignored).
152 .Pp
153 The
154 .Fa flag
155 argument is also used to specify the encoding style of the source.
156 If set to
157 .Dv VIS_HTTPSTYLE
158 or
159 .Dv VIS_HTTP1808 ,
160 .Fn unvis
161 will decode URI strings as specified in RFC 1808.
162 If set to
163 .Dv VIS_HTTP1866 ,
164 .Fn unvis
165 will decode entity references and numeric character references
166 as specified in RFC 1866.
167 If set to
168 .Dv VIS_MIMESTYLE ,
169 .Fn unvis
170 will decode MIME Quoted-Printable strings as specified in RFC 2045.
171 If set to
172 .Dv VIS_NOESCAPE ,
173 .Fn unvis
174 will not decode
175 .Ql \e
176 quoted characters.
177 .Pp
178 The following code fragment illustrates a proper use of
179 .Fn unvis .
180 .Bd -literal -offset indent
181 int state = 0;
182 char out;
184 while ((ch = getchar()) != EOF) {
185 again:
186 switch(unvis(\*[Am]out, ch, \*[Am]state, 0)) {
187 case 0:
188 case UNVIS_NOCHAR:
189 break;
190 case UNVIS_VALID:
191 (void)putchar(out);
192 break;
193 case UNVIS_VALIDPUSH:
194 (void)putchar(out);
195 goto again;
196 case UNVIS_SYNBAD:
197 errx(EXIT_FAILURE, "Bad character sequence!");
198 }
199 }
200 if (unvis(\*[Am]out, '\e0', \*[Am]state, UNVIS_END) == UNVIS_VALID)
201 (void)putchar(out);
202 .Ed
203 .Sh ERRORS
204 The functions
205 .Fn strunvis ,
206 .Fn strnunvis ,
207 .Fn strunvisx ,
208 and
209 .Fn strnunvisx
210 will return \-1 on error and set
211 .Va errno
212 to:
213 .Bl -tag -width Er
214 .It Bq Er EINVAL
215 An invalid escape sequence was detected, or the decoder is in an unknown state.
216 .El
217 .Pp
218 In addition the functions
219 .Fn strnunvis
220 and
221 .Fn strnunvisx
222 will can also set
223 .Va errno
224 on error to:
225 .Bl -tag -width Er
226 .It Bq Er ENOSPC
227 Not enough space to perform the conversion.
228 .El
229 .Sh SEE ALSO
230 .Xr unvis 1 ,
231 .Xr vis 1 ,
232 .Xr vis 3
233 .Rs
234 .%A R. Fielding
235 .%T Relative Uniform Resource Locators
236 .%O RFC1808
237 .Re
238 .Sh HISTORY
239 The
240 .Fn unvis
241 function
242 first appeared in
243 .Bx 4.4 .
244 The
245 .Fn strnunvis
246 and
247 .Fn strnunvisx
248 functions appeared in
249 .Nx 6.0 .
250 .Sh BUGS
251 The names
252 .Dv VIS_HTTP1808
253 and
254 .Dv VIS_HTTP1866
255 are wrong.
256 Percent-encoding was defined in RFC 1738, the original RFC for URL.
257 RFC 1866 defines HTML 2.0, an application of SGML, from which it
258 inherits concepts of numeric character references and entity
259 references.