diff --git a/usr.man/man3/unvis.3 b/usr.man/man3/unvis.3 new file mode 100644 index 0000000..bdde430 --- /dev/null +++ b/usr.man/man3/unvis.3 @@ -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 " +.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. diff --git a/usr.man/man3/vis.3 b/usr.man/man3/vis.3 new file mode 100644 index 0000000..eb505e6 --- /dev/null +++ b/usr.man/man3/vis.3 @@ -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 " +.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. +