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.\" @(#)unvis.3 8.2 (Berkeley) 12/11/93 33.\" $FreeBSD: src/lib/libc/gen/unvis.3,v 1.6.2.5 2001/12/14 18:33:51 ru Exp $ 34.\" $DragonFly: src/lib/libc/gen/unvis.3,v 1.2 2003/06/17 04:26:42 dillon Exp $ 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.In vis.h 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.Sh DESCRIPTION 52The 53.Fn unvis 54and 55.Fn strunvis 56functions 57are used to decode a visual representation of characters, as produced 58by the 59.Xr vis 3 60function, back into 61the original form. Unvis is called with successive characters in 62.Ar c 63until a valid 64sequence is recognized, at which time the decoded character is 65available at the character pointed to by 66.Ar cp . 67Strunvis decodes the 68characters pointed to by 69.Ar src 70into the buffer pointed to by 71.Ar dst . 72.Pp 73The 74.Fn strunvis 75function 76simply copies 77.Ar src 78to 79.Ar dst , 80decoding any escape sequences along the way, 81and returns the number of characters placed into 82.Ar dst , 83or \-1 if an 84invalid escape sequence was detected. The size of 85.Ar dst 86should be 87equal to the size of 88.Ar src 89(that is, no expansion takes place during 90decoding). 91.Pp 92The 93.Fn unvis 94function 95implements a state machine that can be used to decode an arbitrary 96stream of bytes. All state associated with the bytes being decoded 97is stored outside the 98.Fn unvis 99function (that is, a pointer to the state is passed in), so 100calls decoding different streams can be freely intermixed. To 101start decoding a stream of bytes, first initialize an integer 102to zero. Call 103.Fn unvis 104with each successive byte, along with a pointer 105to this integer, and a pointer to a destination character. 106The 107.Fn unvis 108function 109has several return codes that must be handled properly. They are: 110.Bl -tag -width UNVIS_VALIDPUSH 111.It Li \&0 (zero) 112Another character is necessary; nothing has been recognized yet. 113.It Dv UNVIS_VALID 114A valid character has been recognized and is available at the location 115pointed to by cp. 116.It Dv UNVIS_VALIDPUSH 117A valid character has been recognized and is available at the location 118pointed to by cp; however, the character currently passed in should 119be passed in again. 120.It Dv UNVIS_NOCHAR 121A valid sequence was detected, but no character was produced. This 122return code is necessary to indicate a logical break between characters. 123.It Dv UNVIS_SYNBAD 124An invalid escape sequence was detected, or the decoder is in an 125unknown state. The decoder is placed into the starting state. 126.El 127.Pp 128When all bytes in the stream have been processed, call 129.Fn unvis 130one more time with 131.Ar flag 132set to 133.Dv UNVIS_END 134to extract any remaining character (the character passed in is ignored). 135.Pp 136The following code fragment illustrates a proper use of 137.Fn unvis . 138.Bd -literal -offset indent 139int state = 0; 140char out; 141 142while ((ch = getchar()) != EOF) { 143again: 144 switch(unvis(&out, ch, &state, 0)) { 145 case 0: 146 case UNVIS_NOCHAR: 147 break; 148 case UNVIS_VALID: 149 (void) putchar(out); 150 break; 151 case UNVIS_VALIDPUSH: 152 (void) putchar(out); 153 goto again; 154 case UNVIS_SYNBAD: 155 (void)fprintf(stderr, "bad sequence!\en"); 156 exit(1); 157 } 158} 159if (unvis(&out, (char)0, &state, UNVIS_END) == UNVIS_VALID) 160 (void) putchar(out); 161.Ed 162.Sh SEE ALSO 163.Xr vis 1 164.Sh HISTORY 165The 166.Fn unvis 167function 168first appeared in 169.Bx 4.4 . 170