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