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