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