char
*
vis(
char *dst
, int c
, int flag
, int nextc
)
int
strvis(
char *dst
, const char *src
, int flag
)
int
strvisx(
char *dst
, const char *src
, size_t len
, int flag
)
char
*
svis(
char *dst
, int c
, int flag
, int nextc
, const char *extra
)
int
strsvis(
char *dst
, const char *src
, int flag
, const char *extra
)
int
strsvisx(
char *dst
, const char *src
, size_t len
, int flag
, const char *extra
)
)
function
copies into
dst
a string which represents the character
c
.
If
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
NUL
);
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
NUL
.
The flag parameter is used for altering the default range of
characters considered for encoding and for altering the visual
representation.
The additional character,
nextc
,
is only used when selecting the
VIS_CSTYLE
encoding format (explained below).
The
strvis()
and
strvisx(
)
functions copy into
dst
a visual representation of
the string
src
.
The
strvis()
function encodes characters from
src
up to the
first
NUL
.
The
strvisx()
function encodes exactly
len
characters from
src
(this
is useful for encoding a block of data that may contain
NUL
's).
Both forms
NUL
terminate
dst
.
The size of
dst
must be four times the number
of characters encoded from
src
(plus one for the
NUL
).
Both
forms return the number of characters in dst (not including
the trailing
NUL
).
The functions
svis(),
strsvis(
),
and
strsvisx(
)
correspond to
vis(
),
strvis(
),
and
strvisx(
)
but have an additional argument
extra
,
pointing to a
NUL
terminated list of characters.
These characters will be copied encoded or backslash-escaped into
dst
.
These functions are useful e.g. to remove the special meaning
of certain characters to shells.
The encoding is a unique, invertible representation composed entirely of graphic characters; it can be decoded back into the original form using the unvis(3) or strunvis(3) functions.
There are two parameters that can be controlled: the range of
characters that are encoded (applies only to
vis(),
strvis(
),
and
strvisx(
)),
and the type of representation used.
By default, all non-graphic characters,
except space, tab, and newline are encoded.
(See
isgraph(3).)
The following flags
alter this:
VIS_SP
VIS_TAB
VIS_NL
VIS_WHITE
VIS_SP
|
VIS_TAB
|
VIS_NL
.
VIS_SAFE
(The above flags have no effect for
svis(),
strsvis(
),
and
strsvisx(
).
When using these functions, place all graphic characters to be
encoded in an array pointed to by
extra
.
In general, the backslash character should be included in this array, see the
warning on the use of the
VIS_NOSLASH
flag below).
There are four forms of encoding.
All forms use the backslash character
`\'
to introduce a special
sequence; two backslashes are used to represent a real backslash,
except
VIS_HTTPSTYLE
that uses
`%'.
These are the visual formats:
\^C
\M-C
\M^C
\040
\240
VIS_CSTYLE
\a
- BEL (007)\b
- BS (010)\f
- NP (014)\n
- NL (012)\r
- CR (015)\s
- SP (040)\t
- HT (011)\v
- VT (013)\0
- NUL (000)
When using this format, the nextc parameter is looked at to determine
if a
NUL
character can be encoded as
`\0'
instead of
`\000'.
If
nextc
is an octal digit, the latter representation is used to
avoid ambiguity.
VIS_OCTAL
VIS_HTTPSTYLE
There is one additional flag,
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.
vis
,
strvis
,
and
strvisx
functions first appeared in
4.4BSD.
The
svis
,
strsvis
,
and
strsvisx
functions appeared in
NetBSD1.5.