.\" Copyright (c) 1989 The Regents of the University of California.
.\" Redistribution and use in source and binary forms are permitted
.\" provided that the above copyright notice and this paragraph are
.\" duplicated in all such forms and that any documentation,
.\" advertising materials, and other materials related to such
.\" distribution and use acknowledge that the software was developed
.\" by the University of California, Berkeley. The name of the
.\" University may not be used to endorse or promote products derived
.\" from this software without specific prior written permission.
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
.\" @(#)vis.3 5.2 (Berkeley) %G%
cencode, cdecode \- encode (decode) non-printing characters
.B char *cencode(c, cflag)
\fICencode\fP converts a non-printing character into a printable,
invertable representation; \fIcdecode\fP inverts
from that representation back to the original character.
Both functions pass through printable characters, and
are useful for filtering a stream of characters
to and from a visual representation.
By default, \fIcencode\fP considers isgraph(c), space, tab, and
newline as printable characters. Setting CENC_WHITE in
cflag causes space, tab, and newline to be
There are 3 forms of representation, and all
three can be requested, independent of each other,
since some encode only a subset
of the non-printable characters.
forms use the backslash character to introduce the visual
sequence; two backslashs are used to represent a
real backslash. The following lists the name of the form
(specified in the cflag), and a description:
Use C-style backslash sequences where possible. The following
sequences are used to represent the indicated character:
These are the only characters that are converted using CDEC_CTYPE.
The more familiar abbreviation of \\0 for NULL cannot be used since
it could be confused as another octal number if the sequence
is laid ahead of other octal digits.
Use an M to represent meta characters (chars with the 8th bit set),
and use hat (^) to represent control characters (iscntrl(c)). The
following forms are possible:
\\^C - Represents control character 'C'. Spans
characters 000 through 037, and 0177 (as \\^?).
\\M-C - Represents character 'C' with the 8th bit set.
Spans characters 0240 (241 if CENC_WHITE is set)
\\M^C - Represents control character 'C' with the 8th
bit set. Spans characters 0200 through 0237,
The only characters that cannot be displayed using CDEC_GRAPHIC
are space and meta-space, and only when CENC_WHITE is set.
Use a three digit octal sequence. The form is:
where d represents an octal digit. All non-printing characters
can be displayed in this form.
\fICencode\fP returns a pointer to a string that contains the
printable representation of the character passed in c. If the character
could not be encoded (because none of the selected formats can
encode that character), it is placed in the returned
string un-encoded. Note that if NULL is not encoded, it is placed
in the string as two nulls. If the caller expects to encounter
this situation, it suffices to always extract one character from
the returned string before checking for NULL. If CDEC_OCTAL
is selected, in addition to any other formats, this situation
can never arrise. Also, calling \fIcencode\fP with no requested formats
results in no encoding being done; however, backslashes are
Using \fIcdecode\fP to decode previously encoded data is a little
trickier. Essentially, characters are passed to \fIcdecode\fP
until the decoder recognizes a character to return. There are
five return codes which need to be handled:
The decoder is not done recognizing a control sequence; pass it
A character was recognized and has been placed in *cp.
A character was recognized and has been placed in *cp; however,
the character that was just passed in c is not yet needed.
When processing a stream of characters, the current character
A sequence which represents no character was detected.
An unrecognized backslash sequence was detected. The decoder
was automatically reset to a normal state. All characters since
the last un-escaped backslash character constitute the
When the caller is finished feeding characters to \fIcdecode\fP,
should be called one last time with dflag set to CDEC_END. This will extract
is given to illustrate using cdecode:
while ((c = getchar()) != EOF) {
switch(cdecode((char)c, &nc, 0)) {
fprintf(stderr, "Bad sequence\n");
if (cdecode((char)0, &nc, CDEC_END) == CDEC_OK)
projects / unix-history / blob