lib/libc/gen/vis.3

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