1.\" $NetBSD: vis.3,v 1.18 2003/04/16 13:34:40 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. 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.In vis.h 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. 74The string is null terminated, and a pointer to the end of the string is 75returned. 76The maximum length of any encoding is four 77characters (not including the trailing 78.Dv NUL ) ; 79thus, when 80encoding a set of characters into a buffer, the size of the buffer should 81be four times the number of characters encoded, plus one for the trailing 82.Dv NUL . 83The flag parameter is used for altering the default range of 84characters considered for encoding and for altering the visual 85representation. 86The additional character, 87.Fa nextc , 88is only used when selecting the 89.Dv VIS_CSTYLE 90encoding format (explained below). 91.Pp 92The 93.Fn strvis 94and 95.Fn strvisx 96functions copy into 97.Fa dst 98a visual representation of 99the string 100.Fa src . 101The 102.Fn strvis 103function encodes characters from 104.Fa src 105up to the 106first 107.Dv NUL . 108The 109.Fn strvisx 110function encodes exactly 111.Fa len 112characters from 113.Fa src 114(this 115is useful for encoding a block of data that may contain 116.Dv NUL Ns 's ) . 117Both forms 118.Dv NUL 119terminate 120.Fa dst . 121The size of 122.Fa dst 123must be four times the number 124of characters encoded from 125.Fa src 126(plus one for the 127.Dv NUL ) . 128Both 129forms return the number of characters in dst (not including 130the trailing 131.Dv NUL ) . 132.Pp 133The functions 134.Fn svis , 135.Fn strsvis , 136and 137.Fn strsvisx 138correspond to 139.Fn vis , 140.Fn strvis , 141and 142.Fn strvisx 143but have an additional argument 144.Fa extra , 145pointing to a 146.Dv NUL 147terminated list of characters. 148These characters will be copied encoded or backslash-escaped into 149.Fa dst . 150These functions are useful e.g. to remove the special meaning 151of certain characters to shells. 152.Pp 153The encoding is a unique, invertible representation composed entirely of 154graphic characters; it can be decoded back into the original form using 155the 156.Xr unvis 3 157or 158.Xr strunvis 3 159functions. 160.Pp 161There are two parameters that can be controlled: the range of 162characters that are encoded (applies only to 163.Fn vis , 164.Fn strvis , 165and 166.Fn strvisx ) , 167and the type of representation used. 168By default, all non-graphic characters, 169except space, tab, and newline are encoded. 170(See 171.Xr isgraph 3 . ) 172The following flags 173alter this: 174.Bl -tag -width VIS_WHITEX 175.It Dv VIS_SP 176Also encode space. 177.It Dv VIS_TAB 178Also encode tab. 179.It Dv VIS_NL 180Also encode newline. 181.It Dv VIS_WHITE 182Synonym for 183.Dv VIS_SP 184\&| 185.Dv VIS_TAB 186\&| 187.Dv VIS_NL . 188.It Dv VIS_SAFE 189Only encode "unsafe" characters. 190Unsafe means control characters which may cause common terminals to perform 191unexpected functions. 192Currently this form allows space, tab, newline, backspace, bell, and 193return - in addition to all graphic characters - unencoded. 194.El 195.Pp 196(The above flags have no effect for 197.Fn svis , 198.Fn strsvis , 199and 200.Fn strsvisx . 201When using these functions, place all graphic characters to be 202encoded in an array pointed to by 203.Fa extra . 204In general, the backslash character should be included in this array, see the 205warning on the use of the 206.Dv VIS_NOSLASH 207flag below). 208.Pp 209There are four forms of encoding. 210All forms use the backslash character 211.Ql \e 212to introduce a special 213sequence; two backslashes are used to represent a real backslash, 214except 215.Dv VIS_HTTPSTYLE 216that uses 217.Ql $ . 218These are the visual formats: 219.Bl -tag -width VIS_CSTYLE 220.It (default) 221Use an 222.Ql M 223to represent meta characters (characters with the 8th 224bit set), and use caret 225.Ql ^ 226to represent control characters see 227.Pf ( Xr iscntrl 3 ) . 228The following formats are used: 229.Bl -tag -width xxxxx 230.It Dv \e^C 231Represents the control character 232.Ql C . 233Spans characters 234.Ql \e000 235through 236.Ql \e037 , 237and 238.Ql \e177 239(as 240.Ql \e^? ) . 241.It Dv \eM-C 242Represents character 243.Ql C 244with the 8th bit set. 245Spans characters 246.Ql \e241 247through 248.Ql \e376 . 249.It Dv \eM^C 250Represents control character 251.Ql C 252with the 8th bit set. 253Spans characters 254.Ql \e200 255through 256.Ql \e237 , 257and 258.Ql \e377 259(as 260.Ql \eM^? ) . 261.It Dv \e040 262Represents 263.Tn ASCII 264space. 265.It Dv \e240 266Represents Meta-space. 267.El 268.Pp 269.It Dv VIS_CSTYLE 270Use C-style backslash sequences to represent standard non-printable 271characters. 272The following sequences are used to represent the indicated characters: 273.Bd -unfilled -offset indent 274.Li \ea Tn - BEL No (007) 275.Li \eb Tn - BS No (010) 276.Li \ef Tn - NP No (014) 277.Li \en Tn - NL No (012) 278.Li \er Tn - CR No (015) 279.Li \et Tn - HT No (011) 280.Li \ev Tn - VT No (013) 281.Li \e0 Tn - NUL No (000) 282.Ed 283.Pp 284When using this format, the nextc parameter is looked at to determine 285if a 286.Dv NUL 287character can be encoded as 288.Ql \e0 289instead of 290.Ql \e000 . 291If 292.Fa nextc 293is an octal digit, the latter representation is used to 294avoid ambiguity. 295.It Dv VIS_OCTAL 296Use a three digit octal sequence. 297The form is 298.Ql \eddd 299where 300.Em d 301represents an octal digit. 302.It Dv VIS_HTTPSTYLE 303Use URI encoding as described in RFC 1808. 304The form is 305.Ql %xx 306where 307.Em x 308represents a hexadecimal digit. 309.El 310.Pp 311There is one additional flag, 312.Dv VIS_NOSLASH , 313which inhibits the 314doubling of backslashes and the backslash before the default 315format (that is, control characters are represented by 316.Ql ^C 317and 318meta characters as 319.Ql M-C ) . 320With this flag set, the encoding is 321ambiguous and non-invertible. 322.Sh SEE ALSO 323.Xr unvis 1 , 324.Xr vis 1 , 325.Xr unvis 3 326.Rs 327.%A R. Fielding 328.%T Relative Uniform Resource Locators 329.%O RFC1808 330.Re 331.Sh HISTORY 332The 333.Fa vis , 334.Fa strvis , 335and 336.Fa strvisx 337functions first appeared in 338.Bx 4.4 . 339The 340.Fa svis , 341.Fa strsvis , 342and 343.Fa strsvisx 344functions appeared in 345.Nx 1.5 . 346