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