Commit | Line | Data |
---|---|---|
af359dea | 1 | .\" Copyright (c) 1989, 1991 The Regents of the University of California. |
c2e56add MT |
2 | .\" All rights reserved. |
3 | .\" | |
af359dea C |
4 | .\" Redistribution and use in source and binary forms, with or without |
5 | .\" modification, are permitted provided that the following conditions | |
6 | .\" are met: | |
7 | .\" 1. Redistributions of source code must retain the above copyright | |
8 | .\" notice, this list of conditions and the following disclaimer. | |
9 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer in the | |
11 | .\" documentation and/or other materials provided with the distribution. | |
12 | .\" 3. All advertising materials mentioning features or use of this software | |
13 | .\" must display the following acknowledgement: | |
14 | .\" This product includes software developed by the University of | |
15 | .\" California, Berkeley and its contributors. | |
16 | .\" 4. Neither the name of the University nor the names of its contributors | |
17 | .\" may be used to endorse or promote products derived from this software | |
18 | .\" without specific prior written permission. | |
c2e56add | 19 | .\" |
af359dea C |
20 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
21 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
22 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
23 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
24 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
25 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
26 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
27 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
28 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
29 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
30 | .\" SUCH DAMAGE. | |
c2e56add | 31 | .\" |
af359dea C |
32 | .\" @(#)vis.3 5.7 (Berkeley) 4/19/91 |
33 | .\" | |
34 | .Dd April 19, 1991 | |
35 | .Dt VIS 3 | |
36 | .Os | |
37 | .Sh NAME | |
38 | .Nm vis | |
39 | .Nd visually encode characters | |
40 | .Sh SYNOPSIS | |
41 | .Fd #include <vis.h> | |
42 | .Ft char * | |
43 | .Fn vis "char *dst" "char c" "int flag" "char nextc" | |
44 | .Ft int | |
45 | .Fn strvis "char *dst" "char *src" "int flag" | |
46 | .Ft int | |
47 | .Fn strvisx "char *dst" "char *src" "int len" "int flag" | |
48 | .Sh DESCRIPTION | |
49 | The | |
50 | .Fn vis | |
51 | function | |
52 | copies into | |
53 | .Fa dst | |
54 | a string which represents the character | |
55 | .Fa c . | |
56 | If | |
57 | .Fa c | |
58 | needs no encoding, it is copied in unaltered. The string is | |
aa773330 | 59 | null terminated, and a pointer to the end of the string is |
56617876 | 60 | returned. The maximum length of any encoding is four |
af359dea C |
61 | characters (not including the trailing |
62 | .Dv NULL ) ; | |
63 | thus, when | |
aa773330 | 64 | encoding a set of characters into a buffer, the size of the buffer should |
af359dea C |
65 | be four times the number of characters encoded, plus one for the trailing |
66 | .Dv NULL . | |
aa773330 MT |
67 | The flag parameter is used for altering the default range of |
68 | characters considered for encoding and for altering the visual | |
69 | representation. | |
af359dea C |
70 | The additional character, |
71 | .Fa nextc , | |
72 | is only used when selecting the | |
73 | .Dv VIS_CSTYLE | |
74 | encoding format (explained below). | |
75 | .Pp | |
76 | The | |
77 | .Fn strvis | |
78 | and | |
79 | .Fn strvisx | |
80 | functions copy into | |
81 | .Fa dst | |
82 | a visual representation of | |
83 | the string | |
84 | .Fa src . | |
85 | The | |
86 | .Fn strvis | |
87 | function encodes characters from | |
88 | .Fa src | |
89 | up to the | |
90 | first | |
91 | .Dv NULL . | |
92 | The | |
93 | .Fn strvisx | |
94 | function encodes exactly | |
95 | .Fa len | |
96 | characters from | |
97 | .Fa src | |
98 | (this | |
99 | is useful for encoding a block of data that may contain | |
100 | .Dv NULL Ns 's). | |
101 | Both forms | |
102 | .Dv NULL | |
103 | terminate | |
104 | .Fa dst . | |
105 | The size of | |
106 | .Fa dst | |
107 | must be four times the number | |
108 | of characters encoded from | |
109 | .Fa src | |
110 | (plus one for the | |
111 | .Dv NULL ) . | |
112 | Both | |
aa773330 | 113 | forms return the number of characters in dst (not including |
af359dea C |
114 | the trailing |
115 | .Dv NULL ) . | |
116 | .Pp | |
aa773330 MT |
117 | The encoding is a unique, invertible representation comprised entirely of |
118 | graphic characters; it can be decoded back into the original form using | |
af359dea C |
119 | the |
120 | .Xr unvis 3 | |
121 | or | |
122 | .Xr strunvis 3 | |
123 | functions. | |
124 | .Pp | |
aa773330 MT |
125 | There are two parameters that can be controlled: the range of |
126 | characters that are encoded, and the type | |
127 | of representation used. | |
af359dea C |
128 | By default, all non-graphic characters. |
129 | except space, tab, and newline are encoded. | |
130 | (See | |
131 | .Xr isgraph 3 . ) | |
132 | The following flags | |
aa773330 | 133 | alter this: |
af359dea C |
134 | .Bl -tag -width VIS_WHITEX |
135 | .It Dv VIS_SP | |
aa773330 | 136 | Also encode space. |
af359dea | 137 | .It Dv VIS_TAB |
aa773330 | 138 | Also encode tab. |
af359dea | 139 | .It Dv VIS_NL |
aa773330 | 140 | Also encode newline. |
af359dea C |
141 | .It Dv VIS_WHITE |
142 | Synonym for | |
143 | .Dv VIS_SP | |
144 | \&| | |
145 | .Dv VIS_TAB | |
146 | \&| | |
147 | .Dv VIS_NL . | |
148 | .It Dv VIS_SAFE | |
aa773330 MT |
149 | Only encode "unsafe" characters. Unsafe means control |
150 | characters which may cause common terminals to perform | |
151 | unexpected functions. Currently this form allows space, | |
152 | tab, newline, backspace, bell, and return - in addition | |
153 | to all graphic characters - unencoded. | |
af359dea C |
154 | .El |
155 | .Pp | |
56617876 | 156 | There are three forms of encoding. |
af359dea C |
157 | All forms use the backslash character |
158 | .Ql \e | |
159 | to introduce a special | |
aa773330 MT |
160 | sequence; two backslashes are used to represent a real backslash. |
161 | These are the visual formats: | |
af359dea C |
162 | .Bl -tag -width VIS_CSTYLE |
163 | .It (default) | |
164 | Use an | |
165 | .Ql M | |
166 | to represent meta characters (characters with the 8th | |
167 | bit set), and use carat | |
168 | .Ql ^ | |
169 | to represent control characters see | |
170 | .Pf ( Xr iscntrl 3 ) . | |
4e19ff34 | 171 | The following formats are used: |
af359dea C |
172 | .Bl -tag -width xxxxx |
173 | .It Dv \e^C | |
174 | Represents the control character | |
175 | .Ql C . | |
176 | Spans characters | |
177 | .Ql \e000 | |
178 | through | |
179 | .Ql \e037 , | |
180 | and | |
181 | .Ql \e177 | |
182 | (as | |
183 | .Ql \e^? ) . | |
184 | .It Dv \eM-C | |
185 | Represents character | |
186 | .Ql C | |
187 | with the 8th bit set. | |
188 | Spans characters | |
189 | .Ql \e241 | |
190 | through | |
191 | .Ql \e376 . | |
192 | .It Dv \eM^C | |
193 | Represents control character | |
194 | .Ql C | |
195 | with the 8th bit set. | |
196 | Spans characters | |
197 | .Ql \e200 | |
198 | through | |
199 | .Ql \e237 , | |
200 | and | |
201 | .Ql \e377 | |
202 | (as | |
203 | .Ql \eM^? ) . | |
204 | .It Dv \e040 | |
205 | Represents | |
206 | .Tn ASCII | |
207 | space. | |
208 | .It Dv \e240 | |
aa773330 | 209 | Represents Meta-space. |
af359dea C |
210 | .El |
211 | .Pp | |
212 | .It Dv VIS_CSTYLE | |
aa773330 MT |
213 | Use C-style backslash sequences to represent standard non-printable |
214 | characters. | |
215 | The following sequences are used to represent the indicated characters: | |
af359dea C |
216 | .Bd -unfilled -offset indent |
217 | .Li \ea Tn - BEL No (007) | |
218 | .Li \eb Tn - BS No (010) | |
219 | .Li \ef Tn - NP No (014) | |
220 | .Li \en Tn - NL No (012) | |
221 | .Li \er Tn - CR No (015) | |
222 | .Li \et Tn - HT No (011) | |
223 | .Li \ev Tn - VT No (013) | |
224 | .Li \e0 Tn - NUL No (000) | |
225 | .Ed | |
226 | .Pp | |
aa773330 | 227 | When using this format, the nextc parameter is looked at to determine |
af359dea C |
228 | if a |
229 | .Dv NULL | |
230 | character can be encoded as | |
231 | .Ql \e0 | |
232 | instead of | |
233 | .Ql \e000 . | |
234 | If | |
235 | .Fa nextc | |
236 | is an octal digit, the latter representation is used to | |
aa773330 | 237 | avoid ambiguity. |
af359dea C |
238 | .It Dv VIS_OCTAL |
239 | Use a three digit octal sequence. The form is | |
240 | .Ql \eddd | |
241 | where | |
242 | .Em d | |
243 | represents an octal digit. | |
244 | .El | |
245 | .Pp | |
246 | There is one additional flag, | |
247 | .Dv VIS_NOSLASH , | |
248 | which inhibits the | |
aa773330 | 249 | doubling of backslashes and the backslash before the default |
af359dea C |
250 | format (that is, control characters are represented by |
251 | .Ql ^C | |
252 | and | |
253 | meta characters as | |
254 | .Ql M-C ) . | |
255 | With this flag set, the encoding is | |
aa773330 | 256 | ambiguous and non-invertible. |
af359dea C |
257 | .Sh SEE ALSO |
258 | .Xr unvis 1 , | |
259 | .Xr unvis 3 | |
260 | .Xr strunvis 3 | |
261 | .Sh HISTORY | |
262 | These | |
263 | functions are | |
264 | .Ud . |