manual/netkit/original/man3/vis.3

   1 .\"     $OpenBSD: vis.3,v 1.3 1996/08/19 08:27:34 tholo Exp $
   2 .\"
   3 .\" Copyright (c) 1989, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .Dd June 9, 1993
  35 .Dt VIS 3
  36 .Os "Linux NetKit (0.17)"
  37 .Sh NAME
  38 .Nm vis
  39 .Nd visually encode characters
  40 .Sh SYNOPSIS
  41 .Fd #include <vis.h>
  42 .Ft char *
  43 .Fn vis "char *dst" "char c" "int flag" "char nextc"
  44 .Ft int
  45 .Fn strvis "char *dst" "char *src" "int flag"
  46 .Ft int
  47 .Fn strvisx "char *dst" "char *src" "int len" "int flag"
  48 .Sh DESCRIPTION
  49 The
  50 .Fn vis
  51 function
  52 copies into
  53 .Fa dst
  54 a string which represents the character
  55 .Fa c .
  56 If
  57 .Fa c
  58 needs no encoding, it is copied in unaltered.  The string is
  59 null terminated, and a pointer to the end of the string is
  60 returned.  The maximum length of any encoding is four
  61 characters (not including the trailing
  62 .Dv NUL ) ;
  63 thus, when
  64 encoding a set of characters into a buffer, the size of the buffer should
  65 be four times the number of characters encoded, plus one for the trailing
  66 .Dv NUL .
  67 The flag parameter is used for altering the default range of
  68 characters considered for encoding and for altering the visual
  69 representation.
  70 The additional character,
  71 .Fa nextc ,
  72 is only used when selecting the
  73 .Dv VIS_CSTYLE
  74 encoding format (explained below).
  75 .Pp
  76 The
  77 .Fn strvis
  78 and
  79 .Fn strvisx
  80 functions copy into
  81 .Fa dst
  82 a visual representation of
  83 the string
  84 .Fa src .
  85 The
  86 .Fn strvis
  87 function encodes characters from
  88 .Fa src
  89 up to the
  90 first
  91 .Dv NUL .
  92 The
  93 .Fn strvisx
  94 function encodes exactly
  95 .Fa len
  96 characters from
  97 .Fa src
  98 (this
  99 is useful for encoding a block of data that may contain
 100 .Dv NUL Ns 's).
 101 Both forms
 102 .Dv NUL
 103 terminate
 104 .Fa dst .
 105 The size of
 106 .Fa dst
 107 must be four times the number
 108 of characters encoded from
 109 .Fa src
 110 (plus one for the
 111 .Dv NUL ) .
 112 Both
 113 forms return the number of characters in dst (not including
 114 the trailing
 115 .Dv NUL ) .
 116 .Pp
 117 The encoding is a unique, invertible representation composed entirely of
 118 graphic characters; it can be decoded back into the original form using
 119 the
 120 .Xr unvis 3
 121 or
 122 .Xr strunvis 3
 123 functions.
 124 .Pp
 125 There are two parameters that can be controlled: the range of
 126 characters that are encoded, and the type
 127 of representation used.
 128 By default, all non-graphic characters.
 129 except space, tab, and newline are encoded.
 130 (See
 131 .Xr isgraph 3 . )
 132 The following flags
 133 alter this:
 134 .Bl -tag -width VIS_WHITEX
 135 .It Dv VIS_SP
 136 Also encode space.
 137 .It Dv VIS_TAB
 138 Also encode tab.
 139 .It Dv VIS_NL
 140 Also encode newline.
 141 .It Dv VIS_WHITE
 142 Synonym for
 143 .Dv VIS_SP
 144 \&|
 145 .Dv VIS_TAB
 146 \&|
 147 .Dv VIS_NL .
 148 .It Dv VIS_SAFE
 149 Only encode "unsafe" characters.  Unsafe means control
 150 characters which may cause common terminals to perform
 151 unexpected functions.  Currently this form allows space,
 152 tab, newline, backspace, bell, and return - in addition
 153 to all graphic characters - unencoded.
 154 .El
 155 .Pp
 156 There are three forms of encoding.
 157 All forms use the backslash character
 158 .Ql \e
 159 to introduce a special
 160 sequence; two backslashes are used to represent a real backslash.
 161 These are the visual formats:
 162 .Bl -tag -width VIS_CSTYLE
 163 .It (default)
 164 Use an
 165 .Ql M
 166 to represent meta characters (characters with the 8th
 167 bit set), and use caret
 168 .Ql ^
 169 to represent control characters see
 170 .Pf ( Xr iscntrl 3 ) .
 171 The following formats are used:
 172 .Bl -tag -width xxxxx
 173 .It Dv \e^C
 174 Represents the control character
 175 .Ql C .
 176 Spans characters
 177 .Ql \e000
 178 through
 179 .Ql \e037 ,
 180 and
 181 .Ql \e177
 182 (as
 183 .Ql \e^? ) .
 184 .It Dv \eM-C
 185 Represents character
 186 .Ql C
 187 with the 8th bit set.
 188 Spans characters
 189 .Ql \e241
 190 through
 191 .Ql \e376 .
 192 .It Dv \eM^C
 193 Represents control character
 194 .Ql C
 195 with the 8th bit set.
 196 Spans characters
 197 .Ql \e200
 198 through
 199 .Ql \e237 ,
 200 and
 201 .Ql \e377
 202 (as
 203 .Ql \eM^? ) .
 204 .It Dv \e040
 205 Represents
 206 .Tn ASCII
 207 space.
 208 .It Dv \e240
 209 Represents Meta-space.
 210 .El
 211 .Pp
 212 .It Dv VIS_CSTYLE
 213 Use C-style backslash sequences to represent standard non-printable
 214 characters.
 215 The following sequences are used to represent the indicated characters:
 216 .Bd -unfilled -offset indent
 217 .Li \ea Tn  - BEL No (007)
 218 .Li \eb Tn  - BS No (010)
 219 .Li \ef Tn  - NP No (014)
 220 .Li \en Tn  - NL No (012)
 221 .Li \er Tn  - CR No (015)
 222 .Li \et Tn  - HT No (011)
 223 .Li \ev Tn  - VT No (013)
 224 .Li \e0 Tn  - NUL No (000)
 225 .Ed
 226 .Pp
 227 When using this format, the nextc parameter is looked at to determine
 228 if a
 229 .Dv NUL
 230 character can be encoded as
 231 .Ql \e0
 232 instead of
 233 .Ql \e000 .
 234 If
 235 .Fa nextc
 236 is an octal digit, the latter representation is used to
 237 avoid ambiguity.
 238 .It Dv VIS_OCTAL
 239 Use a three digit octal sequence.  The form is
 240 .Ql \eddd
 241 where
 242 .Em d
 243 represents an octal digit.
 244 .El
 245 .Pp
 246 There is one additional flag,
 247 .Dv VIS_NOSLASH ,
 248 which inhibits the
 249 doubling of backslashes and the backslash before the default
 250 format (that is, control characters are represented by
 251 .Ql ^C
 252 and
 253 meta characters as
 254 .Ql M-C ) .
 255 With this flag set, the encoding is
 256 ambiguous and non-invertible.
 257 .Sh SEE ALSO
 258 .Xr vis 1 ,
 259 .Xr unvis 1 ,
 260 .Xr unvis 3
 261 .Sh HISTORY
 262 These functions first appeared in 4.4BSD.