Commit | Line | Data |
---|---|---|
c2e56add MT |
1 | .\" Copyright (c) 1989 The Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
91cff1e1 | 4 | .\" %sccs.include.redist.man% |
c2e56add | 5 | .\" |
91cff1e1 | 6 | .\" @(#)vis.3 5.6 (Berkeley) %G% |
c2e56add | 7 | .\" |
aa773330 | 8 | .TH VIS 3 "" |
c2e56add | 9 | .UC 7 |
c2e56add | 10 | .SH NAME |
aa773330 | 11 | vis \- visually encode characters |
c2e56add MT |
12 | .SH SYNOPSIS |
13 | .nf | |
4e19ff34 | 14 | .ft B |
aa773330 | 15 | #include <vis.h> |
c2e56add | 16 | |
aa773330 MT |
17 | char *vis(dst, c, flag, nextc) |
18 | char *dst, c, nextc; | |
4e19ff34 | 19 | int flag; |
c2e56add | 20 | |
aa773330 MT |
21 | int strvis(dst, src, flag) |
22 | char *dst, *src; | |
4e19ff34 | 23 | int flag; |
aa773330 MT |
24 | |
25 | int strvisx(dst, src, len, flag) | |
26 | char *dst, *src; | |
27 | int len, flag; | |
28 | ||
4e19ff34 | 29 | .ft R |
c2e56add | 30 | .fi |
4e19ff34 | 31 | .SH DESCRIPTION |
aa773330 MT |
32 | .I Vis |
33 | copies into dst a string which represents the character c. If | |
34 | c needs no encoding, it is copied in unaltered. The string is | |
35 | null terminated, and a pointer to the end of the string is | |
56617876 | 36 | returned. The maximum length of any encoding is four |
aa773330 MT |
37 | characters (not including the trailing NULL); thus, when |
38 | encoding a set of characters into a buffer, the size of the buffer should | |
56617876 | 39 | be four times the number of characters encoded, plus one for the trailing NULL. |
aa773330 MT |
40 | The flag parameter is used for altering the default range of |
41 | characters considered for encoding and for altering the visual | |
42 | representation. | |
43 | The additional character, nextc, is only used when selecting the | |
44 | VIS_CSTYLE encoding format (explained below). | |
4e19ff34 | 45 | .PP |
aa773330 MT |
46 | Strvis and strvisx copy into dst a visual representation of |
47 | the string src. Strvis encodes characters from src up to the | |
48 | first NULL. Strvisx encodes exactly len characters from src (this | |
49 | is useful for encoding a block of data that may contain NULL's). | |
50 | Both forms NULL terminate dst. Dst must be four times the number | |
51 | of characters encoded from src (plus one for the NULL). Both | |
52 | forms return the number of characters in dst (not including | |
53 | the trailing NULL). | |
c2e56add | 54 | .PP |
aa773330 MT |
55 | The encoding is a unique, invertible representation comprised entirely of |
56 | graphic characters; it can be decoded back into the original form using | |
57 | the unvis(3) or strunvis(3) functions. | |
58 | .PP | |
59 | There are two parameters that can be controlled: the range of | |
60 | characters that are encoded, and the type | |
61 | of representation used. | |
56617876 | 62 | By default, all non-graphic characters (see isgraph(3)) |
aa773330 MT |
63 | except space, tab, and newline are encoded. The following flags |
64 | alter this: | |
4e19ff34 | 65 | .TP |
aa773330 MT |
66 | VIS_SP |
67 | Also encode space. | |
c2e56add | 68 | .TP |
aa773330 MT |
69 | VIS_TAB |
70 | Also encode tab. | |
71 | .TP | |
72 | VIS_NL | |
73 | Also encode newline. | |
4e19ff34 | 74 | .TP |
aa773330 MT |
75 | VIS_WHITE |
76 | Synonym for VIS_SP | VIS_TAB | VIS_NL. | |
77 | .TP | |
78 | VIS_SAFE | |
79 | Only encode "unsafe" characters. Unsafe means control | |
80 | characters which may cause common terminals to perform | |
81 | unexpected functions. Currently this form allows space, | |
82 | tab, newline, backspace, bell, and return - in addition | |
83 | to all graphic characters - unencoded. | |
84 | .PP | |
56617876 | 85 | There are three forms of encoding. |
aa773330 MT |
86 | All forms use the backslash character (``\e'') to introduce a special |
87 | sequence; two backslashes are used to represent a real backslash. | |
88 | These are the visual formats: | |
89 | .TP | |
90 | (default) | |
4e19ff34 MT |
91 | Use an ``M'' to represent meta characters (characters with the 8th |
92 | bit set), and use carat (``^'') to represent control characters see | |
93 | (\fIiscntrl\fP(3)). | |
94 | The following formats are used: | |
95 | .RS | |
c2e56add | 96 | .TP |
4e19ff34 MT |
97 | \e^C |
98 | Represents the control character ``C''. | |
aa773330 | 99 | Spans characters \e000 through \e037, and \e177 (as \e^?). |
4e19ff34 MT |
100 | .TP |
101 | \eM-C | |
102 | Represents character ``C'' with the 8th bit set. | |
aa773330 | 103 | Spans characters \e241 through \e376. |
4e19ff34 MT |
104 | .TP |
105 | \eM^C | |
106 | Represents control character ``C'' with the 8th bit set. | |
aa773330 MT |
107 | Spans characters \e200 through \e237, and \e377 (as \eM^?). |
108 | .TP | |
109 | \e040 | |
110 | Represents ACSII space. | |
111 | .TP | |
112 | \e240 | |
113 | Represents Meta-space. | |
4e19ff34 MT |
114 | .sp |
115 | .RE | |
4e19ff34 | 116 | .TP |
56617876 | 117 | VIS_CSTYLE |
aa773330 MT |
118 | Use C-style backslash sequences to represent standard non-printable |
119 | characters. | |
120 | The following sequences are used to represent the indicated characters: | |
121 | .sp | |
122 | .nf | |
123 | \ea - BEL (007) | |
124 | \eb - BS (010) | |
125 | \ef - NP (014) | |
126 | \en - NL (012) | |
127 | \er - CR (015) | |
128 | \et - HT (011) | |
129 | \ev - VT (013) | |
130 | \e0 - NUL (000) | |
131 | .fi | |
132 | .sp | |
133 | When using this format, the nextc parameter is looked at to determine | |
134 | if a NULL character can be encoded as ``\e0'' instead of ``\e000''. | |
135 | If nextc is an octal digit, the latter representation is used to | |
136 | avoid ambiguity. | |
137 | .TP | |
138 | VIS_OCTAL | |
4e19ff34 MT |
139 | Use a three digit octal sequence. The form is ``\eddd'' where |
140 | d represents an octal digit. | |
c2e56add | 141 | .PP |
aa773330 MT |
142 | There is one additional flag, VIS_NOSLASH, which inhibits the |
143 | doubling of backslashes and the backslash before the default | |
144 | format (that is, control characters are represented by ^C and | |
145 | meta characters as M-C). With this flag set, the encoding is | |
146 | ambiguous and non-invertible. | |
c2e56add | 147 | .SH "SEE ALSO" |
aa773330 | 148 | vis(1), unvis(1), unvis(3) |