1.\" $OpenBSD: vis.3,v 1.28 2011/05/02 11:14:11 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 2 2011 $ 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 dstsize" "int flag" 48.Ft int 49.Fn strvisx "char *dst" "const char *src" "size_t srclen" "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 . 89.Pp 90The 91.Fn strvis 92function encodes characters from 93.Fa src 94up to the first NUL, into a buffer 95.Fa dst 96(which must be at least 4 * srclen + 1 long). 97.Pp 98The 99.Fn strnvis 100function encodes characters from 101.Fa src 102up to the first NUL or the end of the buffer 103.Fa dst , 104as indicated by 105.Fa dstsize . 106.Pp 107The 108.Fn strvisx 109function encodes exactly 110.Fa srclen 111characters from 112.Fa src 113into a buffer 114.Fa dst 115(which must be at least 4 * srclen + 1 long). 116This 117is useful for encoding a block of data that may contain NULs. 118.Pp 119All three forms NUL-terminate 120.Fa dst , 121except for 122.Fn strnvis 123when 124.Fa dstsize 125is zero, in which case 126.Fa dst 127is not touched. 128.Fn strvis 129and 130.Fn strvisx 131return the number of characters in 132.Fa dst 133(not including the trailing NUL). 134.Fn strnvis 135returns the length that 136.Fa dst 137would become if it were of unlimited size (similar to 138.Xr snprintf 3 139or 140.Xr strlcpy 3 ) . 141This can be used to detect truncation but it also means that 142the return value of 143.Fn strnvis 144must not be used without checking it against 145.Fa dstsize . 146.Pp 147The encoding is a unique, invertible representation composed entirely of 148graphic characters; it can be decoded back into the original form using 149the 150.Xr unvis 3 151or 152.Xr strunvis 3 153functions. 154.Pp 155There are two parameters that can be controlled: the range of 156characters that are encoded, and the type 157of representation used. 158By default, all non-graphic characters 159except space, tab, and newline are encoded 160(see 161.Xr isgraph 3 ) . 162The following flags 163alter this: 164.Bl -tag -width VIS_WHITEX 165.It Dv VIS_ALL 166Encode all characters, whether visible or not. 167.It Dv VIS_GLOB 168Also encode magic characters recognized by 169.Xr glob 3 170.Pf ( Ql * , 171.Ql \&? , 172.Ql \&[ ) 173and 174.Ql # . 175.It Dv VIS_SP 176Also encode space. 177.It Dv VIS_TAB 178Also encode tab. 179.It Dv VIS_NL 180Also encode newline. 181.It Dv VIS_WHITE 182Synonym for 183.Dv VIS_SP | VIS_TAB | VIS_NL . 184.It Dv VIS_SAFE 185Only encode 186.Dq unsafe 187characters. 188These are control characters which may cause common terminals to perform 189unexpected functions. 190Currently this form allows space, 191tab, newline, backspace, bell, and return -- in addition 192to all graphic characters -- unencoded. 193.El 194.Pp 195There are three forms of encoding. 196All forms use the backslash 197.Ql \e 198character to introduce a special 199sequence; two backslashes are used to represent a real backslash. 200These are the visual formats: 201.Bl -tag -width VIS_CSTYLE 202.It (default) 203Use an 204.Ql M 205to represent meta characters (characters with the 8th 206bit set), and use a caret 207.Ql ^ 208to represent control characters (see 209.Xr iscntrl 3 ) . 210The following formats are used: 211.Bl -tag -width xxxxx 212.It Dv \e^C 213Represents the control character 214.Ql C . 215Spans characters 216.Ql \e000 217through 218.Ql \e037 , 219and 220.Ql \e177 221(as 222.Ql \e^? ) . 223.It Dv \eM-C 224Represents character 225.Ql C 226with the 8th bit set. 227Spans characters 228.Ql \e241 229through 230.Ql \e376 . 231.It Dv \eM^C 232Represents control character 233.Ql C 234with the 8th bit set. 235Spans characters 236.Ql \e200 237through 238.Ql \e237 , 239and 240.Ql \e377 241(as 242.Ql \eM^? ) . 243.It Dv \e040 244Represents 245.Tn ASCII 246space. 247.It Dv \e240 248Represents Meta-space. 249.El 250.Pp 251.It Dv VIS_CSTYLE 252Use C-style backslash sequences to represent standard non-printable 253characters. 254The following sequences are used to represent the indicated characters: 255.Bd -unfilled -offset indent 256.Li \ea Tn - BEL No (007) 257.Li \eb Tn - BS No (010) 258.Li \ef Tn - NP No (014) 259.Li \en Tn - NL No (012) 260.Li \er Tn - CR No (015) 261.Li \es Tn - SP No (040) 262.Li \et Tn - HT No (011) 263.Li \ev Tn - VT No (013) 264.Li \e0 Tn - NUL No (000) 265.Ed 266.Pp 267When using this format, the 268.Fa nextc 269parameter is looked at to determine 270if a NUL character can be encoded as 271.Ql \e0 272instead of 273.Ql \e000 . 274If 275.Fa nextc 276is an octal digit, the latter representation is used to 277avoid ambiguity. 278.It Dv VIS_OCTAL 279Use a three digit octal sequence. 280The form is 281.Ql \eddd 282where 283.Ar d 284represents an octal digit. 285.El 286.Pp 287There is one additional flag, 288.Dv VIS_NOSLASH , 289which inhibits the 290doubling of backslashes and the backslash before the default 291format (that is, control characters are represented by 292.Ql ^C 293and 294meta characters as 295.Ql M-C ) . 296With this flag set, the encoding is 297ambiguous and non-invertible. 298.Sh SEE ALSO 299.Xr unvis 1 , 300.Xr vis 1 , 301.Xr snprintf 3 , 302.Xr strlcpy 3 , 303.Xr unvis 3 304.Sh HISTORY 305The 306.Fn vis , 307.Fn strvis 308and 309.Fn strvisx 310functions first appeared in 311.Bx 4.4 . 312The 313.Fn strnvis 314function first appeared in 315.Ox 2.9 . 316