![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to vis.3 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / gen|
Return to vis.3 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / gen |
1.1 root 1: .\" Copyright (c) 1989 The Regents of the University of California.
2: .\" All rights reserved.
3: .\"
4: .\" Redistribution and use in source and binary forms are permitted provided
5: .\" that: (1) source distributions retain this entire copyright notice and
6: .\" comment, and (2) distributions including binaries display the following
7: .\" acknowledgement: ``This product includes software developed by the
8: .\" University of California, Berkeley and its contributors'' in the
9: .\" documentation or other materials provided with the distribution and in
10: .\" all advertising materials mentioning features or use of this software.
11: .\" Neither the name of the University nor the names of its contributors may
12: .\" be used to endorse or promote products derived from this software without
13: .\" specific prior written permission.
14: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
15: .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
16: .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
17: .\"
18: .\" @(#)vis.3 5.6 (Berkeley) 6/23/90
19: .\"
20: .TH VIS 3 "June 23, 1990"
21: .UC 7
22: .SH NAME
23: vis \- visually encode characters
24: .SH SYNOPSIS
25: .nf
26: .ft B
27: #include <vis.h>
28:
29: char *vis(dst, c, flag, nextc)
30: char *dst, c, nextc;
31: int flag;
32:
33: int strvis(dst, src, flag)
34: char *dst, *src;
35: int flag;
36:
37: int strvisx(dst, src, len, flag)
38: char *dst, *src;
39: int len, flag;
40:
41: .ft R
42: .fi
43: .SH DESCRIPTION
44: .I Vis
45: copies into dst a string which represents the character c. If
46: c needs no encoding, it is copied in unaltered. The string is
47: null terminated, and a pointer to the end of the string is
48: returned. The maximum length of any encoding is four
49: characters (not including the trailing NULL); thus, when
50: encoding a set of characters into a buffer, the size of the buffer should
51: be four times the number of characters encoded, plus one for the trailing NULL.
52: The flag parameter is used for altering the default range of
53: characters considered for encoding and for altering the visual
54: representation.
55: The additional character, nextc, is only used when selecting the
56: VIS_CSTYLE encoding format (explained below).
57: .PP
58: Strvis and strvisx copy into dst a visual representation of
59: the string src. Strvis encodes characters from src up to the
60: first NULL. Strvisx encodes exactly len characters from src (this
61: is useful for encoding a block of data that may contain NULL's).
62: Both forms NULL terminate dst. Dst must be four times the number
63: of characters encoded from src (plus one for the NULL). Both
64: forms return the number of characters in dst (not including
65: the trailing NULL).
66: .PP
67: The encoding is a unique, invertible representation comprised entirely of
68: graphic characters; it can be decoded back into the original form using
69: the unvis(3) or strunvis(3) functions.
70: .PP
71: There are two parameters that can be controlled: the range of
72: characters that are encoded, and the type
73: of representation used.
74: By default, all non-graphic characters (see isgraph(3))
75: except space, tab, and newline are encoded. The following flags
76: alter this:
77: .TP
78: VIS_SP
79: Also encode space.
80: .TP
81: VIS_TAB
82: Also encode tab.
83: .TP
84: VIS_NL
85: Also encode newline.
86: .TP
87: VIS_WHITE
88: Synonym for VIS_SP | VIS_TAB | VIS_NL.
89: .TP
90: VIS_SAFE
91: Only encode "unsafe" characters. Unsafe means control
92: characters which may cause common terminals to perform
93: unexpected functions. Currently this form allows space,
94: tab, newline, backspace, bell, and return - in addition
95: to all graphic characters - unencoded.
96: .PP
97: There are three forms of encoding.
98: All forms use the backslash character (``\e'') to introduce a special
99: sequence; two backslashes are used to represent a real backslash.
100: These are the visual formats:
101: .TP
102: (default)
103: Use an ``M'' to represent meta characters (characters with the 8th
104: bit set), and use carat (``^'') to represent control characters see
105: (\fIiscntrl\fP(3)).
106: The following formats are used:
107: .RS
108: .TP
109: \e^C
110: Represents the control character ``C''.
111: Spans characters \e000 through \e037, and \e177 (as \e^?).
112: .TP
113: \eM-C
114: Represents character ``C'' with the 8th bit set.
115: Spans characters \e241 through \e376.
116: .TP
117: \eM^C
118: Represents control character ``C'' with the 8th bit set.
119: Spans characters \e200 through \e237, and \e377 (as \eM^?).
120: .TP
121: \e040
122: Represents ACSII space.
123: .TP
124: \e240
125: Represents Meta-space.
126: .sp
127: .RE
128: .TP
129: VIS_CSTYLE
130: Use C-style backslash sequences to represent standard non-printable
131: characters.
132: The following sequences are used to represent the indicated characters:
133: .sp
134: .nf
135: \ea - BEL (007)
136: \eb - BS (010)
137: \ef - NP (014)
138: \en - NL (012)
139: \er - CR (015)
140: \et - HT (011)
141: \ev - VT (013)
142: \e0 - NUL (000)
143: .fi
144: .sp
145: When using this format, the nextc parameter is looked at to determine
146: if a NULL character can be encoded as ``\e0'' instead of ``\e000''.
147: If nextc is an octal digit, the latter representation is used to
148: avoid ambiguity.
149: .TP
150: VIS_OCTAL
151: Use a three digit octal sequence. The form is ``\eddd'' where
152: d represents an octal digit.
153: .PP
154: There is one additional flag, VIS_NOSLASH, which inhibits the
155: doubling of backslashes and the backslash before the default
156: format (that is, control characters are represented by ^C and
157: meta characters as M-C). With this flag set, the encoding is
158: ambiguous and non-invertible.
159: .SH "SEE ALSO"
160: vis(1), unvis(1), unvis(3)
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.