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