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