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