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