lib/libc/gen/vis.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 .\"     From: @(#)vis.3 8.1 (Berkeley) 6/9/93
  33 .\" $FreeBSD$
  34 .\"
  35 .Dd April 9, 2006
  36 .Dt VIS 3
  37 .Os
  38 .Sh NAME
  39 .Nm vis
  40 .Nd visually encode characters
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In vis.h
  45 .Ft char *
  46 .Fn vis "char *dst" "int c" "int flag" "int nextc"
  47 .Ft int
  48 .Fn strvis "char *dst" "const char *src" "int flag"
  49 .Ft int
  50 .Fn strvisx "char *dst" "const char *src" "size_t len" "int flag"
  51 .Sh DESCRIPTION
  52 The
  53 .Fn vis
  54 function
  55 copies into
  56 .Fa dst
  57 a string which represents the character
  58 .Fa c .
  59 If
  60 .Fa c
  61 needs no encoding, it is copied in unaltered.
  62 The string is
  63 null terminated, and a pointer to the end of the string is
  64 returned.
  65 The maximum length of any encoding is four
  66 characters (not including the trailing
  67 .Dv NUL ) ;
  68 thus, when
  69 encoding a set of characters into a buffer, the size of the buffer should
  70 be four times the number of characters encoded, plus one for the trailing
  71 .Dv NUL .
  72 The
  73 .Fa flag
  74 argument is used for altering the default range of
  75 characters considered for encoding and for altering the visual
  76 representation.
  77 The additional character,
  78 .Fa nextc ,
  79 is only used when selecting the
  80 .Dv VIS_CSTYLE
  81 encoding format (explained below).
  82 .Pp
  83 The
  84 .Fn strvis
  85 and
  86 .Fn strvisx
  87 functions copy into
  88 .Fa dst
  89 a visual representation of
  90 the string
  91 .Fa src .
  92 The
  93 .Fn strvis
  94 function encodes characters from
  95 .Fa src
  96 up to the
  97 first
  98 .Dv NUL .
  99 The
 100 .Fn strvisx
 101 function encodes exactly
 102 .Fa len
 103 characters from
 104 .Fa src
 105 (this
 106 is useful for encoding a block of data that may contain
 107 .Dv NUL Ns 's ) .
 108 Both forms
 109 .Dv NUL
 110 terminate
 111 .Fa dst .
 112 The size of
 113 .Fa dst
 114 must be four times the number
 115 of characters encoded from
 116 .Fa src
 117 (plus one for the
 118 .Dv NUL ) .
 119 Both
 120 forms return the number of characters in dst (not including
 121 the trailing
 122 .Dv NUL ) .
 123 .Pp
 124 The encoding is a unique, invertible representation composed entirely of
 125 graphic characters; it can be decoded back into the original form using
 126 the
 127 .Xr unvis 3
 128 or
 129 .Xr strunvis 3
 130 functions.
 131 .Pp
 132 There are two parameters that can be controlled: the range of
 133 characters that are encoded, and the type
 134 of representation used.
 135 By default, all non-graphic characters
 136 except space, tab, and newline are encoded.
 137 (See
 138 .Xr isgraph 3 . )
 139 The following flags
 140 alter this:
 141 .Bl -tag -width VIS_WHITEX
 142 .It Dv VIS_GLOB
 143 Also encode magic characters
 144 .Ql ( * ,
 145 .Ql \&? ,
 146 .Ql \&[
 147 and
 148 .Ql # )
 149 recognized by
 150 .Xr glob 3 .
 151 .It Dv VIS_SP
 152 Also encode space.
 153 .It Dv VIS_TAB
 154 Also encode tab.
 155 .It Dv VIS_NL
 156 Also encode newline.
 157 .It Dv VIS_WHITE
 158 Synonym for
 159 .Dv VIS_SP
 160 \&|
 161 .Dv VIS_TAB
 162 \&|
 163 .Dv VIS_NL .
 164 .It Dv VIS_SAFE
 165 Only encode "unsafe" characters.
 166 Unsafe means control
 167 characters which may cause common terminals to perform
 168 unexpected functions.
 169 Currently this form allows space,
 170 tab, newline, backspace, bell, and return - in addition
 171 to all graphic characters - unencoded.
 172 .El
 173 .Pp
 174 There are four forms of encoding.
 175 Most forms use the backslash character
 176 .Ql \e
 177 to introduce a special
 178 sequence; two backslashes are used to represent a real backslash.
 179 These are the visual formats:
 180 .Bl -tag -width VIS_HTTPSTYLE
 181 .It (default)
 182 Use an
 183 .Ql M
 184 to represent meta characters (characters with the 8th
 185 bit set), and use caret
 186 .Ql ^
 187 to represent control characters see
 188 .Pf ( Xr iscntrl 3 ) .
 189 The following formats are used:
 190 .Bl -tag -width xxxxx
 191 .It Dv \e^C
 192 Represents the control character
 193 .Ql C .
 194 Spans characters
 195 .Ql \e000
 196 through
 197 .Ql \e037 ,
 198 and
 199 .Ql \e177
 200 (as
 201 .Ql \e^? ) .
 202 .It Dv \eM-C
 203 Represents character
 204 .Ql C
 205 with the 8th bit set.
 206 Spans characters
 207 .Ql \e241
 208 through
 209 .Ql \e376 .
 210 .It Dv \eM^C
 211 Represents control character
 212 .Ql C
 213 with the 8th bit set.
 214 Spans characters
 215 .Ql \e200
 216 through
 217 .Ql \e237 ,
 218 and
 219 .Ql \e377
 220 (as
 221 .Ql \eM^? ) .
 222 .It Dv \e040
 223 Represents
 224 .Tn ASCII
 225 space.
 226 .It Dv \e240
 227 Represents Meta-space.
 228 .El
 229 .Pp
 230 .It Dv VIS_CSTYLE
 231 Use C-style backslash sequences to represent standard non-printable
 232 characters.
 233 The following sequences are used to represent the indicated characters:
 234 .Pp
 235 .Bl -tag -width ".Li \e0" -offset indent -compact
 236 .It Li \ea
 237 .Dv BEL No (007)
 238 .It Li \eb
 239 .Dv BS No (010)
 240 .It Li \ef
 241 .Dv NP No (014)
 242 .It Li \en
 243 .Dv NL No (012)
 244 .It Li \er
 245 .Dv CR No (015)
 246 .It Li \es
 247 .Dv SP No (040)
 248 .It Li \et
 249 .Dv HT No (011)
 250 .It Li \ev
 251 .Dv VT No (013)
 252 .It Li \e0
 253 .Dv NUL No (000)
 254 .El
 255 .Pp
 256 When using this format, the
 257 .Fa nextc
 258 argument is looked at to determine
 259 if a
 260 .Dv NUL
 261 character can be encoded as
 262 .Ql \e0
 263 instead of
 264 .Ql \e000 .
 265 If
 266 .Fa nextc
 267 is an octal digit, the latter representation is used to
 268 avoid ambiguity.
 269 .It Dv VIS_HTTPSTYLE
 270 Use URI encoding as described in RFC 1808.
 271 The form is
 272 .Ql %dd
 273 where
 274 .Ar d
 275 represents a hexadecimal digit.
 276 .It Dv VIS_OCTAL
 277 Use a three digit octal sequence.
 278 The form is
 279 .Ql \eddd
 280 where
 281 .Ar d
 282 represents an octal digit.
 283 .El
 284 .Pp
 285 There is one additional flag,
 286 .Dv VIS_NOSLASH ,
 287 which inhibits the
 288 doubling of backslashes and the backslash before the default
 289 format (that is, control characters are represented by
 290 .Ql ^C
 291 and
 292 meta characters as
 293 .Ql M-C ) .
 294 With this flag set, the encoding is
 295 ambiguous and non-invertible.
 296 .Sh SEE ALSO
 297 .Xr unvis 1 ,
 298 .Xr unvis 3
 299 .Rs
 300 .%A R. Fielding
 301 .%T Relative Uniform Resource Locators
 302 .%O RFC1808
 303 .Re
 304 .Sh HISTORY
 305 These functions first appeared in
 306 .Bx 4.4 .
 307 .Sh BUGS
 308 The
 309 .Nm
 310 family of functions do not recognize multibyte characters, and thus
 311 may consider them to be non-printable when they are in fact printable
 312 (and vice versa.)