1.\" $OpenBSD: vis.3,v 1.24 2007/05/31 19:19:29 jmc 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. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.Dd $Mdocdate: May 31 2007 $ 31.Dt VIS 3 32.Os 33.Sh NAME 34.Nm vis , 35.Nm strvis , 36.Nm strnvis , 37.Nm strvisx 38.Nd visually encode characters 39.Sh SYNOPSIS 40.Fd #include <stdlib.h> 41.Fd #include <vis.h> 42.Ft char * 43.Fn vis "char *dst" "int c" "int flag" "int nextc" 44.Ft int 45.Fn strvis "char *dst" "const char *src" "int flag" 46.Ft int 47.Fn strnvis "char *dst" "const char *src" "size_t size" "int flag" 48.Ft int 49.Fn strvisx "char *dst" "const char *src" "size_t len" "int flag" 50.Sh DESCRIPTION 51The 52.Fn vis 53function copies 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. 60The string is NUL terminated and a pointer to the end of the string is 61returned. 62The maximum length of any encoding is four 63characters (not including the trailing NUL); 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 67NUL. 68The 69.Fa flag 70parameter is used for altering the default range of 71characters considered for encoding and for altering the visual 72representation. 73The additional character, 74.Fa nextc , 75is only used when selecting the 76.Dv VIS_CSTYLE 77encoding format (explained below). 78.Pp 79The 80.Fn strvis , 81.Fn strnvis 82and 83.Fn strvisx 84functions copy into 85.Fa dst 86a visual representation of 87the string 88.Fa src . 89The 90.Fn strvis 91function encodes characters from 92.Fa src 93up to the first NUL. 94The 95.Fn strnvis 96function encodes characters from 97.Fa src 98up to the first NUL or the end of 99.Fa dst , 100as indicated by 101.Fa size . 102The 103.Fn strvisx 104function encodes exactly 105.Fa len 106characters from 107.Fa src 108(this 109is useful for encoding a block of data that may contain NULs). 110All three forms NUL terminate 111.Fa dst , 112except for 113.Fn strnvis 114when 115.Fa size 116is zero, in which case 117.Fa dst 118is not touched. 119For 120.Fn strvis 121and 122.Fn strvisx , 123the size of 124.Fa dst 125must be four times the number 126of characters encoded from 127.Fa src 128(plus one for the NUL). 129.Fn strvis 130and 131.Fn strvisx 132return the number of characters in 133.Fa dst 134(not including the trailing NUL). 135.Fn strnvis 136returns the length that 137.Fa dst 138would become if it were of unlimited size (similar to 139.Xr snprintf 3 140or 141.Xr strlcpy 3 ) . 142This can be used to detect truncation but it also means that 143the return value of 144.Fn strnvis 145must not be used without checking it against 146.Fa size . 147.Pp 148The encoding is a unique, invertible representation composed entirely of 149graphic characters; it can be decoded back into the original form using 150the 151.Xr unvis 3 152or 153.Xr strunvis 3 154functions. 155.Pp 156There are two parameters that can be controlled: the range of 157characters that are encoded, and the type 158of representation used. 159By default, all non-graphic characters 160except space, tab, and newline are encoded 161(see 162.Xr isgraph 3 ) . 163The following flags 164alter this: 165.Bl -tag -width VIS_WHITEX 166.It Dv VIS_GLOB 167Also encode magic characters recognized by 168.Xr glob 3 169.Pf ( Ql * , 170.Ql \&? , 171.Ql \&[ ) 172and 173.Ql # . 174.It Dv VIS_SP 175Also encode space. 176.It Dv VIS_TAB 177Also encode tab. 178.It Dv VIS_NL 179Also encode newline. 180.It Dv VIS_WHITE 181Synonym for 182.Dv VIS_SP 183\&| 184.Dv VIS_TAB 185\&| 186.Dv VIS_NL . 187.It Dv VIS_SAFE 188Only encode 189.Dq unsafe 190characters. 191These are control characters which may cause common terminals to perform 192unexpected functions. 193Currently this form allows space, 194tab, newline, backspace, bell, and return -- in addition 195to all graphic characters -- unencoded. 196.El 197.Pp 198There are three forms of encoding. 199All forms use the backslash 200.Ql \e 201character to introduce a special 202sequence; two backslashes are used to represent a real backslash. 203These are the visual formats: 204.Bl -tag -width VIS_CSTYLE 205.It (default) 206Use an 207.Ql M 208to represent meta characters (characters with the 8th 209bit set), and use a caret 210.Ql ^ 211to represent control characters (see 212.Xr iscntrl 3 ) . 213The following formats are used: 214.Bl -tag -width xxxxx 215.It Dv \e^C 216Represents the control character 217.Ql C . 218Spans characters 219.Ql \e000 220through 221.Ql \e037 , 222and 223.Ql \e177 224(as 225.Ql \e^? ) . 226.It Dv \eM-C 227Represents character 228.Ql C 229with the 8th bit set. 230Spans characters 231.Ql \e241 232through 233.Ql \e376 . 234.It Dv \eM^C 235Represents control character 236.Ql C 237with the 8th bit set. 238Spans characters 239.Ql \e200 240through 241.Ql \e237 , 242and 243.Ql \e377 244(as 245.Ql \eM^? ) . 246.It Dv \e040 247Represents 248.Tn ASCII 249space. 250.It Dv \e240 251Represents Meta-space. 252.El 253.Pp 254.It Dv VIS_CSTYLE 255Use C-style backslash sequences to represent standard non-printable 256characters. 257The following sequences are used to represent the indicated characters: 258.Bd -unfilled -offset indent 259.Li \ea Tn - BEL No (007) 260.Li \eb Tn - BS No (010) 261.Li \ef Tn - NP No (014) 262.Li \en Tn - NL No (012) 263.Li \er Tn - CR No (015) 264.Li \es Tn - SP No (040) 265.Li \et Tn - HT No (011) 266.Li \ev Tn - VT No (013) 267.Li \e0 Tn - NUL No (000) 268.Ed 269.Pp 270When using this format, the 271.Fa nextc 272parameter is looked at to determine 273if a NUL character can be encoded as 274.Ql \e0 275instead of 276.Ql \e000 . 277If 278.Fa nextc 279is an octal digit, the latter representation is used to 280avoid ambiguity. 281.It Dv VIS_OCTAL 282Use a three digit octal sequence. 283The form is 284.Ql \eddd 285where 286.Ar d 287represents an octal digit. 288.El 289.Pp 290There is one additional flag, 291.Dv VIS_NOSLASH , 292which inhibits the 293doubling of backslashes and the backslash before the default 294format (that is, control characters are represented by 295.Ql ^C 296and 297meta characters as 298.Ql M-C ) . 299With this flag set, the encoding is 300ambiguous and non-invertible. 301.Sh SEE ALSO 302.Xr unvis 1 , 303.Xr vis 1 , 304.Xr snprintf 3 , 305.Xr strlcpy 3 , 306.Xr unvis 3 307.Sh HISTORY 308The 309.Fn vis , 310.Fn strvis 311and 312.Fn strvisx 313functions first appeared in 314.Bx 4.4 . 315The 316.Fn strnvis 317function first appeared in 318.Ox 2.9 . 319