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