contrib/libc-vis/vis.3

   1 .\"     $NetBSD: vis.3,v 1.49 2017/08/05 20:22:29 wiz Exp $
   2 .\"     $FreeBSD$
   3 .\"
   4 .\" Copyright (c) 1989, 1991, 1993
   5 .\"     The Regents of the University of California.  All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. Neither the name of the University nor the names of its contributors
  16 .\"    may be used to endorse or promote products derived from this software
  17 .\"    without specific prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .\"     @(#)vis.3       8.1 (Berkeley) 6/9/93
  32 .\"
  33 .Dd April 22, 2017
  34 .Dt VIS 3
  35 .Os
  36 .Sh NAME
  37 .Nm vis ,
  38 .Nm nvis ,
  39 .Nm strvis ,
  40 .Nm stravis ,
  41 .Nm strnvis ,
  42 .Nm strvisx ,
  43 .Nm strnvisx ,
  44 .Nm strenvisx ,
  45 .Nm svis ,
  46 .Nm snvis ,
  47 .Nm strsvis ,
  48 .Nm strsnvis ,
  49 .Nm strsvisx ,
  50 .Nm strsnvisx ,
  51 .Nm strsenvisx
  52 .Nd visually encode characters
  53 .Sh LIBRARY
  54 .Lb libc
  55 .Sh SYNOPSIS
  56 .In vis.h
  57 .Ft char *
  58 .Fn vis "char *dst" "int c" "int flag" "int nextc"
  59 .Ft char *
  60 .Fn nvis "char *dst" "size_t dlen" "int c" "int flag" "int nextc"
  61 .Ft int
  62 .Fn strvis "char *dst" "const char *src" "int flag"
  63 .Ft int
  64 .Fn stravis "char **dst" "const char *src" "int flag"
  65 .Ft int
  66 .Fn strnvis "char *dst" "size_t dlen" "const char *src" "int flag"
  67 .Ft int
  68 .Fn strvisx "char *dst" "const char *src" "size_t len" "int flag"
  69 .Ft int
  70 .Fn strnvisx "char *dst" "size_t dlen" "const char *src" "size_t len" "int flag"
  71 .Ft int
  72 .Fn strenvisx "char *dst" "size_t dlen" "const char *src" "size_t len" "int flag" "int *cerr_ptr"
  73 .Ft char *
  74 .Fn svis "char *dst" "int c" "int flag" "int nextc" "const char *extra"
  75 .Ft char *
  76 .Fn snvis "char *dst" "size_t dlen" "int c" "int flag" "int nextc" "const char *extra"
  77 .Ft int
  78 .Fn strsvis "char *dst" "const char *src" "int flag" "const char *extra"
  79 .Ft int
  80 .Fn strsnvis "char *dst" "size_t dlen" "const char *src" "int flag" "const char *extra"
  81 .Ft int
  82 .Fn strsvisx "char *dst" "const char *src" "size_t len" "int flag" "const char *extra"
  83 .Ft int
  84 .Fn strsnvisx "char *dst" "size_t dlen" "const char *src" "size_t len" "int flag" "const char *extra"
  85 .Ft int
  86 .Fn strsenvisx "char *dst" "size_t dlen" "const char *src" "size_t len" "int flag" "const char *extra" "int *cerr_ptr"
  87 .Sh DESCRIPTION
  88 The
  89 .Fn vis
  90 function
  91 copies into
  92 .Fa dst
  93 a string which represents the character
  94 .Fa c .
  95 If
  96 .Fa c
  97 needs no encoding, it is copied in unaltered.
  98 The string is null terminated, and a pointer to the end of the string is
  99 returned.
 100 The maximum length of any encoding is four
 101 bytes (not including the trailing
 102 .Dv NUL ) ;
 103 thus, when
 104 encoding a set of characters into a buffer, the size of the buffer should
 105 be four times the number of bytes encoded, plus one for the trailing
 106 .Dv NUL .
 107 The flag parameter is used for altering the default range of
 108 characters considered for encoding and for altering the visual
 109 representation.
 110 The additional character,
 111 .Fa nextc ,
 112 is only used when selecting the
 113 .Dv VIS_CSTYLE
 114 encoding format (explained below).
 115 .Pp
 116 The
 117 .Fn strvis ,
 118 .Fn stravis ,
 119 .Fn strnvis ,
 120 .Fn strvisx ,
 121 and
 122 .Fn strnvisx
 123 functions copy into
 124 .Fa dst
 125 a visual representation of
 126 the string
 127 .Fa src .
 128 The
 129 .Fn strvis
 130 and
 131 .Fn strnvis
 132 functions encode characters from
 133 .Fa src
 134 up to the
 135 first
 136 .Dv NUL .
 137 The
 138 .Fn strvisx
 139 and
 140 .Fn strnvisx
 141 functions encode exactly
 142 .Fa len
 143 characters from
 144 .Fa src
 145 (this
 146 is useful for encoding a block of data that may contain
 147 .Dv NUL Ns 's ) .
 148 Both forms
 149 .Dv NUL
 150 terminate
 151 .Fa dst .
 152 The size of
 153 .Fa dst
 154 must be four times the number
 155 of bytes encoded from
 156 .Fa src
 157 (plus one for the
 158 .Dv NUL ) .
 159 Both
 160 forms return the number of characters in
 161 .Fa dst
 162 (not including the trailing
 163 .Dv NUL ) .
 164 The
 165 .Fn stravis
 166 function allocates space dynamically to hold the string.
 167 The
 168 .Dq Nm n
 169 versions of the functions also take an additional argument
 170 .Fa dlen
 171 that indicates the length of the
 172 .Fa dst
 173 buffer.
 174 If
 175 .Fa dlen
 176 is not large enough to fit the converted string then the
 177 .Fn strnvis
 178 and
 179 .Fn strnvisx
 180 functions return \-1 and set
 181 .Va errno
 182 to
 183 .Dv ENOSPC .
 184 The
 185 .Fn strenvisx
 186 function takes an additional argument,
 187 .Fa cerr_ptr ,
 188 that is used to pass in and out a multibyte conversion error flag.
 189 This is useful when processing single characters at a time when
 190 it is possible that the locale may be set to something other
 191 than the locale of the characters in the input data.
 192 .Pp
 193 The functions
 194 .Fn svis ,
 195 .Fn snvis ,
 196 .Fn strsvis ,
 197 .Fn strsnvis ,
 198 .Fn strsvisx ,
 199 .Fn strsnvisx ,
 200 and
 201 .Fn strsenvisx
 202 correspond to
 203 .Fn vis ,
 204 .Fn nvis ,
 205 .Fn strvis ,
 206 .Fn strnvis ,
 207 .Fn strvisx ,
 208 .Fn strnvisx ,
 209 and
 210 .Fn strenvisx
 211 but have an additional argument
 212 .Fa extra ,
 213 pointing to a
 214 .Dv NUL
 215 terminated list of characters.
 216 These characters will be copied encoded or backslash-escaped into
 217 .Fa dst .
 218 These functions are useful e.g. to remove the special meaning
 219 of certain characters to shells.
 220 .Pp
 221 The encoding is a unique, invertible representation composed entirely of
 222 graphic characters; it can be decoded back into the original form using
 223 the
 224 .Xr unvis 3 ,
 225 .Xr strunvis 3
 226 or
 227 .Xr strnunvis 3
 228 functions.
 229 .Pp
 230 There are two parameters that can be controlled: the range of
 231 characters that are encoded (applies only to
 232 .Fn vis ,
 233 .Fn nvis ,
 234 .Fn strvis ,
 235 .Fn strnvis ,
 236 .Fn strvisx ,
 237 and
 238 .Fn strnvisx ) ,
 239 and the type of representation used.
 240 By default, all non-graphic characters,
 241 except space, tab, and newline are encoded (see
 242 .Xr isgraph 3 ) .
 243 The following flags
 244 alter this:
 245 .Bl -tag -width VIS_WHITEX
 246 .It Dv VIS_DQ
 247 Also encode double quotes
 248 .It Dv VIS_GLOB
 249 Also encode the magic characters
 250 .Ql ( * ,
 251 .Ql \&? ,
 252 .Ql \&[ ,
 253 and
 254 .Ql # )
 255 recognized by
 256 .Xr glob 3 .
 257 .It Dv VIS_SHELL
 258 Also encode the meta characters used by shells (in addition to the glob
 259 characters):
 260 .Ql ( ' ,
 261 .Ql ` ,
 262 .Ql \&" ,
 263 .Ql \&; ,
 264 .Ql & ,
 265 .Ql < ,
 266 .Ql > ,
 267 .Ql \&( ,
 268 .Ql \&) ,
 269 .Ql \&| ,
 270 .Ql \&] ,
 271 .Ql \e ,
 272 .Ql $ ,
 273 .Ql \&! ,
 274 .Ql \&^ ,
 275 and
 276 .Ql ~ ) .
 277 .It Dv VIS_SP
 278 Also encode space.
 279 .It Dv VIS_TAB
 280 Also encode tab.
 281 .It Dv VIS_NL
 282 Also encode newline.
 283 .It Dv VIS_WHITE
 284 Synonym for
 285 .Dv VIS_SP | VIS_TAB | VIS_NL .
 286 .It Dv VIS_META
 287 Synonym for
 288 .Dv VIS_WHITE | VIS_GLOB | VIS_SHELL .
 289 .It Dv VIS_SAFE
 290 Only encode
 291 .Dq unsafe
 292 characters.
 293 Unsafe means control characters which may cause common terminals to perform
 294 unexpected functions.
 295 Currently this form allows space, tab, newline, backspace, bell, and
 296 return \(em in addition to all graphic characters \(em unencoded.
 297 .El
 298 .Pp
 299 (The above flags have no effect for
 300 .Fn svis ,
 301 .Fn snvis ,
 302 .Fn strsvis ,
 303 .Fn strsnvis ,
 304 .Fn strsvisx ,
 305 and
 306 .Fn strsnvisx .
 307 When using these functions, place all graphic characters to be
 308 encoded in an array pointed to by
 309 .Fa extra .
 310 In general, the backslash character should be included in this array, see the
 311 warning on the use of the
 312 .Dv VIS_NOSLASH
 313 flag below).
 314 .Pp
 315 There are six forms of encoding.
 316 All forms use the backslash character
 317 .Ql \e
 318 to introduce a special
 319 sequence; two backslashes are used to represent a real backslash,
 320 except
 321 .Dv VIS_HTTPSTYLE
 322 that uses
 323 .Ql % ,
 324 or
 325 .Dv VIS_MIMESTYLE
 326 that uses
 327 .Ql = .
 328 These are the visual formats:
 329 .Bl -tag -width VIS_CSTYLE
 330 .It (default)
 331 Use an
 332 .Ql M
 333 to represent meta characters (characters with the 8th
 334 bit set), and use caret
 335 .Ql ^
 336 to represent control characters (see
 337 .Xr iscntrl 3 ) .
 338 The following formats are used:
 339 .Bl -tag -width xxxxx
 340 .It Dv \e^C
 341 Represents the control character
 342 .Ql C .
 343 Spans characters
 344 .Ql \e000
 345 through
 346 .Ql \e037 ,
 347 and
 348 .Ql \e177
 349 (as
 350 .Ql \e^? ) .
 351 .It Dv \eM-C
 352 Represents character
 353 .Ql C
 354 with the 8th bit set.
 355 Spans characters
 356 .Ql \e241
 357 through
 358 .Ql \e376 .
 359 .It Dv \eM^C
 360 Represents control character
 361 .Ql C
 362 with the 8th bit set.
 363 Spans characters
 364 .Ql \e200
 365 through
 366 .Ql \e237 ,
 367 and
 368 .Ql \e377
 369 (as
 370 .Ql \eM^? ) .
 371 .It Dv \e040
 372 Represents
 373 .Tn ASCII
 374 space.
 375 .It Dv \e240
 376 Represents Meta-space.
 377 .El
 378 .It Dv VIS_CSTYLE
 379 Use C-style backslash sequences to represent standard non-printable
 380 characters.
 381 The following sequences are used to represent the indicated characters:
 382 .Bd -unfilled -offset indent
 383 .Li \ea Tn  \(em BEL No (007)
 384 .Li \eb Tn  \(em BS No (010)
 385 .Li \ef Tn  \(em NP No (014)
 386 .Li \en Tn  \(em NL No (012)
 387 .Li \er Tn  \(em CR No (015)
 388 .Li \es Tn  \(em SP No (040)
 389 .Li \et Tn  \(em HT No (011)
 390 .Li \ev Tn  \(em VT No (013)
 391 .Li \e0 Tn  \(em NUL No (000)
 392 .Ed
 393 .Pp
 394 When using this format, the
 395 .Fa nextc
 396 parameter is looked at to determine if a
 397 .Dv NUL
 398 character can be encoded as
 399 .Ql \e0
 400 instead of
 401 .Ql \e000 .
 402 If
 403 .Fa nextc
 404 is an octal digit, the latter representation is used to
 405 avoid ambiguity.
 406 .Pp
 407 Non-printable characters without C-style
 408 backslash sequences use the default representation.
 409 .It Dv VIS_OCTAL
 410 Use a three digit octal sequence.
 411 The form is
 412 .Ql \eddd
 413 where
 414 .Em d
 415 represents an octal digit.
 416 .It Dv VIS_CSTYLE \&| Dv VIS_OCTAL
 417 Same as
 418 .Dv VIS_CSTYLE
 419 except that non-printable characters without C-style
 420 backslash sequences use a three digit octal sequence.
 421 .It Dv VIS_HTTPSTYLE
 422 Use URI encoding as described in RFC 1738.
 423 The form is
 424 .Ql %xx
 425 where
 426 .Em x
 427 represents a lower case hexadecimal digit.
 428 .It Dv VIS_MIMESTYLE
 429 Use MIME Quoted-Printable encoding as described in RFC 2045, only don't
 430 break lines and don't handle CRLF.
 431 The form is
 432 .Ql =XX
 433 where
 434 .Em X
 435 represents an upper case hexadecimal digit.
 436 .El
 437 .Pp
 438 There is one additional flag,
 439 .Dv VIS_NOSLASH ,
 440 which inhibits the
 441 doubling of backslashes and the backslash before the default
 442 format (that is, control characters are represented by
 443 .Ql ^C
 444 and
 445 meta characters as
 446 .Ql M-C ) .
 447 With this flag set, the encoding is
 448 ambiguous and non-invertible.
 449 .Sh MULTIBYTE CHARACTER SUPPORT
 450 These functions support multibyte character input.
 451 The encoding conversion is influenced by the setting of the
 452 .Ev LC_CTYPE
 453 environment variable which defines the set of characters
 454 that can be copied without encoding.
 455 .Pp
 456 If
 457 .Dv VIS_NOLOCALE
 458 is set, processing is done assuming the C locale and overriding
 459 any other environment settings.
 460 .Pp
 461 When 8-bit data is present in the input,
 462 .Ev LC_CTYPE
 463 must be set to the correct locale or to the C locale.
 464 If the locales of the data and the conversion are mismatched,
 465 multibyte character recognition may fail and encoding will be performed
 466 byte-by-byte instead.
 467 .Pp
 468 As noted above,
 469 .Fa dst
 470 must be four times the number of bytes processed from
 471 .Fa src .
 472 But note that each multibyte character can be up to
 473 .Dv MB_LEN_MAX
 474 bytes
 475 .\" (see
 476 .\" .Xr multibyte 3 )
 477 so in terms of multibyte characters,
 478 .Fa dst
 479 must be four times
 480 .Dv MB_LEN_MAX
 481 times the number of characters processed from
 482 .Fa src .
 483 .Sh ENVIRONMENT
 484 .Bl -tag -width ".Ev LC_CTYPE"
 485 .It Ev LC_CTYPE
 486 Specify the locale of the input data.
 487 Set to C if the input data locale is unknown.
 488 .El
 489 .Sh ERRORS
 490 The functions
 491 .Fn nvis
 492 and
 493 .Fn snvis
 494 will return
 495 .Dv NULL
 496 and the functions
 497 .Fn strnvis ,
 498 .Fn strnvisx ,
 499 .Fn strsnvis ,
 500 and
 501 .Fn strsnvisx ,
 502 will return \-1 when the
 503 .Fa dlen
 504 destination buffer size is not enough to perform the conversion while
 505 setting
 506 .Va errno
 507 to:
 508 .Bl -tag -width ".Bq Er ENOSPC"
 509 .It Bq Er ENOSPC
 510 The destination buffer size is not large enough to perform the conversion.
 511 .El
 512 .Sh SEE ALSO
 513 .Xr unvis 1 ,
 514 .Xr vis 1 ,
 515 .Xr glob 3 ,
 516 .\" .Xr multibyte 3 ,
 517 .Xr unvis 3
 518 .Rs
 519 .%A T. Berners-Lee
 520 .%T Uniform Resource Locators (URL)
 521 .%O "RFC 1738"
 522 .Re
 523 .Rs
 524 .%T "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies"
 525 .%O "RFC 2045"
 526 .Re
 527 .Sh HISTORY
 528 The
 529 .Fn vis ,
 530 .Fn strvis ,
 531 and
 532 .Fn strvisx
 533 functions first appeared in
 534 .Bx 4.4 .
 535 The
 536 .Fn svis ,
 537 .Fn strsvis ,
 538 and
 539 .Fn strsvisx
 540 functions appeared in
 541 .Nx 1.5
 542 and
 543 .Fx 9.2 .
 544 The buffer size limited versions of the functions
 545 .Po Fn nvis ,
 546 .Fn strnvis ,
 547 .Fn strnvisx ,
 548 .Fn snvis ,
 549 .Fn strsnvis ,
 550 and
 551 .Fn strsnvisx Pc
 552 appeared in
 553 .Nx 6.0
 554 and
 555 .Fx 9.2 .
 556 Multibyte character support was added in
 557 .Nx 7.0
 558 and
 559 .Fx 9.2 .