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