vis(), strvis(), strvisx()

convert character to visual representation 

Function

SYNOPSIS

#include <vis.h>

char *vis(char *dst, char c, int flag, char nextc);

int strvis(char *dst, const char *src, int flag);

int strvisx(char *dst, const char *src, size_t len, int flag);

DESCRIPTION

The vis() function stores a string representing the specified character to the specified destination. If the specified character needs no encoding, it is copied 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 specified flags are used for altering the default range of characters considered for encoding and for altering the visual representation.

The strvis() and strvisx() store a visual representation of the source string in the specified destination. The strvis() function encodes characters up to the first null character. The strvisx() function encodes exactly the specified number of characters (this is useful for encoding a block of data that may not contain nulls). Both forms null terminate the destination. The size of the destination must be four times the number of characters encoded, plus one for the trailing null. Both forms return the number of characters stored, not including the trailing null.

The encoding is a unique, invertible representation comprised entirely of graphic characters; it can be decoded back into the original form using the unvis() or strunvis() functions.

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. The following flags alter this:

VIS_SP 

Also encode space.

VIS_TAB 

Also encode tab.

VIS_NL 

Also encode newline.

VIS_WHITE 

Synonym for VIS_SP | VIS_TAB | VIS_NL.

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.

There are three forms of encoding. All forms use the backslash character '\' to introduce a special sequence; two backslashed are used to represent a real backslash. These are the visual formats:

<default> 

Use an 'M' to represent meta characters (characters with the 8th bit set), and use carat '^' to represent control characters (see iscntrl()). The following formats are used:

\^C 

Represents the control character 'C'. Spans characters '\000' through '\037', and '\177' (as '\^?').

\M-C 

Represents character 'C' with the 8th bit set. Spans characters '\241' through '\376'.

\M^C 

Represents control character 'C' with the 8th bit set. Spans characters '\200' through '\237', and '\377' (as '\M^?')

\040 

Represents ASCII space.

\240 

Represents meta-space.

VIS_CSTYLE 

Use C-style backslash sequences to represent standard non-printable characters. The following sequences are used to represent the indicated characters:

\a	BEL (007)
\b	BS (010)
\f	NP (014)
\n	NL (012)
\r	CR (015)
\t	HT (011)
\v	VT (013)
\0	NUL (000)

When using this format, the nextc parameter is looked at to determine if a null character chan be encoded as '\0' instead of '\000'. If nextc is an octal digit, the latter representation is used to avoid ambiguity.

VIS_OCTAL 

Use a three digit octal sequence. The form is '\ddd' where d represents an octal digit.

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.

PARAMETERS

dst 

Is the buffer into which the result of the encoding is stored.

c 

Is the character to encode.

flag 

Is one or more of the flags listed in the DESCRIPTION section, bitwise-OR'd together.

nextc 

Is the next character in the sequence, for use with VIS_CSTYLE is specified in flag.

src 

Is the source string to be encoded.

len 

Is the exact number of characters to be encoded.

RETURN VALUES

The vis() function returns a pointer to the end of the converted string. The strvis() and strvisx() function return the number of characters in the encoded destination buffer.

CONFORMANCE

4.4BSD.

MULTITHREAD SAFETY LEVEL

MT-Safe.

PORTING ISSUES

None.

AVAILABILITY

MKS Toolkit for Professional Developers
MKS Toolkit for Enterprise Developers
MKS Toolkit for Enterprise Developers 64-Bit Edition

SEE ALSO

Functions:
strunvis(), unvis()

MKS Toolkit 9.3 Documentation Build 6.