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