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 flag parameter is used for altering the default range of
 107 characters considered for encoding and for altering the visual
 108 representation.
 109 The additional character,
 110 .Fa nextc ,
 111 is only used when selecting the
 112 .Dv VIS_CSTYLE
 113 encoding format (explained below).
 114 .Pp
 115 The
 116 .Fn strvis ,
 117 .Fn stravis ,
 118 .Fn strnvis ,
 119 .Fn strvisx ,
 120 and
 121 .Fn strnvisx
 122 functions copy into
 123 .Fa dst
 124 a visual representation of
 125 the string
 126 .Fa src .
 127 The
 128 .Fn strvis
 129 and
 130 .Fn strnvis
 131 functions encode characters from
 132 .Fa src
 133 up to the
 134 first
 135 .Dv NUL .
 136 The
 137 .Fn strvisx
 138 and
 139 .Fn strnvisx
 140 functions encode exactly
 141 .Fa len
 142 characters from
 143 .Fa src
 144 (this
 145 is useful for encoding a block of data that may contain
 146 .Dv NUL Ns 's ) .
 147 Both forms
 148 .Dv NUL
 149 terminate
 150 .Fa dst .
 151 The size of
 152 .Fa dst
 153 must be four times the number
 154 of bytes encoded from
 155 .Fa src
 156 (plus one for the
 157 .Dv NUL ) .
 158 Both
 159 forms return the number of characters in
 160 .Fa dst
 161 (not including the trailing
 162 .Dv NUL ) .
 163 The
 164 .Fn stravis
 165 function allocates space dynamically to hold the string.
 166 The
 167 .Dq Nm n
 168 versions of the functions also take an additional argument
 169 .Fa dlen
 170 that indicates the length of the
 171 .Fa dst
 172 buffer.
 173 If
 174 .Fa dlen
 175 is not large enough to fit the converted string then the
 176 .Fn strnvis
 177 and
 178 .Fn strnvisx
 179 functions return \-1 and set
 180 .Va errno
 181 to
 182 .Dv ENOSPC .
 183 The
 184 .Fn strenvisx
 185 function takes an additional argument,
 186 .Fa cerr_ptr ,
 187 that is used to pass in and out a multibyte conversion error flag.
 188 This is useful when processing single characters at a time when
 189 it is possible that the locale may be set to something other
 190 than the locale of the characters in the input data.
 191 .Pp
 192 The functions
 193 .Fn svis ,
 194 .Fn snvis ,
 195 .Fn strsvis ,
 196 .Fn strsnvis ,
 197 .Fn strsvisx ,
 198 .Fn strsnvisx ,
 199 and
 200 .Fn strsenvisx
 201 correspond to
 202 .Fn vis ,
 203 .Fn nvis ,
 204 .Fn strvis ,
 205 .Fn strnvis ,
 206 .Fn strvisx ,
 207 .Fn strnvisx ,
 208 and
 209 .Fn strenvisx
 210 but have an additional argument
 211 .Fa extra ,
 212 pointing to a
 213 .Dv NUL
 214 terminated list of characters.
 215 These characters will be copied encoded or backslash-escaped into
 216 .Fa dst .
 217 These functions are useful e.g. to remove the special meaning
 218 of certain characters to shells.
 219 .Pp
 220 The encoding is a unique, invertible representation composed entirely of
 221 graphic characters; it can be decoded back into the original form using
 222 the
 223 .Xr unvis 3 ,
 224 .Xr strunvis 3
 225 or
 226 .Xr strnunvis 3
 227 functions.
 228 .Pp
 229 There are two parameters that can be controlled: the range of
 230 characters that are encoded (applies only to
 231 .Fn vis ,
 232 .Fn nvis ,
 233 .Fn strvis ,
 234 .Fn strnvis ,
 235 .Fn strvisx ,
 236 and
 237 .Fn strnvisx ) ,
 238 and the type of representation used.
 239 By default, all non-graphic characters,
 240 except space, tab, and newline are encoded (see
 241 .Xr isgraph 3 ) .
 242 The following flags
 243 alter this:
 244 .Bl -tag -width VIS_WHITEX
 245 .It Dv VIS_DQ
 246 Also encode double quotes
 247 .It Dv VIS_GLOB
 248 Also encode the magic characters
 249 .Ql ( * ,
 250 .Ql \&? ,
 251 .Ql \&[ ,
 252 and
 253 .Ql # )
 254 recognized by
 255 .Xr glob 3 .
 256 .It Dv VIS_SHELL
 257 Also encode the meta characters used by shells (in addition to the glob
 258 characters):
 259 .Ql ( ' ,
 260 .Ql ` ,
 261 .Ql \&" ,
 262 .Ql \&; ,
 263 .Ql & ,
 264 .Ql < ,
 265 .Ql > ,
 266 .Ql \&( ,
 267 .Ql \&) ,
 268 .Ql \&| ,
 269 .Ql \&] ,
 270 .Ql \e ,
 271 .Ql $ ,
 272 .Ql \&! ,
 273 .Ql \&^ ,
 274 and
 275 .Ql ~ ) .
 276 .It Dv VIS_SP
 277 Also encode space.
 278 .It Dv VIS_TAB
 279 Also encode tab.
 280 .It Dv VIS_NL
 281 Also encode newline.
 282 .It Dv VIS_WHITE
 283 Synonym for
 284 .Dv VIS_SP | VIS_TAB | VIS_NL .
 285 .It Dv VIS_META
 286 Synonym for
 287 .Dv VIS_WHITE | VIS_GLOB | VIS_SHELL .
 288 .It Dv VIS_SAFE
 289 Only encode
 290 .Dq unsafe
 291 characters.
 292 Unsafe means control characters which may cause common terminals to perform
 293 unexpected functions.
 294 Currently this form allows space, tab, newline, backspace, bell, and
 295 return \(em in addition to all graphic characters \(em unencoded.
 296 .El
 297 .Pp
 298 (The above flags have no effect for
 299 .Fn svis ,
 300 .Fn snvis ,
 301 .Fn strsvis ,
 302 .Fn strsnvis ,
 303 .Fn strsvisx ,
 304 and
 305 .Fn strsnvisx .
 306 When using these functions, place all graphic characters to be
 307 encoded in an array pointed to by
 308 .Fa extra .
 309 In general, the backslash character should be included in this array, see the
 310 warning on the use of the
 311 .Dv VIS_NOSLASH
 312 flag below).
 313 .Pp
 314 There are six forms of encoding.
 315 All forms use the backslash character
 316 .Ql \e
 317 to introduce a special
 318 sequence; two backslashes are used to represent a real backslash,
 319 except
 320 .Dv VIS_HTTPSTYLE
 321 that uses
 322 .Ql % ,
 323 or
 324 .Dv VIS_MIMESTYLE
 325 that uses
 326 .Ql = .
 327 These are the visual formats:
 328 .Bl -tag -width VIS_CSTYLE
 329 .It (default)
 330 Use an
 331 .Ql M
 332 to represent meta characters (characters with the 8th
 333 bit set), and use caret
 334 .Ql ^
 335 to represent control characters (see
 336 .Xr iscntrl 3 ) .
 337 The following formats are used:
 338 .Bl -tag -width xxxxx
 339 .It Dv \e^C
 340 Represents the control character
 341 .Ql C .
 342 Spans characters
 343 .Ql \e000
 344 through
 345 .Ql \e037 ,
 346 and
 347 .Ql \e177
 348 (as
 349 .Ql \e^? ) .
 350 .It Dv \eM-C
 351 Represents character
 352 .Ql C
 353 with the 8th bit set.
 354 Spans characters
 355 .Ql \e241
 356 through
 357 .Ql \e376 .
 358 .It Dv \eM^C
 359 Represents control character
 360 .Ql C
 361 with the 8th bit set.
 362 Spans characters
 363 .Ql \e200
 364 through
 365 .Ql \e237 ,
 366 and
 367 .Ql \e377
 368 (as
 369 .Ql \eM^? ) .
 370 .It Dv \e040
 371 Represents
 372 .Tn ASCII
 373 space.
 374 .It Dv \e240
 375 Represents Meta-space.
 376 .El
 377 .It Dv VIS_CSTYLE
 378 Use C-style backslash sequences to represent standard non-printable
 379 characters.
 380 The following sequences are used to represent the indicated characters:
 381 .Bd -unfilled -offset indent
 382 .Li \ea Tn  \(em BEL No (007)
 383 .Li \eb Tn  \(em BS No (010)
 384 .Li \ef Tn  \(em NP No (014)
 385 .Li \en Tn  \(em NL No (012)
 386 .Li \er Tn  \(em CR No (015)
 387 .Li \es Tn  \(em SP No (040)
 388 .Li \et Tn  \(em HT No (011)
 389 .Li \ev Tn  \(em VT No (013)
 390 .Li \e0 Tn  \(em NUL No (000)
 391 .Ed
 392 .Pp
 393 When using this format, the
 394 .Fa nextc
 395 parameter is looked at to determine if a
 396 .Dv NUL
 397 character can be encoded as
 398 .Ql \e0
 399 instead of
 400 .Ql \e000 .
 401 If
 402 .Fa nextc
 403 is an octal digit, the latter representation is used to
 404 avoid ambiguity.
 405 .Pp
 406 Non-printable characters without C-style
 407 backslash sequences use the default representation.
 408 .It Dv VIS_OCTAL
 409 Use a three digit octal sequence.
 410 The form is
 411 .Ql \eddd
 412 where
 413 .Em d
 414 represents an octal digit.
 415 .It Dv VIS_CSTYLE \&| Dv VIS_OCTAL
 416 Same as
 417 .Dv VIS_CSTYLE
 418 except that non-printable characters without C-style
 419 backslash sequences use a three digit octal sequence.
 420 .It Dv VIS_HTTPSTYLE
 421 Use URI encoding as described in RFC 1738.
 422 The form is
 423 .Ql %xx
 424 where
 425 .Em x
 426 represents a lower case hexadecimal digit.
 427 .It Dv VIS_MIMESTYLE
 428 Use MIME Quoted-Printable encoding as described in RFC 2045, only don't
 429 break lines and don't handle CRLF.
 430 The form is
 431 .Ql =XX
 432 where
 433 .Em X
 434 represents an upper case hexadecimal digit.
 435 .El
 436 .Pp
 437 There is one additional flag,
 438 .Dv VIS_NOSLASH ,
 439 which inhibits the
 440 doubling of backslashes and the backslash before the default
 441 format (that is, control characters are represented by
 442 .Ql ^C
 443 and
 444 meta characters as
 445 .Ql M-C ) .
 446 With this flag set, the encoding is
 447 ambiguous and non-invertible.
 448 .Sh MULTIBYTE CHARACTER SUPPORT
 449 These functions support multibyte character input.
 450 The encoding conversion is influenced by the setting of the
 451 .Ev LC_CTYPE
 452 environment variable which defines the set of characters
 453 that can be copied without encoding.
 454 .Pp
 455 If
 456 .Dv VIS_NOLOCALE
 457 is set, processing is done assuming the C locale and overriding
 458 any other environment settings.
 459 .Pp
 460 When 8-bit data is present in the input,
 461 .Ev LC_CTYPE
 462 must be set to the correct locale or to the C locale.
 463 If the locales of the data and the conversion are mismatched,
 464 multibyte character recognition may fail and encoding will be performed
 465 byte-by-byte instead.
 466 .Pp
 467 As noted above,
 468 .Fa dst
 469 must be four times the number of bytes processed from
 470 .Fa src .
 471 But note that each multibyte character can be up to
 472 .Dv MB_LEN_MAX
 473 bytes
 474 .\" (see
 475 .\" .Xr multibyte 3 )
 476 so in terms of multibyte characters,
 477 .Fa dst
 478 must be four times
 479 .Dv MB_LEN_MAX
 480 times the number of characters processed from
 481 .Fa src .
 482 .Sh ENVIRONMENT
 483 .Bl -tag -width ".Ev LC_CTYPE"
 484 .It Ev LC_CTYPE
 485 Specify the locale of the input data.
 486 Set to C if the input data locale is unknown.
 487 .El
 488 .Sh ERRORS
 489 The functions
 490 .Fn nvis
 491 and
 492 .Fn snvis
 493 will return
 494 .Dv NULL
 495 and the functions
 496 .Fn strnvis ,
 497 .Fn strnvisx ,
 498 .Fn strsnvis ,
 499 and
 500 .Fn strsnvisx ,
 501 will return \-1 when the
 502 .Fa dlen
 503 destination buffer size is not enough to perform the conversion while
 504 setting
 505 .Va errno
 506 to:
 507 .Bl -tag -width ".Bq Er ENOSPC"
 508 .It Bq Er ENOSPC
 509 The destination buffer size is not large enough to perform the conversion.
 510 .El
 511 .Sh SEE ALSO
 512 .Xr unvis 1 ,
 513 .Xr vis 1 ,
 514 .Xr glob 3 ,
 515 .\" .Xr multibyte 3 ,
 516 .Xr unvis 3
 517 .Rs
 518 .%A T. Berners-Lee
 519 .%T Uniform Resource Locators (URL)
 520 .%O "RFC 1738"
 521 .Re
 522 .Rs
 523 .%T "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies"
 524 .%O "RFC 2045"
 525 .Re
 526 .Sh HISTORY
 527 The
 528 .Fn vis ,
 529 .Fn strvis ,
 530 and
 531 .Fn strvisx
 532 functions first appeared in
 533 .Bx 4.4 .
 534 The
 535 .Fn svis ,
 536 .Fn strsvis ,
 537 and
 538 .Fn strsvisx
 539 functions appeared in
 540 .Nx 1.5 .
 541 The buffer size limited versions of the functions
 542 .Po Fn nvis ,
 543 .Fn strnvis ,
 544 .Fn strnvisx ,
 545 .Fn snvis ,
 546 .Fn strsnvis ,
 547 and
 548 .Fn strsnvisx Pc
 549 appeared in
 550 .Nx 6.0
 551 and
 552 .Fx 9.2 .
 553 Multibyte character support was added in
 554 .Nx 7.0
 555 and
 556 .Fx 9.2 .