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