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