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.14 2001/10/01 16:08: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 .Ft int
  51 .Fn strunvisx "char *dst" "const char *src" "int flag"
  52 .Sh DESCRIPTION
  53 The
  54 .Fn unvis ,
  55 .Fn strunvis
  56 and
  57 .Fn strunvisx
  58 functions
  59 are used to decode a visual representation of characters, as produced
  60 by the
  61 .Xr vis 3
  62 function, back into
  63 the original form.  Unvis is called with successive characters in
  64 .Ar c
  65 until a valid
  66 sequence is recognized, at which time the decoded character is
  67 available at the character pointed to by
  68 .Ar cp .
  69 Strunvis decodes the
  70 characters pointed to by
  71 .Ar src
  72 into the buffer pointed to by
  73 .Ar dst .
  74 .Pp
  75 The
  76 .Fn strunvis
  77 function
  78 simply copies
  79 .Ar src
  80 to
  81 .Ar dst ,
  82 decoding any escape sequences along the way,
  83 and returns the number of characters placed into
  84 .Ar dst ,
  85 or \-1 if an
  86 invalid escape sequence was detected.  The size of
  87 .Ar dst
  88 should be
  89 equal to the size of
  90 .Ar src
  91 (that is, no expansion takes place during
  92 decoding).
  93 .Pp
  94 The
  95 .Fn strunvisx
  96 function does the same as the
  97 .Fn strunvis
  98 function,
  99 but it allows you to add a flag that specifies the style the string
 100 .Ar src
 101 is encoded with.
 102 Currently, the only supported flag is
 103 .Dv VIS_HTTPSTYLE .
 104 .Pp
 105 The
 106 .Fn unvis
 107 function
 108 implements a state machine that can be used to decode an arbitrary
 109 stream of bytes.  All state associated with the bytes being decoded
 110 is stored outside the
 111 .Fn unvis
 112 function (that is, a pointer to the state is passed in), so
 113 calls decoding different streams can be freely intermixed.  To
 114 start decoding a stream of bytes, first initialize an integer
 115 to zero.  Call
 116 .Fn unvis
 117 with each successive byte, along with a pointer
 118 to this integer, and a pointer to a destination character.
 119 The
 120 .Fn unvis
 121 function
 122 has several return codes that must be handled properly.  They are:
 123 .Bl -tag -width UNVIS_VALIDPUSH
 124 .It Li \&0 (zero)
 125 Another character is necessary; nothing has been recognized yet.
 126 .It Dv  UNVIS_VALID
 127 A valid character has been recognized and is available at the location
 128 pointed to by cp.
 129 .It Dv  UNVIS_VALIDPUSH
 130 A valid character has been recognized and is available at the location
 131 pointed to by cp; however, the character currently passed in should
 132 be passed in again.
 133 .It Dv  UNVIS_NOCHAR
 134 A valid sequence was detected, but no character was produced.  This
 135 return code is necessary to indicate a logical break between characters.
 136 .It Dv  UNVIS_SYNBAD
 137 An invalid escape sequence was detected, or the decoder is in an
 138 unknown state.  The decoder is placed into the starting state.
 139 .El
 140 .Pp
 141 When all bytes in the stream have been processed, call
 142 .Fn unvis
 143 one more time with
 144 .Ar flag
 145 set to
 146 .Dv UNVIS_END
 147 to extract any remaining character (the character passed in is ignored).
 148 .Pp
 149 The
 150 .Ar flag
 151 argument is also used to specify the encoding style of the source.
 152 If set to
 153 .Dv VIS_HTTPSTYLE ,
 154 .Fn unvis
 155 will decode URI strings as specified in RFC 1808.
 156 .Pp
 157 The following code fragment illustrates a proper use of
 158 .Fn unvis .
 159 .Bd -literal -offset indent
 160 int state = 0;
 161 char out;
 162
 163 while ((ch = getchar()) != EOF) {
 164 again:
 165         switch(unvis(&out, ch, &state, 0)) {
 166         case 0:
 167         case UNVIS_NOCHAR:
 168                 break;
 169         case UNVIS_VALID:
 170                 (void) putchar(out);
 171                 break;
 172         case UNVIS_VALIDPUSH:
 173                 (void) putchar(out);
 174                 goto again;
 175         case UNVIS_SYNBAD:
 176                 (void)fprintf(stderr, "bad sequence!\en");
 177         exit(1);
 178         }
 179 }
 180 if (unvis(&out, (char)0, &state, UNVIS_END) == UNVIS_VALID)
 181         (void) putchar(out);
 182 .Ed
 183 .Sh SEE ALSO
 184 .Xr vis 1 ,
 185 .Xr vis 3
 186 .Rs
 187 .%A R. Fielding
 188 .%T Relative Uniform Resource Locators
 189 .%O RFC1808
 190 .Re
 191 .Sh HISTORY
 192 The
 193 .Fn unvis
 194 function
 195 first appeared in
 196 .Bx 4.4 .