1.\" $NetBSD: vis.3,v 1.26 2011/05/17 03:35:38 enami 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 March 12, 2011 33.Dt VIS 3 34.Os 35.Sh NAME 36.Nm vis , 37.Nm nvis , 38.Nm strvis , 39.Nm strnvis , 40.Nm strvisx , 41.Nm strnvisx , 42.Nm svis , 43.Nm snvis , 44.Nm strsvis , 45.Nm strsnvis , 46.Nm strsvisx 47.Nm strsnvisx 48.Nd visually encode characters 49.Sh LIBRARY 50.Lb libc 51.Sh SYNOPSIS 52.In vis.h 53.Ft char * 54.Fn vis "char *dst" "int c" "int flag" "int nextc" 55.Ft char * 56.Fn nvis "char *dst" "size_t dlen" "int c" "int flag" "int nextc" 57.Ft int 58.Fn strvis "char *dst" "const char *src" "int flag" 59.Ft int 60.Fn strnvis "char *dst" "size_t dlen" "const char *src" "int flag" 61.Ft int 62.Fn strvisx "char *dst" "const char *src" "size_t len" "int flag" 63.Ft int 64.Fn strnvisx "char *dst" "size_t dlen" "const char *src" "size_t len" "int flag" 65.Ft char * 66.Fn svis "char *dst" "int c" "int flag" "int nextc" "const char *extra" 67.Ft char * 68.Fn snvis "char *dst" "size_t dlen" "int c" "int flag" "int nextc" "const char *extra" 69.Ft int 70.Fn strsvis "char *dst" "const char *src" "int flag" "const char *extra" 71.Ft int 72.Fn strsnvis "char *dst" "size_t dlen" "const char *src" "int flag" "const char *extra" 73.Ft int 74.Fn strsvisx "char *dst" "const char *src" "size_t len" "int flag" "const char *extra" 75.Ft int 76.Fn strsnvisx "char *dst" "size_t dlen" "const char *src" "size_t len" "int flag" "const char *extra" 77.Sh DESCRIPTION 78The 79.Fn vis 80function 81copies into 82.Fa dst 83a string which represents the character 84.Fa c . 85If 86.Fa c 87needs no encoding, it is copied in unaltered. 88The string is null terminated, and a pointer to the end of the string is 89returned. 90The maximum length of any encoding is four 91characters (not including the trailing 92.Dv NUL ) ; 93thus, when 94encoding a set of characters into a buffer, the size of the buffer should 95be four times the number of characters encoded, plus one for the trailing 96.Dv NUL . 97The flag parameter is used for altering the default range of 98characters considered for encoding and for altering the visual 99representation. 100The additional character, 101.Fa nextc , 102is only used when selecting the 103.Dv VIS_CSTYLE 104encoding format (explained below). 105.Pp 106The 107.Fn strvis , 108.Fn strnvis , 109.Fn strvisx , 110and 111.Fn strnvisx 112functions copy into 113.Fa dst 114a visual representation of 115the string 116.Fa src . 117The 118.Fn strvis 119and 120.Fn strnvis 121functions encode characters from 122.Fa src 123up to the 124first 125.Dv NUL . 126The 127.Fn strvisx 128and 129.Fn strnvisx 130functions encode exactly 131.Fa len 132characters from 133.Fa src 134(this 135is useful for encoding a block of data that may contain 136.Dv NUL Ns 's ) . 137Both forms 138.Dv NUL 139terminate 140.Fa dst . 141The size of 142.Fa dst 143must be four times the number 144of characters encoded from 145.Fa src 146(plus one for the 147.Dv NUL ) . 148Both 149forms return the number of characters in dst (not including 150the trailing 151.Dv NUL ) . 152The 153.Dq n 154versions of the functions also take an additional argument 155.Fa dlen 156that indicates the length of the 157.Fa dst 158buffer. 159If 160.Fa dlen 161is not large enough to fix the converted string then the 162.Fn strnvis 163and 164.Fn strnvisx 165functions return \-1 and set 166.Va errno 167to 168.Dv ENOSPC . 169.Pp 170The functions 171.Fn svis , 172.Fn snvis , 173.Fn strsvis , 174.Fn strsnvis , 175.Fn strsvisx , 176and 177.Fn strsnvisx 178correspond to 179.Fn vis , 180.Fn nvis , 181.Fn strvis , 182.Fn strnvis , 183.Fn strvisx , 184and 185.Fn strnvisx 186but have an additional argument 187.Fa extra , 188pointing to a 189.Dv NUL 190terminated list of characters. 191These characters will be copied encoded or backslash-escaped into 192.Fa dst . 193These functions are useful e.g. to remove the special meaning 194of certain characters to shells. 195.Pp 196The encoding is a unique, invertible representation composed entirely of 197graphic characters; it can be decoded back into the original form using 198the 199.Xr unvis 3 , 200.Xr strunvis 3 201or 202.Xr strnunvis 3 203functions. 204.Pp 205There are two parameters that can be controlled: the range of 206characters that are encoded (applies only to 207.Fn vis , 208.Fn nvis , 209.Fn strvis , 210.Fn strnvis , 211.Fn strvisx , 212and 213.Fn strnvisx ) , 214and the type of representation used. 215By default, all non-graphic characters, 216except space, tab, and newline are encoded. 217(See 218.Xr isgraph 3 . ) 219The following flags 220alter this: 221.Bl -tag -width VIS_WHITEX 222.It Dv VIS_SP 223Also encode space. 224.It Dv VIS_TAB 225Also encode tab. 226.It Dv VIS_NL 227Also encode newline. 228.It Dv VIS_WHITE 229Synonym for 230.Dv VIS_SP 231\&| 232.Dv VIS_TAB 233\&| 234.Dv VIS_NL . 235.It Dv VIS_SAFE 236Only encode "unsafe" characters. 237Unsafe means control characters which may cause common terminals to perform 238unexpected functions. 239Currently this form allows space, tab, newline, backspace, bell, and 240return - in addition to all graphic characters - unencoded. 241.El 242.Pp 243(The above flags have no effect for 244.Fn svis , 245.Fn snvis , 246.Fn strsvis , 247.Fn strsnvis , 248.Fn strsvisx , 249and 250.Fn strsnvisx . 251When using these functions, place all graphic characters to be 252encoded in an array pointed to by 253.Fa extra . 254In general, the backslash character should be included in this array, see the 255warning on the use of the 256.Dv VIS_NOSLASH 257flag below). 258.Pp 259There are four forms of encoding. 260All forms use the backslash character 261.Ql \e 262to introduce a special 263sequence; two backslashes are used to represent a real backslash, 264except 265.Dv VIS_HTTPSTYLE 266that uses 267.Ql % , 268or 269.Dv VIS_MIMESTYLE 270that uses 271.Ql = . 272These are the visual formats: 273.Bl -tag -width VIS_CSTYLE 274.It (default) 275Use an 276.Ql M 277to represent meta characters (characters with the 8th 278bit set), and use caret 279.Ql ^ 280to represent control characters see 281.Pf ( Xr iscntrl 3 ) . 282The following formats are used: 283.Bl -tag -width xxxxx 284.It Dv \e^C 285Represents the control character 286.Ql C . 287Spans characters 288.Ql \e000 289through 290.Ql \e037 , 291and 292.Ql \e177 293(as 294.Ql \e^? ) . 295.It Dv \eM-C 296Represents character 297.Ql C 298with the 8th bit set. 299Spans characters 300.Ql \e241 301through 302.Ql \e376 . 303.It Dv \eM^C 304Represents control character 305.Ql C 306with the 8th bit set. 307Spans characters 308.Ql \e200 309through 310.Ql \e237 , 311and 312.Ql \e377 313(as 314.Ql \eM^? ) . 315.It Dv \e040 316Represents 317.Tn ASCII 318space. 319.It Dv \e240 320Represents Meta-space. 321.El 322.Pp 323.It Dv VIS_CSTYLE 324Use C-style backslash sequences to represent standard non-printable 325characters. 326The following sequences are used to represent the indicated characters: 327.Bd -unfilled -offset indent 328.Li \ea Tn - BEL No (007) 329.Li \eb Tn - BS No (010) 330.Li \ef Tn - NP No (014) 331.Li \en Tn - NL No (012) 332.Li \er Tn - CR No (015) 333.Li \es Tn - SP No (040) 334.Li \et Tn - HT No (011) 335.Li \ev Tn - VT No (013) 336.Li \e0 Tn - NUL No (000) 337.Ed 338.Pp 339When using this format, the nextc parameter is looked at to determine 340if a 341.Dv NUL 342character can be encoded as 343.Ql \e0 344instead of 345.Ql \e000 . 346If 347.Fa nextc 348is an octal digit, the latter representation is used to 349avoid ambiguity. 350.It Dv VIS_OCTAL 351Use a three digit octal sequence. 352The form is 353.Ql \eddd 354where 355.Em d 356represents an octal digit. 357.It Dv VIS_HTTPSTYLE 358Use URI encoding as described in RFC 1738. 359The form is 360.Ql %xx 361where 362.Em x 363represents a lower case hexadecimal digit. 364.It Dv VIS_MIMESTYLE 365Use MIME Quoted-Printable encoding as described in RFC 2045, only don't 366break lines and don't handle CRLF. 367The form is: 368.Ql %XX 369where 370.Em X 371represents an upper case hexadecimal digit. 372.El 373.Pp 374There is one additional flag, 375.Dv VIS_NOSLASH , 376which inhibits the 377doubling of backslashes and the backslash before the default 378format (that is, control characters are represented by 379.Ql ^C 380and 381meta characters as 382.Ql M-C ) . 383With this flag set, the encoding is 384ambiguous and non-invertible. 385.Sh ERRORS 386The functions 387.Fn nvis 388and 389.Fn snvis 390will return 391.Dv NULL 392and the functions 393.Fn strnvis , 394.Fn strnvisx , 395.Fn strsnvis , 396and 397.Fn strsnvisx , 398will return \-1 when the 399.Fa dlen 400destination buffer length size is not enough to perform the conversion while 401setting 402.Va errno 403to: 404.Bl -tag -width Er 405.It Bq Er ENOSPC 406The destination buffer size is not large enough to perform the conversion. 407.El 408.Sh SEE ALSO 409.Xr unvis 1 , 410.Xr vis 1 , 411.Xr unvis 3 412.Rs 413.%A T. Berners-Lee 414.%T Uniform Resource Locators (URL) 415.%O RFC1738 416.Re 417.Sh HISTORY 418The 419.Fn vis , 420.Fn strvis , 421and 422.Fa strvisx 423functions first appeared in 424.Bx 4.4 . 425The 426.Fn svis , 427.Fn strsvis , 428and 429.Fn strsvisx 430functions appeared in 431.Nx 1.5 . 432The buffer size limited versions of the functions 433.Po Fn nvis , 434.Fn strnvis , 435.Fn strnvisx , 436.Fn snvis , 437.Fn strsnvis , 438and 439.Fn strsnvisx Pc 440appeared in 441.Nx 6.0 . 442