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