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