lib/libc/gen/unvis.3

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