xref: /csrg-svn/lib/libc/gen/vis.3 (revision 62863)
1*62863Selan.\" Copyright (c) 1989, 1991, 1993
2*62863Selan.\"	The Regents of the University of California.  All rights reserved.
339288Smarc.\"
443571Strent.\" %sccs.include.redist.man%
539288Smarc.\"
6*62863Selan.\"     @(#)vis.3	8.1 (Berkeley) 06/09/93
739288Smarc.\"
848352Scael.Dd
948352Scael.Dt VIS 3
1048352Scael.Os
1148352Scael.Sh NAME
1248352Scael.Nm vis
1348352Scael.Nd visually encode characters
1448352Scael.Sh SYNOPSIS
1548352Scael.Fd #include <vis.h>
1648352Scael.Ft char *
1748352Scael.Fn vis "char *dst" "char c" "int flag" "char nextc"
1848352Scael.Ft int
1948352Scael.Fn strvis "char *dst" "char *src" "int flag"
2048352Scael.Ft int
2148352Scael.Fn strvisx "char *dst" "char *src" "int len" "int flag"
2248352Scael.Sh DESCRIPTION
2348352ScaelThe
2448352Scael.Fn vis
2548352Scaelfunction
2648352Scaelcopies into
2748352Scael.Fa dst
2848352Scaela string which represents the character
2948352Scael.Fa c .
3048352ScaelIf
3148352Scael.Fa c
3248352Scaelneeds no encoding, it is copied in unaltered.  The string is
3342139Smarcnull terminated, and a pointer to the end of the string is
3442438Smarcreturned.  The maximum length of any encoding is four
3548352Scaelcharacters (not including the trailing
3648352Scael.Dv NULL ) ;
3748352Scaelthus, when
3842139Smarcencoding a set of characters into a buffer, the size of the buffer should
3948352Scaelbe four times the number of characters encoded, plus one for the trailing
4048352Scael.Dv NULL .
4142139SmarcThe flag parameter is used for altering the default range of
4242139Smarccharacters considered for encoding and for altering the visual
4342139Smarcrepresentation.
4448352ScaelThe additional character,
4548352Scael.Fa nextc ,
4648352Scaelis only used when selecting the
4748352Scael.Dv VIS_CSTYLE
4848352Scaelencoding format (explained below).
4948352Scael.Pp
5048352ScaelThe
5148352Scael.Fn strvis
5248352Scaeland
5348352Scael.Fn strvisx
5448352Scaelfunctions copy into
5548352Scael.Fa dst
5648352Scaela visual representation of
5748352Scaelthe string
5848352Scael.Fa src .
5948352ScaelThe
6048352Scael.Fn strvis
6148352Scaelfunction encodes characters from
6248352Scael.Fa src
6348352Scaelup to the
6448352Scaelfirst
6548352Scael.Dv NULL .
6648352ScaelThe
6748352Scael.Fn strvisx
6848352Scaelfunction encodes exactly
6948352Scael.Fa len
7048352Scaelcharacters from
7148352Scael.Fa src
7248352Scael(this
7348352Scaelis useful for encoding a block of data that may contain
7448352Scael.Dv NULL Ns 's).
7548352ScaelBoth forms
7648352Scael.Dv NULL
7748352Scaelterminate
7848352Scael.Fa dst .
7948352ScaelThe size of
8048352Scael.Fa dst
8148352Scaelmust be four times the number
8248352Scaelof characters encoded from
8348352Scael.Fa src
8448352Scael(plus one for the
8548352Scael.Dv NULL ) .
8648352ScaelBoth
8742139Smarcforms return the number of characters in dst (not including
8848352Scaelthe trailing
8948352Scael.Dv NULL ) .
9048352Scael.Pp
9142139SmarcThe encoding is a unique, invertible representation comprised entirely of
9242139Smarcgraphic characters; it can be decoded back into the original form using
9348352Scaelthe
9448352Scael.Xr unvis 3
9548352Scaelor
9648352Scael.Xr strunvis 3
9748352Scaelfunctions.
9848352Scael.Pp
9942139SmarcThere are two parameters that can be controlled: the range of
10042139Smarccharacters that are encoded, and the type
10142139Smarcof representation used.
10248352ScaelBy default, all non-graphic characters.
10348352Scaelexcept space, tab, and newline are encoded.
10448352Scael(See
10548352Scael.Xr isgraph 3 . )
10648352ScaelThe following flags
10742139Smarcalter this:
10848352Scael.Bl -tag -width VIS_WHITEX
10948352Scael.It Dv VIS_SP
11042139SmarcAlso encode space.
11148352Scael.It Dv VIS_TAB
11242139SmarcAlso encode tab.
11348352Scael.It Dv VIS_NL
11442139SmarcAlso encode newline.
11548352Scael.It Dv VIS_WHITE
11648352ScaelSynonym for
11748352Scael.Dv VIS_SP
11848352Scael\&|
11948352Scael.Dv VIS_TAB
12048352Scael\&|
12148352Scael.Dv VIS_NL .
12248352Scael.It Dv VIS_SAFE
12342139SmarcOnly encode "unsafe" characters.  Unsafe means control
12442139Smarccharacters which may cause common terminals to perform
12542139Smarcunexpected functions.  Currently this form allows space,
12642139Smarctab, newline, backspace, bell, and return - in addition
12742139Smarcto all graphic characters - unencoded.
12848352Scael.El
12948352Scael.Pp
13042438SmarcThere are three forms of encoding.
13148352ScaelAll forms use the backslash character
13248352Scael.Ql \e
13348352Scaelto introduce a special
13441758Smarcsequence; two backslashes are used to represent a real backslash.
13542139SmarcThese are the visual formats:
13648352Scael.Bl -tag -width VIS_CSTYLE
13748352Scael.It (default)
13848352ScaelUse an
13948352Scael.Ql M
14048352Scaelto represent meta characters (characters with the 8th
14148352Scaelbit set), and use carat
14248352Scael.Ql ^
14348352Scaelto represent control characters see
14448352Scael.Pf ( Xr iscntrl 3 ) .
14542139SmarcThe following formats are used:
14648352Scael.Bl -tag -width xxxxx
14748352Scael.It Dv \e^C
14848352ScaelRepresents the control character
14948352Scael.Ql C .
15048352ScaelSpans characters
15148352Scael.Ql \e000
15248352Scaelthrough
15348352Scael.Ql \e037 ,
15448352Scaeland
15548352Scael.Ql \e177
15648352Scael(as
15748352Scael.Ql \e^? ) .
15848352Scael.It Dv \eM-C
15948352ScaelRepresents character
16048352Scael.Ql C
16148352Scaelwith the 8th bit set.
16248352ScaelSpans characters
16348352Scael.Ql \e241
16448352Scaelthrough
16548352Scael.Ql \e376 .
16648352Scael.It Dv \eM^C
16748352ScaelRepresents control character
16848352Scael.Ql C
16948352Scaelwith the 8th bit set.
17048352ScaelSpans characters
17148352Scael.Ql \e200
17248352Scaelthrough
17348352Scael.Ql \e237 ,
17448352Scaeland
17548352Scael.Ql \e377
17648352Scael(as
17748352Scael.Ql \eM^? ) .
17848352Scael.It Dv \e040
17948352ScaelRepresents
18048352Scael.Tn ASCII
18148352Scaelspace.
18248352Scael.It Dv \e240
18342139SmarcRepresents Meta-space.
18448352Scael.El
18548352Scael.Pp
18648352Scael.It Dv VIS_CSTYLE
18741758SmarcUse C-style backslash sequences to represent standard non-printable
18841758Smarccharacters.
18941758SmarcThe following sequences are used to represent the indicated characters:
19048352Scael.Bd -unfilled -offset indent
19148352Scael.Li \ea Tn  - BEL No (007)
19248352Scael.Li \eb Tn  - BS No (010)
19348352Scael.Li \ef Tn  - NP No (014)
19448352Scael.Li \en Tn  - NL No (012)
19548352Scael.Li \er Tn  - CR No (015)
19648352Scael.Li \et Tn  - HT No (011)
19748352Scael.Li \ev Tn  - VT No (013)
19848352Scael.Li \e0 Tn  - NUL No (000)
19948352Scael.Ed
20048352Scael.Pp
20142139SmarcWhen using this format, the nextc parameter is looked at to determine
20248352Scaelif a
20348352Scael.Dv NULL
20448352Scaelcharacter can be encoded as
20548352Scael.Ql \e0
20648352Scaelinstead of
20748352Scael.Ql \e000 .
20848352ScaelIf
20948352Scael.Fa nextc
21048352Scaelis an octal digit, the latter representation is used to
21142139Smarcavoid ambiguity.
21248352Scael.It Dv VIS_OCTAL
21348352ScaelUse a three digit octal sequence.  The form is
21448352Scael.Ql \eddd
21548352Scaelwhere
21648352Scael.Em d
21748352Scaelrepresents an octal digit.
21848352Scael.El
21948352Scael.Pp
22048352ScaelThere is one additional flag,
22148352Scael.Dv VIS_NOSLASH ,
22248352Scaelwhich inhibits the
22342139Smarcdoubling of backslashes and the backslash before the default
22448352Scaelformat (that is, control characters are represented by
22548352Scael.Ql ^C
22648352Scaeland
22748352Scaelmeta characters as
22848352Scael.Ql M-C ) .
22948352ScaelWith this flag set, the encoding is
23042139Smarcambiguous and non-invertible.
23148352Scael.Sh SEE ALSO
23248352Scael.Xr unvis 1 ,
23348352Scael.Xr unvis 3
23448352Scael.Xr strunvis 3
23548352Scael.Sh HISTORY
23662862SelanThese functions first appeared in 4.4BSD.
23762862Selan
238