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