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