Annotation of src/lib/libc/gen/unvis.3, Revision 1.17
1.17 ! christos 1: .\" $NetBSD: unvis.3,v 1.16 2003/08/07 16:42:59 agc Exp $
1.5 cgd 2: .\"
3: .\" Copyright (c) 1989, 1991, 1993
4: .\" The Regents of the University of California. All rights reserved.
1.1 cgd 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.
1.16 agc 14: .\" 3. Neither the name of the University nor the names of its contributors
1.1 cgd 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: .\"
1.5 cgd 30: .\" @(#)unvis.3 8.2 (Berkeley) 12/11/93
1.1 cgd 31: .\"
1.17 ! christos 32: .Dd November 11, 2005
1.1 cgd 33: .Dt UNVIS 3
34: .Os
35: .Sh NAME
36: .Nm unvis ,
37: .Nm strunvis
38: .Nd decode a visual representation of characters
1.8 perry 39: .Sh LIBRARY
40: .Lb libc
1.1 cgd 41: .Sh SYNOPSIS
1.15 wiz 42: .In vis.h
1.9 fair 43: .Ft int
1.14 christos 44: .Fn unvis "char *cp" "int c" "int *astate" "int flag"
1.9 fair 45: .Ft int
1.14 christos 46: .Fn strunvis "char *dst" "const char *src"
47: .Ft int
48: .Fn strunvisx "char *dst" "const char *src" "int flag"
1.1 cgd 49: .Sh DESCRIPTION
50: The
1.14 christos 51: .Fn unvis ,
52: .Fn strunvis
1.1 cgd 53: and
1.14 christos 54: .Fn strunvisx
1.1 cgd 55: functions
56: are used to decode a visual representation of characters, as produced
57: by the
58: .Xr vis 3
59: function, back into
1.9 fair 60: the original form.
61: .Pp
62: The
63: .Fn unvis
64: function is called with successive characters in
65: .Ar c
66: until a valid sequence is recognized, at which time the decoded
67: character is available at the character pointed to by
1.1 cgd 68: .Ar cp .
1.9 fair 69: .Pp
70: The
71: .Fn strunvis
72: function decodes the characters pointed to by
1.1 cgd 73: .Ar src
74: into the buffer pointed to by
75: .Ar dst .
76: The
77: .Fn strunvis
1.9 fair 78: function simply copies
1.1 cgd 79: .Ar src
80: to
81: .Ar dst ,
82: decoding any escape sequences along the way,
83: and returns the number of characters placed into
84: .Ar dst ,
85: or \-1 if an
1.9 fair 86: invalid escape sequence was detected.
87: The size of
1.1 cgd 88: .Ar dst
1.9 fair 89: should be equal to the size of
1.1 cgd 90: .Ar src
1.9 fair 91: (that is, no expansion takes place during decoding).
1.1 cgd 92: .Pp
93: The
1.14 christos 94: .Fn strunvisx
95: function does the same as the
96: .Fn strunvis
97: function,
98: but it allows you to add a flag that specifies the style the string
99: .Ar src
100: is encoded with.
101: Currently, the only supported flag is
102: .Dv VIS_HTTPSTYLE .
103: .Pp
104: The
1.1 cgd 105: .Fn unvis
1.9 fair 106: function implements a state machine that can be used to decode an
107: arbitrary stream of bytes.
108: All state associated with the bytes being decoded is stored outside the
1.1 cgd 109: .Fn unvis
110: function (that is, a pointer to the state is passed in), so
1.9 fair 111: calls decoding different streams can be freely intermixed.
112: To start decoding a stream of bytes, first initialize an integer to zero.
113: Call
1.1 cgd 114: .Fn unvis
115: with each successive byte, along with a pointer
1.5 cgd 116: to this integer, and a pointer to a destination character.
1.1 cgd 117: The
1.9 fair 118: .Fn unvis
119: function has several return codes that must be handled properly.
120: They are:
1.1 cgd 121: .Bl -tag -width UNVIS_VALIDPUSH
122: .It Li \&0 (zero)
123: Another character is necessary; nothing has been recognized yet.
1.10 wiz 124: .It Dv UNVIS_VALID
1.1 cgd 125: A valid character has been recognized and is available at the location
126: pointed to by cp.
1.9 fair 127: .It Dv UNVIS_VALIDPUSH
1.1 cgd 128: A valid character has been recognized and is available at the location
129: pointed to by cp; however, the character currently passed in should
130: be passed in again.
1.9 fair 131: .It Dv UNVIS_NOCHAR
132: A valid sequence was detected, but no character was produced.
133: This return code is necessary to indicate a logical break between characters.
134: .It Dv UNVIS_SYNBAD
135: An invalid escape sequence was detected, or the decoder is in an unknown state.
136: The decoder is placed into the starting state.
1.1 cgd 137: .El
138: .Pp
139: When all bytes in the stream have been processed, call
140: .Fn unvis
141: one more time with flag set to
142: .Dv UNVIS_END
143: to extract any remaining character (the character passed in is ignored).
144: .Pp
1.14 christos 145: The
146: .Ar flag
147: argument is also used to specify the encoding style of the source.
148: If set to
149: .Dv VIS_HTTPSTYLE ,
150: .Fn unvis
151: will decode URI strings as specified in RFC 1808.
152: .Pp
1.1 cgd 153: The following code fragment illustrates a proper use of
154: .Fn unvis .
155: .Bd -literal -offset indent
156: int state = 0;
157: char out;
158:
159: while ((ch = getchar()) != EOF) {
160: again:
1.13 ross 161: switch(unvis(\*[Am]out, ch, \*[Am]state, 0)) {
1.1 cgd 162: case 0:
163: case UNVIS_NOCHAR:
164: break;
165: case UNVIS_VALID:
1.17 ! christos 166: (void)putchar(out);
1.1 cgd 167: break;
168: case UNVIS_VALIDPUSH:
1.17 ! christos 169: (void)putchar(out);
1.1 cgd 170: goto again;
171: case UNVIS_SYNBAD:
1.17 ! christos 172: errx(EXIT_FAILURE, "Bad character sequence!");
1.1 cgd 173: }
174: }
1.17 ! christos 175: if (unvis(\*[Am]out, '\e0', \*[Am]state, UNVIS_END) == UNVIS_VALID)
! 176: (void)putchar(out);
1.1 cgd 177: .Ed
178: .Sh SEE ALSO
1.11 wiz 179: .Xr unvis 1 ,
1.3 jtc 180: .Xr vis 1 ,
181: .Xr vis 3
1.14 christos 182: .Rs
183: .%A R. Fielding
184: .%T Relative Uniform Resource Locators
185: .%O RFC1808
186: .Re
1.1 cgd 187: .Sh HISTORY
188: The
1.9 fair 189: .Fn unvis
1.5 cgd 190: function
1.7 perry 191: first appeared in
192: .Bx 4.4 .
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to unvis.3 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / lib / libc / gen