gen/FreeBSD/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 .\" 4. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)unvis.3     8.2 (Berkeley) 12/11/93
  29 .\" $FreeBSD: src/lib/libc/gen/unvis.3,v 1.18 2007/01/09 00:27:56 imp Exp $
  30 .\"
  31 .Dd December 11, 1993
  32 .Dt UNVIS 3
  33 .Os
  34 .Sh NAME
  35 .Nm unvis ,
  36 .Nm strunvis
  37 .Nd decode a visual representation of characters
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In vis.h
  42 .Ft int
  43 .Fn unvis "char *cp" "int c" "int *astate" "int flag"
  44 .Ft int
  45 .Fn strunvis "char *dst" "const char *src"
  46 .Ft int
  47 .Fn strunvisx "char *dst" "const char *src" "int flag"
  48 .Sh DESCRIPTION
  49 The
  50 .Fn unvis ,
  51 .Fn strunvis
  52 and
  53 .Fn strunvisx
  54 functions
  55 are used to decode a visual representation of characters, as produced
  56 by the
  57 .Xr vis 3
  58 function, back into
  59 the original form.
  60 Unvis is called with successive characters in
  61 .Fa 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 .Fa cp .
  66 Strunvis decodes the
  67 characters pointed to by
  68 .Fa src
  69 into the buffer pointed to by
  70 .Fa dst .
  71 .Pp
  72 The
  73 .Fn strunvis
  74 function
  75 simply copies
  76 .Fa src
  77 to
  78 .Fa dst ,
  79 decoding any escape sequences along the way,
  80 and returns the number of characters placed into
  81 .Fa dst ,
  82 or \-1 if an
  83 invalid escape sequence was detected.
  84 The size of
  85 .Fa dst
  86 should be
  87 equal to the size of
  88 .Fa src
  89 (that is, no expansion takes place during
  90 decoding).
  91 .Pp
  92 The
  93 .Fn strunvisx
  94 function does the same as the
  95 .Fn strunvis
  96 function,
  97 but it allows you to add a flag that specifies the style the string
  98 .Fa src
  99 is encoded with.
 100 Currently, the only supported flag is
 101 .Dv VIS_HTTPSTYLE .
 102 .Pp
 103 The
 104 .Fn unvis
 105 function
 106 implements a state machine that can be used to decode an arbitrary
 107 stream of bytes.
 108 All state associated with the bytes being decoded
 109 is stored outside the
 110 .Fn unvis
 111 function (that is, a pointer to the state is passed in), so
 112 calls decoding different streams can be freely intermixed.
 113 To
 114 start decoding a stream of bytes, first initialize an integer
 115 to zero.
 116 Call
 117 .Fn unvis
 118 with each successive byte, along with a pointer
 119 to this integer, and a pointer to a destination character.
 120 The
 121 .Fn unvis
 122 function
 123 has several return codes that must be handled properly.
 124 They are:
 125 .Bl -tag -width UNVIS_VALIDPUSH
 126 .It Li \&0 (zero)
 127 Another character is necessary; nothing has been recognized yet.
 128 .It Dv UNVIS_VALID
 129 A valid character has been recognized and is available at the location
 130 pointed to by cp.
 131 .It Dv UNVIS_VALIDPUSH
 132 A valid character has been recognized and is available at the location
 133 pointed to by cp; however, the character currently passed in should
 134 be passed in again.
 135 .It Dv UNVIS_NOCHAR
 136 A valid sequence was detected, but no character was produced.
 137 This
 138 return code is necessary to indicate a logical break between characters.
 139 .It Dv UNVIS_SYNBAD
 140 An invalid escape sequence was detected, or the decoder is in an
 141 unknown state.
 142 The decoder is placed into the starting state.
 143 .El
 144 .Pp
 145 When all bytes in the stream have been processed, call
 146 .Fn unvis
 147 one more time with
 148 .Fa flag
 149 set to
 150 .Dv UNVIS_END
 151 to extract any remaining character (the character passed in is ignored).
 152 .Pp
 153 The
 154 .Fa flag
 155 argument is also used to specify the encoding style of the source.
 156 If set to
 157 .Dv VIS_HTTPSTYLE ,
 158 .Fn unvis
 159 will decode URI strings as specified in RFC 1808.
 160 .Pp
 161 The following code fragment illustrates a proper use of
 162 .Fn unvis .
 163 .Bd -literal -offset indent
 164 int state = 0;
 165 char out;
 166
 167 while ((ch = getchar()) != EOF) {
 168 again:
 169         switch(unvis(&out, ch, &state, 0)) {
 170         case 0:
 171         case UNVIS_NOCHAR:
 172                 break;
 173         case UNVIS_VALID:
 174                 (void) putchar(out);
 175                 break;
 176         case UNVIS_VALIDPUSH:
 177                 (void) putchar(out);
 178                 goto again;
 179         case UNVIS_SYNBAD:
 180                 (void)fprintf(stderr, "bad sequence!\en");
 181         exit(1);
 182         }
 183 }
 184 if (unvis(&out, (char)0, &state, UNVIS_END) == UNVIS_VALID)
 185         (void) putchar(out);
 186 .Ed
 187 .Sh SEE ALSO
 188 .Xr vis 1 ,
 189 .Xr vis 3
 190 .Rs
 191 .%A R. Fielding
 192 .%T Relative Uniform Resource Locators
 193 .%O RFC1808
 194 .Re
 195 .Sh HISTORY
 196 The
 197 .Fn unvis
 198 function
 199 first appeared in
 200 .Bx 4.4 .