1.\" Copyright (c) 1989, 1991 The Regents of the University of California. 2.\" 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.\" @(#)vis.3 5.7 (Berkeley) 4/19/91 33.\" 34.Dd April 19, 1991 35.Dt VIS 3 36.Os 37.Sh NAME 38.Nm vis 39.Nd visually encode characters 40.Sh SYNOPSIS 41.Fd #include <vis.h> 42.Ft char * 43.Fn vis "char *dst" "char c" "int flag" "char nextc" 44.Ft int 45.Fn strvis "char *dst" "char *src" "int flag" 46.Ft int 47.Fn strvisx "char *dst" "char *src" "int len" "int flag" 48.Sh DESCRIPTION 49The 50.Fn vis 51function 52copies into 53.Fa dst 54a string which represents the character 55.Fa c . 56If 57.Fa c 58needs no encoding, it is copied in unaltered. The string is 59null terminated, and a pointer to the end of the string is 60returned. The maximum length of any encoding is four 61characters (not including the trailing 62.Dv NULL ) ; 63thus, when 64encoding a set of characters into a buffer, the size of the buffer should 65be four times the number of characters encoded, plus one for the trailing 66.Dv NULL . 67The flag parameter is used for altering the default range of 68characters considered for encoding and for altering the visual 69representation. 70The additional character, 71.Fa nextc , 72is only used when selecting the 73.Dv VIS_CSTYLE 74encoding format (explained below). 75.Pp 76The 77.Fn strvis 78and 79.Fn strvisx 80functions copy into 81.Fa dst 82a visual representation of 83the string 84.Fa src . 85The 86.Fn strvis 87function encodes characters from 88.Fa src 89up to the 90first 91.Dv NULL . 92The 93.Fn strvisx 94function encodes exactly 95.Fa len 96characters from 97.Fa src 98(this 99is useful for encoding a block of data that may contain 100.Dv NULL Ns 's). 101Both forms 102.Dv NULL 103terminate 104.Fa dst . 105The size of 106.Fa dst 107must be four times the number 108of characters encoded from 109.Fa src 110(plus one for the 111.Dv NULL ) . 112Both 113forms return the number of characters in dst (not including 114the trailing 115.Dv NULL ) . 116.Pp 117The encoding is a unique, invertible representation comprised entirely of 118graphic characters; it can be decoded back into the original form using 119the 120.Xr unvis 3 121or 122.Xr strunvis 3 123functions. 124.Pp 125There are two parameters that can be controlled: the range of 126characters that are encoded, and the type 127of representation used. 128By default, all non-graphic characters. 129except space, tab, and newline are encoded. 130(See 131.Xr isgraph 3 . ) 132The following flags 133alter this: 134.Bl -tag -width VIS_WHITEX 135.It Dv VIS_SP 136Also encode space. 137.It Dv VIS_TAB 138Also encode tab. 139.It Dv VIS_NL 140Also encode newline. 141.It Dv VIS_WHITE 142Synonym for 143.Dv VIS_SP 144\&| 145.Dv VIS_TAB 146\&| 147.Dv VIS_NL . 148.It Dv VIS_SAFE 149Only encode "unsafe" characters. Unsafe means control 150characters which may cause common terminals to perform 151unexpected functions. Currently this form allows space, 152tab, newline, backspace, bell, and return - in addition 153to all graphic characters - unencoded. 154.El 155.Pp 156There are three forms of encoding. 157All forms use the backslash character 158.Ql \e 159to introduce a special 160sequence; two backslashes are used to represent a real backslash. 161These are the visual formats: 162.Bl -tag -width VIS_CSTYLE 163.It (default) 164Use an 165.Ql M 166to represent meta characters (characters with the 8th 167bit set), and use carat 168.Ql ^ 169to represent control characters see 170.Pf ( Xr iscntrl 3 ) . 171The following formats are used: 172.Bl -tag -width xxxxx 173.It Dv \e^C 174Represents the control character 175.Ql C . 176Spans characters 177.Ql \e000 178through 179.Ql \e037 , 180and 181.Ql \e177 182(as 183.Ql \e^? ) . 184.It Dv \eM-C 185Represents character 186.Ql C 187with the 8th bit set. 188Spans characters 189.Ql \e241 190through 191.Ql \e376 . 192.It Dv \eM^C 193Represents control character 194.Ql C 195with the 8th bit set. 196Spans characters 197.Ql \e200 198through 199.Ql \e237 , 200and 201.Ql \e377 202(as 203.Ql \eM^? ) . 204.It Dv \e040 205Represents 206.Tn ASCII 207space. 208.It Dv \e240 209Represents Meta-space. 210.El 211.Pp 212.It Dv VIS_CSTYLE 213Use C-style backslash sequences to represent standard non-printable 214characters. 215The following sequences are used to represent the indicated characters: 216.Bd -unfilled -offset indent 217.Li \ea Tn - BEL No (007) 218.Li \eb Tn - BS No (010) 219.Li \ef Tn - NP No (014) 220.Li \en Tn - NL No (012) 221.Li \er Tn - CR No (015) 222.Li \et Tn - HT No (011) 223.Li \ev Tn - VT No (013) 224.Li \e0 Tn - NUL No (000) 225.Ed 226.Pp 227When using this format, the nextc parameter is looked at to determine 228if a 229.Dv NULL 230character can be encoded as 231.Ql \e0 232instead of 233.Ql \e000 . 234If 235.Fa nextc 236is an octal digit, the latter representation is used to 237avoid ambiguity. 238.It Dv VIS_OCTAL 239Use a three digit octal sequence. The form is 240.Ql \eddd 241where 242.Em d 243represents an octal digit. 244.El 245.Pp 246There is one additional flag, 247.Dv VIS_NOSLASH , 248which inhibits the 249doubling of backslashes and the backslash before the default 250format (that is, control characters are represented by 251.Ql ^C 252and 253meta characters as 254.Ql M-C ) . 255With this flag set, the encoding is 256ambiguous and non-invertible. 257.Sh SEE ALSO 258.Xr unvis 1 , 259.Xr unvis 3 260.Xr strunvis 3 261.Sh HISTORY 262These 263functions are 264.Ud . 265