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