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