1.\" $NetBSD: vis.3,v 1.16 2002/03/23 17:38:27 christos 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. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)vis.3 8.1 (Berkeley) 6/9/93 35.\" 36.Dd June 9, 1993 37.Dt VIS 3 38.Os 39.Sh NAME 40.Nm vis , 41.Nm strvis , 42.Nm strvisx , 43.Nm svis , 44.Nm strsvis , 45.Nm strsvisx 46.Nd visually encode characters 47.Sh LIBRARY 48.Lb libc 49.Sh SYNOPSIS 50.Fd #include \*[Lt]vis.h\*[Gt] 51.Ft char * 52.Fn vis "char *dst" "int c" "int flag" "int nextc" 53.Ft int 54.Fn strvis "char *dst" "const char *src" "int flag" 55.Ft int 56.Fn strvisx "char *dst" "const char *src" "size_t len" "int flag" 57.Ft char * 58.Fn svis "char *dst" "int c" "int flag" "int nextc" "const char *extra" 59.Ft int 60.Fn strsvis "char *dst" "const char *src" "int flag" "const char *extra" 61.Ft int 62.Fn strsvisx "char *dst" "const char *src" "size_t len" "int flag" "const char *extra" 63.Sh DESCRIPTION 64The 65.Fn vis 66function 67copies into 68.Fa dst 69a string which represents the character 70.Fa c . 71If 72.Fa c 73needs no encoding, it is copied in unaltered. The string is 74null terminated, and a pointer to the end of the string is 75returned. The maximum length of any encoding is four 76characters (not including the trailing 77.Dv NUL ) ; 78thus, when 79encoding a set of characters into a buffer, the size of the buffer should 80be four times the number of characters encoded, plus one for the trailing 81.Dv NUL . 82The flag parameter is used for altering the default range of 83characters considered for encoding and for altering the visual 84representation. 85The additional character, 86.Fa nextc , 87is only used when selecting the 88.Dv VIS_CSTYLE 89encoding format (explained below). 90.Pp 91The 92.Fn strvis 93and 94.Fn strvisx 95functions copy into 96.Fa dst 97a visual representation of 98the string 99.Fa src . 100The 101.Fn strvis 102function encodes characters from 103.Fa src 104up to the 105first 106.Dv NUL . 107The 108.Fn strvisx 109function encodes exactly 110.Fa len 111characters from 112.Fa src 113(this 114is useful for encoding a block of data that may contain 115.Dv NUL Ns 's ) . 116Both forms 117.Dv NUL 118terminate 119.Fa dst . 120The size of 121.Fa dst 122must be four times the number 123of characters encoded from 124.Fa src 125(plus one for the 126.Dv NUL ) . 127Both 128forms return the number of characters in dst (not including 129the trailing 130.Dv NUL ) . 131.Pp 132The functions 133.Fn svis , 134.Fn strsvis , 135and 136.Fn strsvisx 137correspond to 138.Fn vis , 139.Fn strvis , 140and 141.Fn strvisx 142but have an additional argument 143.Fa extra , 144pointing to a 145.Dv NUL 146terminated list of characters. These characters will be copied encoded or 147backslash-escaped into 148.Fa dst . 149These functions are useful e. g. to remove the special meaning 150of certain characters to shells. 151.Pp 152The encoding is a unique, invertible representation composed entirely of 153graphic characters; it can be decoded back into the original form using 154the 155.Xr unvis 3 156or 157.Xr strunvis 3 158functions. 159.Pp 160There are two parameters that can be controlled: the range of 161characters that are encoded (applies only to 162.Fn vis , 163.Fn strvis , 164and 165.Fn strvisx ) , 166and the type of representation used. 167By default, all non-graphic characters, 168except space, tab, and newline are encoded. 169(See 170.Xr isgraph 3 . ) 171The following flags 172alter this: 173.Bl -tag -width VIS_WHITEX 174.It Dv VIS_SP 175Also encode space. 176.It Dv VIS_TAB 177Also encode tab. 178.It Dv VIS_NL 179Also encode newline. 180.It Dv VIS_WHITE 181Synonym for 182.Dv VIS_SP 183\&| 184.Dv VIS_TAB 185\&| 186.Dv VIS_NL . 187.It Dv VIS_SAFE 188Only encode "unsafe" characters. Unsafe means control 189characters which may cause common terminals to perform 190unexpected functions. Currently this form allows space, 191tab, newline, backspace, bell, and return - in addition 192to all graphic characters - unencoded. 193.El 194.Pp 195(The above flags have no effect for 196.Fn svis , 197.Fn strsvis , 198and 199.Fn strsvisx . 200When using these functions, place all graphic characters to be 201encoded in an array pointed to by 202.Fa extra . 203In general, the backslash character should be included in this array, see the 204warning on the use of the 205.Dv VIS_NOSLASH 206flag below). 207.Pp 208There are four forms of encoding. 209All forms use the backslash character 210.Ql \e 211to introduce a special 212sequence; two backslashes are used to represent a real backslash, 213except 214.Dv VIS_HTTPSTYLE 215that uses 216.Ql $ . 217These are the visual formats: 218.Bl -tag -width VIS_CSTYLE 219.It (default) 220Use an 221.Ql M 222to represent meta characters (characters with the 8th 223bit set), and use caret 224.Ql ^ 225to represent control characters see 226.Pf ( Xr iscntrl 3 ) . 227The following formats are used: 228.Bl -tag -width xxxxx 229.It Dv \e^C 230Represents the control character 231.Ql C . 232Spans characters 233.Ql \e000 234through 235.Ql \e037 , 236and 237.Ql \e177 238(as 239.Ql \e^? ) . 240.It Dv \eM-C 241Represents character 242.Ql C 243with the 8th bit set. 244Spans characters 245.Ql \e241 246through 247.Ql \e376 . 248.It Dv \eM^C 249Represents control character 250.Ql C 251with the 8th bit set. 252Spans characters 253.Ql \e200 254through 255.Ql \e237 , 256and 257.Ql \e377 258(as 259.Ql \eM^? ) . 260.It Dv \e040 261Represents 262.Tn ASCII 263space. 264.It Dv \e240 265Represents Meta-space. 266.El 267.Pp 268.It Dv VIS_CSTYLE 269Use C-style backslash sequences to represent standard non-printable 270characters. 271The following sequences are used to represent the indicated characters: 272.Bd -unfilled -offset indent 273.Li \ea Tn - BEL No (007) 274.Li \eb Tn - BS No (010) 275.Li \ef Tn - NP No (014) 276.Li \en Tn - NL No (012) 277.Li \er Tn - CR No (015) 278.Li \et Tn - HT No (011) 279.Li \ev Tn - VT No (013) 280.Li \e0 Tn - NUL No (000) 281.Ed 282.Pp 283When using this format, the nextc parameter is looked at to determine 284if a 285.Dv NUL 286character can be encoded as 287.Ql \e0 288instead of 289.Ql \e000 . 290If 291.Fa nextc 292is an octal digit, the latter representation is used to 293avoid ambiguity. 294.It Dv VIS_OCTAL 295Use a three digit octal sequence. The form is 296.Ql \eddd 297where 298.Em d 299represents an octal digit. 300.It Dv VIS_HTTPSTYLE 301Use URI encoding as described in RFC 1808. 302The form is 303.Ql %xx 304where 305.Em x 306represents a hexadecimal digit. 307.El 308.Pp 309There is one additional flag, 310.Dv VIS_NOSLASH , 311which inhibits the 312doubling of backslashes and the backslash before the default 313format (that is, control characters are represented by 314.Ql ^C 315and 316meta characters as 317.Ql M-C ) . 318With this flag set, the encoding is 319ambiguous and non-invertible. 320.Sh SEE ALSO 321.Xr unvis 1 , 322.Xr vis 1 , 323.Xr unvis 3 324.Rs 325.%A R. Fielding 326.%T Relative Uniform Resource Locators 327.%O RFC1808 328.Re 329.Sh HISTORY 330The 331.Fa vis , 332.Fa strvis , 333and 334.Fa strvisx 335functions first appeared in 336.Bx 4.4 . 337The 338.Fa svis , 339.Fa strsvis , 340and 341.Fa strsvisx 342functions appeared in 343.Nx 1.5 . 344