mirror of
https://github.com/GnoConsortium/gno.git
synced 2024-06-28 03:29:39 +00:00
vis.3, unvis.3:
initial checkin
This commit is contained in:
parent
25b2576666
commit
a2225ddb83
167
usr.man/man3/unvis.3
Normal file
167
usr.man/man3/unvis.3
Normal file
|
@ -0,0 +1,167 @@
|
||||||
|
.\" Copyright (c) 1989, 1991, 1993
|
||||||
|
.\" The Regents of the University of California. All rights reserved.
|
||||||
|
.\"
|
||||||
|
.\" Redistribution and use in source and binary forms, with or without
|
||||||
|
.\" modification, are permitted provided that the following conditions
|
||||||
|
.\" are met:
|
||||||
|
.\" 1. Redistributions of source code must retain the above copyright
|
||||||
|
.\" notice, this list of conditions and the following disclaimer.
|
||||||
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||||
|
.\" notice, this list of conditions and the following disclaimer in the
|
||||||
|
.\" documentation and/or other materials provided with the distribution.
|
||||||
|
.\" 3. All advertising materials mentioning features or use of this software
|
||||||
|
.\" must display the following acknowledgement:
|
||||||
|
.\" This product includes software developed by the University of
|
||||||
|
.\" California, Berkeley and its contributors.
|
||||||
|
.\" 4. Neither the name of the University nor the names of its contributors
|
||||||
|
.\" may be used to endorse or promote products derived from this software
|
||||||
|
.\" without specific prior written permission.
|
||||||
|
.\"
|
||||||
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
||||||
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||||
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||||
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
||||||
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||||||
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
||||||
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||||||
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
||||||
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
||||||
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||||||
|
.\" SUCH DAMAGE.
|
||||||
|
.\"
|
||||||
|
.\" @(#)unvis.3 8.2 (Berkeley) 12/11/93
|
||||||
|
.\"
|
||||||
|
.TH UNVIS 3 "3 January 1999" GNO "Library Routines"
|
||||||
|
.SH NAME
|
||||||
|
.BR unvis ,
|
||||||
|
.BR strunvis
|
||||||
|
\- decode a visual representation of characters
|
||||||
|
.SH SYNOPSIS
|
||||||
|
.BR "#include <vis.h>"
|
||||||
|
.sp 1
|
||||||
|
int
|
||||||
|
.BR unvis
|
||||||
|
.RI "(char *" cp ,
|
||||||
|
.RI "int " c ,
|
||||||
|
.RI "int *" astate ,
|
||||||
|
.RI "int " flag )
|
||||||
|
.br
|
||||||
|
int
|
||||||
|
.BR strunvis
|
||||||
|
.RI "(char *" dst ,
|
||||||
|
.RI "const char *" src )
|
||||||
|
.SH DESCRIPTION
|
||||||
|
The
|
||||||
|
.BR unvis
|
||||||
|
and
|
||||||
|
.BR strunvis
|
||||||
|
functions
|
||||||
|
are used to decode a visual representation of characters, as produced
|
||||||
|
by the
|
||||||
|
.BR vis (3)
|
||||||
|
function, back into
|
||||||
|
the original form. Unvis is called with successive characters in
|
||||||
|
.IR c
|
||||||
|
until a valid
|
||||||
|
sequence is recognized, at which time the decoded character is
|
||||||
|
available at the character pointed to by
|
||||||
|
.IR cp .
|
||||||
|
Strunvis decodes the
|
||||||
|
characters pointed to by
|
||||||
|
.IR src
|
||||||
|
into the buffer pointed to by
|
||||||
|
.IR dst .
|
||||||
|
.PP
|
||||||
|
The
|
||||||
|
.BR strunvis
|
||||||
|
function
|
||||||
|
simply copies
|
||||||
|
.IR src
|
||||||
|
to
|
||||||
|
.IR dst ,
|
||||||
|
decoding any escape sequences along the way,
|
||||||
|
and returns the number of characters placed into
|
||||||
|
.IR dst ,
|
||||||
|
or \-1 if an
|
||||||
|
invalid escape sequence was detected. The size of
|
||||||
|
.IR dst
|
||||||
|
should be
|
||||||
|
equal to the size of
|
||||||
|
.IR src
|
||||||
|
(that is, no expansion takes place during
|
||||||
|
decoding).
|
||||||
|
.PP
|
||||||
|
The
|
||||||
|
.BR unvis
|
||||||
|
function
|
||||||
|
implements a state machine that can be used to decode an arbitrary
|
||||||
|
stream of bytes. All state associated with the bytes being decoded
|
||||||
|
is stored outside the
|
||||||
|
.BR unvis
|
||||||
|
function (that is, a pointer to the state is passed in), so
|
||||||
|
calls decoding different streams can be freely intermixed. To
|
||||||
|
start decoding a stream of bytes, first initialize an integer
|
||||||
|
to zero. Call
|
||||||
|
.BR unvis
|
||||||
|
with each successive byte, along with a pointer
|
||||||
|
to this integer, and a pointer to a destination character.
|
||||||
|
The
|
||||||
|
.BR unvis
|
||||||
|
function
|
||||||
|
has several return codes that must be handled properly. They are:
|
||||||
|
.IP "0 (zero)"
|
||||||
|
Another character is necessary; nothing has been recognized yet.
|
||||||
|
.IP UNVIS_VALID
|
||||||
|
A valid character has been recognized and is available at the location
|
||||||
|
pointed to by cp.
|
||||||
|
.IP UNVIS_VALIDPUSH
|
||||||
|
A valid character has been recognized and is available at the location
|
||||||
|
pointed to by cp; however, the character currently passed in should
|
||||||
|
be passed in again.
|
||||||
|
.IP UNVIS_NOCHAR
|
||||||
|
A valid sequence was detected, but no character was produced. This
|
||||||
|
return code is necessary to indicate a logical break between characters.
|
||||||
|
.IP UNVIS_SYNBAD
|
||||||
|
An invalid escape sequence was detected, or the decoder is in an
|
||||||
|
unknown state. The decoder is placed into the starting state.
|
||||||
|
.PP
|
||||||
|
When all bytes in the stream have been processed, call
|
||||||
|
.BR unvis
|
||||||
|
one more time with flag set to
|
||||||
|
.IR UNVIS_END
|
||||||
|
to extract any remaining character (the character passed in is ignored).
|
||||||
|
.PP
|
||||||
|
The following code fragment illustrates a proper use of
|
||||||
|
.BR unvis .
|
||||||
|
.nf
|
||||||
|
|
||||||
|
int state = 0;
|
||||||
|
char out;
|
||||||
|
|
||||||
|
while ((ch = getchar()) != EOF) {
|
||||||
|
again:
|
||||||
|
switch(unvis(&out, ch, &state, 0)) {
|
||||||
|
case 0:
|
||||||
|
case UNVIS_NOCHAR:
|
||||||
|
break;
|
||||||
|
case UNVIS_VALID:
|
||||||
|
(void) putchar(out);
|
||||||
|
break;
|
||||||
|
case UNVIS_VALIDPUSH:
|
||||||
|
(void) putchar(out);
|
||||||
|
goto again;
|
||||||
|
case UNVIS_SYNBAD:
|
||||||
|
(void)fprintf(stderr, "bad sequence!\n");
|
||||||
|
exit(1);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
if (unvis(&out, (char)0, &state, UNVIS_END) == UNVIS_VALID)
|
||||||
|
(void) putchar(out);
|
||||||
|
.fi
|
||||||
|
.SH SEE ALSO
|
||||||
|
.BR vis (1)
|
||||||
|
.SH HISTORY
|
||||||
|
The
|
||||||
|
.BR unvis
|
||||||
|
function
|
||||||
|
first appeared in 4.4BSD.
|
257
usr.man/man3/vis.3
Normal file
257
usr.man/man3/vis.3
Normal file
|
@ -0,0 +1,257 @@
|
||||||
|
.\" Copyright (c) 1989, 1991, 1993
|
||||||
|
.\" The Regents of the University of California. All rights reserved.
|
||||||
|
.\"
|
||||||
|
.\" Redistribution and use in source and binary forms, with or without
|
||||||
|
.\" modification, are permitted provided that the following conditions
|
||||||
|
.\" are met:
|
||||||
|
.\" 1. Redistributions of source code must retain the above copyright
|
||||||
|
.\" notice, this list of conditions and the following disclaimer.
|
||||||
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||||
|
.\" notice, this list of conditions and the following disclaimer in the
|
||||||
|
.\" documentation and/or other materials provided with the distribution.
|
||||||
|
.\" 3. All advertising materials mentioning features or use of this software
|
||||||
|
.\" must display the following acknowledgement:
|
||||||
|
.\" This product includes software developed by the University of
|
||||||
|
.\" California, Berkeley and its contributors.
|
||||||
|
.\" 4. Neither the name of the University nor the names of its contributors
|
||||||
|
.\" may be used to endorse or promote products derived from this software
|
||||||
|
.\" without specific prior written permission.
|
||||||
|
.\"
|
||||||
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
||||||
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||||
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||||
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
||||||
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||||||
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
||||||
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||||||
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
||||||
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
||||||
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||||||
|
.\" SUCH DAMAGE.
|
||||||
|
.\"
|
||||||
|
.\" From: @(#)vis.3 8.1 (Berkeley) 6/9/93
|
||||||
|
.\" $Id: vis.3,v 1.1 1999/01/07 05:17:24 gdr-ftp Exp $
|
||||||
|
.\"
|
||||||
|
.TH VIS 3 "3 January 1999" GNO "Library Routines"
|
||||||
|
.SH NAME
|
||||||
|
.BR vis
|
||||||
|
\- visually encode characters
|
||||||
|
.SH SYNOPSIS
|
||||||
|
.BR "#include <vis.h>"
|
||||||
|
.sp 1
|
||||||
|
char *\fBvis\fR
|
||||||
|
.RI "(char *" dst ,
|
||||||
|
.RI "int " c ,
|
||||||
|
.RI "int " flag ,
|
||||||
|
.RI "int " nextc );
|
||||||
|
.br
|
||||||
|
int
|
||||||
|
.BR strvis
|
||||||
|
.RI "(char *" dst ,
|
||||||
|
.RI "const char *" src ,
|
||||||
|
.RI "int " flag );
|
||||||
|
.br
|
||||||
|
int
|
||||||
|
.BR strvisx
|
||||||
|
.RI "(char *" dst ,
|
||||||
|
.RI "const char *" src ,
|
||||||
|
.RI "size_t " len ,
|
||||||
|
.RI "int " flag );
|
||||||
|
.SH DESCRIPTION
|
||||||
|
The
|
||||||
|
.BR vis
|
||||||
|
function copies into
|
||||||
|
.IR dst
|
||||||
|
a string which represents the character
|
||||||
|
.IR c .
|
||||||
|
If
|
||||||
|
.IR c
|
||||||
|
needs no encoding, it is copied in unaltered. The string is
|
||||||
|
null terminated, and a pointer to the end of the string is
|
||||||
|
returned. The maximum length of any encoding is four
|
||||||
|
characters (not including the trailing
|
||||||
|
NULL);
|
||||||
|
thus, when
|
||||||
|
encoding a set of characters into a buffer, the size of the buffer should
|
||||||
|
be four times the number of characters encoded, plus one for the trailing
|
||||||
|
NULL.
|
||||||
|
The flag parameter is used for altering the default range of
|
||||||
|
characters considered for encoding and for altering the visual
|
||||||
|
representation.
|
||||||
|
The additional character,
|
||||||
|
.IR nextc ,
|
||||||
|
is only used when selecting the
|
||||||
|
.IR VIS_CSTYLE
|
||||||
|
encoding format (explained below).
|
||||||
|
.PP
|
||||||
|
The
|
||||||
|
.BR strvis
|
||||||
|
and
|
||||||
|
.BR strvisx
|
||||||
|
functions copy into
|
||||||
|
.IR dst
|
||||||
|
a visual representation of
|
||||||
|
the string
|
||||||
|
.IR src .
|
||||||
|
The
|
||||||
|
.BR strvis
|
||||||
|
function encodes characters from
|
||||||
|
.IR src
|
||||||
|
up to the
|
||||||
|
first
|
||||||
|
NULL.
|
||||||
|
The
|
||||||
|
.BR strvisx
|
||||||
|
function encodes exactly
|
||||||
|
.IR len
|
||||||
|
characters from
|
||||||
|
.IR src
|
||||||
|
(this
|
||||||
|
is useful for encoding a block of data that may contain
|
||||||
|
NULL's).
|
||||||
|
Both forms
|
||||||
|
NULL
|
||||||
|
terminate
|
||||||
|
.IR dst .
|
||||||
|
The size of
|
||||||
|
.IR dst
|
||||||
|
must be four times the number
|
||||||
|
of characters encoded from
|
||||||
|
.IR src
|
||||||
|
(plus one for the
|
||||||
|
NULL).
|
||||||
|
Both
|
||||||
|
forms return the number of characters in dst (not including
|
||||||
|
the trailing
|
||||||
|
NULL).
|
||||||
|
.PP
|
||||||
|
The encoding is a unique, invertible representation comprised entirely of
|
||||||
|
graphic characters; it can be decoded back into the original form using
|
||||||
|
the
|
||||||
|
.BR unvis (3)
|
||||||
|
or
|
||||||
|
.BR strunvis (3)
|
||||||
|
functions.
|
||||||
|
.PP
|
||||||
|
There are two parameters that can be controlled: the range of
|
||||||
|
characters that are encoded, and the type
|
||||||
|
of representation used.
|
||||||
|
By default, all non-graphic characters.
|
||||||
|
except space, tab, and newline are encoded.
|
||||||
|
(See
|
||||||
|
.BR isgraph (3).)
|
||||||
|
The following flags
|
||||||
|
alter this:
|
||||||
|
.IP VIS_SP
|
||||||
|
Also encode space.
|
||||||
|
.IP VIS_TAB
|
||||||
|
Also encode tab.
|
||||||
|
.IP VIS_NL
|
||||||
|
Also encode newline.
|
||||||
|
.IP VIS_WHITE
|
||||||
|
Synonym for
|
||||||
|
VIS_SP
|
||||||
|
\&|
|
||||||
|
VIS_TAB
|
||||||
|
\&|
|
||||||
|
VIS_NL .
|
||||||
|
.IP VIS_SAFE
|
||||||
|
Only encode "unsafe" characters. Unsafe means control
|
||||||
|
characters which may cause common terminals to perform
|
||||||
|
unexpected functions. Currently this form allows space,
|
||||||
|
tab, newline, backspace, bell, and return - in addition
|
||||||
|
to all graphic characters - unencoded.
|
||||||
|
.PP
|
||||||
|
There are three forms of encoding.
|
||||||
|
All forms use the backslash character '\e' to introduce a special
|
||||||
|
sequence; two backslashes are used to represent a real backslash.
|
||||||
|
These are the visual formats:
|
||||||
|
.de zb
|
||||||
|
.br
|
||||||
|
.in +0.8i
|
||||||
|
..
|
||||||
|
.de ze
|
||||||
|
.sp 1
|
||||||
|
.in -0.8i
|
||||||
|
..
|
||||||
|
.IP (default)
|
||||||
|
Use an 'M'
|
||||||
|
to represent meta characters (characters with the 8th
|
||||||
|
bit set), and use carat
|
||||||
|
.BR ^
|
||||||
|
to represent control characters see
|
||||||
|
.BR iscntrl (3).
|
||||||
|
The following formats are used:
|
||||||
|
.sp 1
|
||||||
|
\e^C
|
||||||
|
.zb
|
||||||
|
Represents the control character
|
||||||
|
.BR C .
|
||||||
|
Spans characters '\e000' through '\e037',
|
||||||
|
and '\e177' (as '\e^?').
|
||||||
|
.ze
|
||||||
|
\eM-C
|
||||||
|
.zb
|
||||||
|
Represents character
|
||||||
|
.RB ' C '
|
||||||
|
with the 8th bit set.
|
||||||
|
Spans characters '\e241'
|
||||||
|
through '\e376'.
|
||||||
|
.ze
|
||||||
|
\eM^C
|
||||||
|
.zb
|
||||||
|
Represents control character
|
||||||
|
.BR C
|
||||||
|
with the 8th bit set.
|
||||||
|
Spans characters '\e200' through '\e237', and '\e377' (as '\eM^?').
|
||||||
|
.ze
|
||||||
|
\e040
|
||||||
|
.zb
|
||||||
|
Represents ASCII space.
|
||||||
|
.ze
|
||||||
|
\e240
|
||||||
|
.zb
|
||||||
|
Represents Meta-space.
|
||||||
|
.ze
|
||||||
|
.IP VIS_CSTYLE
|
||||||
|
Use C-style backslash sequences to represent standard non-printable
|
||||||
|
characters.
|
||||||
|
The following sequences are used to represent the indicated characters:
|
||||||
|
.nf
|
||||||
|
|
||||||
|
\\a - BEL (007)
|
||||||
|
\\b - BS (010)
|
||||||
|
\\f - NP (014)
|
||||||
|
\\n - NL (012)
|
||||||
|
\\r - CR (015)
|
||||||
|
\\t - HT (011)
|
||||||
|
\\v - VT (013)
|
||||||
|
\\0 - NULL (000)
|
||||||
|
|
||||||
|
.fi
|
||||||
|
.sp 1
|
||||||
|
When using this format, the nextc parameter is looked at to determine
|
||||||
|
if a NULL character can be encoded as '\\0' instead of '\\000'. If
|
||||||
|
.IR nextc
|
||||||
|
is an octal digit, the latter representation is used to
|
||||||
|
avoid ambiguity.
|
||||||
|
.IP VIS_OCTAL
|
||||||
|
Use a three digit octal sequence. The form is '\\ddd' where
|
||||||
|
.IR d
|
||||||
|
represents an octal digit.
|
||||||
|
.PP
|
||||||
|
There is one additional flag,
|
||||||
|
.IR VIS_NOSLASH ,
|
||||||
|
which inhibits the
|
||||||
|
doubling of backslashes and the backslash before the default
|
||||||
|
format (that is, control characters are represented by '^C'
|
||||||
|
and meta characters as 'M-C').
|
||||||
|
With this flag set, the encoding is
|
||||||
|
ambiguous and non-invertible.
|
||||||
|
.SH SEE ALSO
|
||||||
|
.BR unvis (1),
|
||||||
|
.BR strunvis (3),
|
||||||
|
.BR unvis (3)
|
||||||
|
.SH HISTORY
|
||||||
|
These functions first appeared in 4.4BSD.
|
||||||
|
|
Loading…
Reference in New Issue
Block a user