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