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