4.3BSD-Reno/share/man/cat3/vis.0

VIS(3)			      1990			   VIS(3)



NNAAMMEE
     vis - visually encode characters

SSYYNNOOPPSSIISS
     ##iinncclluuddee <<vviiss..hh>>

     cchhaarr **vviiss((ddsstt,, cc,, ffllaagg,, nneexxttcc))
     cchhaarr **ddsstt,, cc,, nneexxttcc;;
     iinntt ffllaagg;;

     iinntt ssttrrvviiss((ddsstt,, ssrrcc,, ffllaagg))
     cchhaarr **ddsstt,, **ssrrcc;;
     iinntt ffllaagg;;

     iinntt ssttrrvviissxx((ddsstt,, ssrrcc,, lleenn,, ffllaagg))
     cchhaarr **ddsstt,, **ssrrcc;;
     iinntt lleenn,, ffllaagg;;


DDEESSCCRRIIPPTTIIOONN
     _V_i_s 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 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 con-
     sidered for encoding and for altering the visual representa-
     tion.  The additional character, nextc, is only used when
     selecting the VIS_CSTYLE encoding format (explained below).

     Strvis and strvisx copy into dst a visual representation of
     the string src.  Strvis encodes characters from src up to
     the first NULL.  Strvisx encodes exactly len characters from
     src (this is useful for encoding a block of data that may
     contain NULL's).  Both forms NULL terminate dst.  Dst must
     be four times the number of characters encoded from src
     (plus one for the NULL).  Both forms return the number of
     characters in dst (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(3) or
     strunvis(3) functions.

     There are two parameters that can be controlled: the range
     of characters that are encoded, and the type of representa-
     tion used. By default, all non-graphic characters (see
     isgraph(3)) except space, tab, and newline are encoded.  The
     following flags alter this:



Printed 7/27/90               June				1






VIS(3)			      1990			   VIS(3)



     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 backslashes 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 (_i_s_c_n_t_r_l(3)).  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 ACSII 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)



Printed 7/27/90               June				2






VIS(3)			      1990			   VIS(3)



	  \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 can be encoded as
	  ``\0'' instead of ``\000''.  If nextc is an octal
	  digit, the latter representation is used to avoid ambi-
	  guity.

     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.

SSEEEE AALLSSOO
     vis(1), unvis(1), unvis(3)






























Printed 7/27/90               June				3