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