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