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. 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 .\" $DragonFly: src/lib/libc/gen/unvis.3,v 1.2 2003/06/17 04:26:42 dillon Exp $
  31 .\"
  32 .Dd April 23, 2009
  33 .Dt UNVIS 3
  34 .Os
  35 .Sh NAME
  36 .Nm unvis ,
  37 .Nm strunvis ,
  38 .Nm strunvisx
  39 .Nd decode a visual representation of characters
  40 .Sh LIBRARY
  41 .Lb libc
  42 .Sh SYNOPSIS
  43 .In 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 .Ft int
  49 .Fn strunvisx "char *dst" "const char *src" "int flag"
  50 .Sh DESCRIPTION
  51 The
  52 .Fn unvis ,
  53 .Fn strunvis
  54 and
  55 .Fn strunvisx
  56 functions
  57 are used to decode a visual representation of characters, as produced
  58 by the
  59 .Xr vis 3
  60 function, back into
  61 the original form.
  62 Unvis is called with successive characters in
  63 .Fa c
  64 until a valid
  65 sequence is recognized, at which time the decoded character is
  66 available at the character pointed to by
  67 .Fa cp .
  68 Strunvis decodes the
  69 characters pointed to by
  70 .Fa src
  71 into the buffer pointed to by
  72 .Fa dst .
  73 .Pp
  74 The
  75 .Fn strunvis
  76 function
  77 simply copies
  78 .Fa src
  79 to
  80 .Fa dst ,
  81 decoding any escape sequences along the way,
  82 and returns the number of characters placed into
  83 .Fa dst ,
  84 or \-1 if an
  85 invalid escape sequence was detected.
  86 The size of
  87 .Fa dst
  88 should be
  89 equal to the size of
  90 .Fa 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 .Fa 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.
 110 All state associated with the bytes being decoded
 111 is stored outside the
 112 .Fn unvis
 113 function (that is, a pointer to the state is passed in), so
 114 calls decoding different streams can be freely intermixed.
 115 To
 116 start decoding a stream of bytes, first initialize an integer
 117 to zero.
 118 Call
 119 .Fn unvis
 120 with each successive byte, along with a pointer
 121 to this integer, and a pointer to a destination character.
 122 The
 123 .Fn unvis
 124 function
 125 has several return codes that must be handled properly.
 126 They are:
 127 .Bl -tag -width ".Dv UNVIS_VALIDPUSH"
 128 .It Li \&0 (zero)
 129 Another character is necessary; nothing has been recognized yet.
 130 .It Dv UNVIS_VALID
 131 A valid character has been recognized and is available at the location
 132 pointed to by cp.
 133 .It Dv UNVIS_VALIDPUSH
 134 A valid character has been recognized and is available at the location
 135 pointed to by cp; however, the character currently passed in should
 136 be passed in again.
 137 .It Dv UNVIS_NOCHAR
 138 A valid sequence was detected, but no character was produced.
 139 This
 140 return code is necessary to indicate a logical break between characters.
 141 .It Dv UNVIS_SYNBAD
 142 An invalid escape sequence was detected, or the decoder is in an
 143 unknown state.
 144 The decoder is placed into the starting state.
 145 .El
 146 .Pp
 147 When all bytes in the stream have been processed, call
 148 .Fn unvis
 149 one more time with
 150 .Fa flag
 151 set to
 152 .Dv UNVIS_END
 153 to extract any remaining character (the character passed in is ignored).
 154 .Pp
 155 The
 156 .Fa flag
 157 argument is also used to specify the encoding style of the source.
 158 If set to
 159 .Dv VIS_HTTPSTYLE ,
 160 .Fn unvis
 161 will decode URI strings as specified in RFC 1808.
 162 .Pp
 163 The following code fragment illustrates a proper use of
 164 .Fn unvis .
 165 .Bd -literal -offset indent
 166 int state = 0;
 167 char out;
 168
 169 while ((ch = getchar()) != EOF) {
 170 again:
 171         switch(unvis(&out, ch, &state, 0)) {
 172         case 0:
 173         case UNVIS_NOCHAR:
 174                 break;
 175         case UNVIS_VALID:
 176                 (void) putchar(out);
 177                 break;
 178         case UNVIS_VALIDPUSH:
 179                 (void) putchar(out);
 180                 goto again;
 181         case UNVIS_SYNBAD:
 182                 (void)fprintf(stderr, "bad sequence!\en");
 183         exit(1);
 184         }
 185 }
 186 if (unvis(&out, (char)0, &state, UNVIS_END) == UNVIS_VALID)
 187         (void) putchar(out);
 188 .Ed
 189 .Sh SEE ALSO
 190 .Xr vis 1 ,
 191 .Xr vis 3
 192 .Rs
 193 .%A R. Fielding
 194 .%T Relative Uniform Resource Locators
 195 .%O RFC 1808
 196 .Re
 197 .Sh HISTORY
 198 The
 199 .Fn unvis
 200 function
 201 first appeared in
 202 .Bx 4.4 .