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