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