Deleted Added
sdiff udiff text old ( 244401 ) new ( 248302 )
full compact
vis.3 (244401) vis.3 (248302)
1.\" $NetBSD: vis.3,v 1.29 2012/12/14 22:55:59 christos Exp $
2.\" $FreeBSD: head/contrib/libc-vis/vis.3 244401 2012-12-18 16:37:24Z brooks $
1.\" $NetBSD: vis.3,v 1.39 2013/02/20 20:05:26 christos Exp $
2.\" $FreeBSD: head/contrib/libc-vis/vis.3 248302 2013-03-14 23:51:47Z brooks $
3.\"
4.\" Copyright (c) 1989, 1991, 1993
5.\" The Regents of the University of California. All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright

--- 14 unchanged lines hidden (view full) ---

25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29.\" SUCH DAMAGE.
30.\"
31.\" @(#)vis.3 8.1 (Berkeley) 6/9/93
32.\"
3.\"
4.\" Copyright (c) 1989, 1991, 1993
5.\" The Regents of the University of California. All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright

--- 14 unchanged lines hidden (view full) ---

25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29.\" SUCH DAMAGE.
30.\"
31.\" @(#)vis.3 8.1 (Berkeley) 6/9/93
32.\"
33.Dd December 14, 2012
33.Dd February 19, 2013
34.Dt VIS 3
35.Os
36.Sh NAME
37.Nm vis ,
38.Nm nvis ,
39.Nm strvis ,
40.Nm strnvis ,
41.Nm strvisx ,
42.Nm strnvisx ,
34.Dt VIS 3
35.Os
36.Sh NAME
37.Nm vis ,
38.Nm nvis ,
39.Nm strvis ,
40.Nm strnvis ,
41.Nm strvisx ,
42.Nm strnvisx ,
43.Nm strenvisx ,
43.Nm svis ,
44.Nm snvis ,
45.Nm strsvis ,
46.Nm strsnvis ,
44.Nm svis ,
45.Nm snvis ,
46.Nm strsvis ,
47.Nm strsnvis ,
47.Nm strsvisx
48.Nm strsnvisx
48.Nm strsvisx ,
49.Nm strsnvisx ,
50.Nm strsenvisx
49.Nd visually encode characters
50.Sh LIBRARY
51.Lb libc
52.Sh SYNOPSIS
53.In vis.h
54.Ft char *
55.Fn vis "char *dst" "int c" "int flag" "int nextc"
56.Ft char *
57.Fn nvis "char *dst" "size_t dlen" "int c" "int flag" "int nextc"
58.Ft int
59.Fn strvis "char *dst" "const char *src" "int flag"
60.Ft int
61.Fn strnvis "char *dst" "size_t dlen" "const char *src" "int flag"
62.Ft int
63.Fn strvisx "char *dst" "const char *src" "size_t len" "int flag"
64.Ft int
65.Fn strnvisx "char *dst" "size_t dlen" "const char *src" "size_t len" "int flag"
51.Nd visually encode characters
52.Sh LIBRARY
53.Lb libc
54.Sh SYNOPSIS
55.In vis.h
56.Ft char *
57.Fn vis "char *dst" "int c" "int flag" "int nextc"
58.Ft char *
59.Fn nvis "char *dst" "size_t dlen" "int c" "int flag" "int nextc"
60.Ft int
61.Fn strvis "char *dst" "const char *src" "int flag"
62.Ft int
63.Fn strnvis "char *dst" "size_t dlen" "const char *src" "int flag"
64.Ft int
65.Fn strvisx "char *dst" "const char *src" "size_t len" "int flag"
66.Ft int
67.Fn strnvisx "char *dst" "size_t dlen" "const char *src" "size_t len" "int flag"
68.Ft int
69.Fn strenvisx "char *dst" "size_t dlen" "const char *src" "size_t len" "int flag" "int *cerr_ptr"
66.Ft char *
67.Fn svis "char *dst" "int c" "int flag" "int nextc" "const char *extra"
68.Ft char *
69.Fn snvis "char *dst" "size_t dlen" "int c" "int flag" "int nextc" "const char *extra"
70.Ft int
71.Fn strsvis "char *dst" "const char *src" "int flag" "const char *extra"
72.Ft int
73.Fn strsnvis "char *dst" "size_t dlen" "const char *src" "int flag" "const char *extra"
74.Ft int
75.Fn strsvisx "char *dst" "const char *src" "size_t len" "int flag" "const char *extra"
76.Ft int
77.Fn strsnvisx "char *dst" "size_t dlen" "const char *src" "size_t len" "int flag" "const char *extra"
70.Ft char *
71.Fn svis "char *dst" "int c" "int flag" "int nextc" "const char *extra"
72.Ft char *
73.Fn snvis "char *dst" "size_t dlen" "int c" "int flag" "int nextc" "const char *extra"
74.Ft int
75.Fn strsvis "char *dst" "const char *src" "int flag" "const char *extra"
76.Ft int
77.Fn strsnvis "char *dst" "size_t dlen" "const char *src" "int flag" "const char *extra"
78.Ft int
79.Fn strsvisx "char *dst" "const char *src" "size_t len" "int flag" "const char *extra"
80.Ft int
81.Fn strsnvisx "char *dst" "size_t dlen" "const char *src" "size_t len" "int flag" "const char *extra"
82.Ft int
83.Fn strsenvisx "char *dst" "size_t dlen" "const char *src" "size_t len" "int flag" "const char *extra" "int *cerr_ptr"
78.Sh DESCRIPTION
79The
80.Fn vis
81function
82copies into
83.Fa dst
84a string which represents the character
85.Fa c .
86If
87.Fa c
88needs no encoding, it is copied in unaltered.
89The string is null terminated, and a pointer to the end of the string is
90returned.
91The maximum length of any encoding is four
84.Sh DESCRIPTION
85The
86.Fn vis
87function
88copies into
89.Fa dst
90a string which represents the character
91.Fa c .
92If
93.Fa c
94needs no encoding, it is copied in unaltered.
95The string is null terminated, and a pointer to the end of the string is
96returned.
97The maximum length of any encoding is four
92characters (not including the trailing
98bytes (not including the trailing
93.Dv NUL ) ;
94thus, when
95encoding a set of characters into a buffer, the size of the buffer should
99.Dv NUL ) ;
100thus, when
101encoding a set of characters into a buffer, the size of the buffer should
96be four times the number of characters encoded, plus one for the trailing
102be four times the number of bytes encoded, plus one for the trailing
97.Dv NUL .
98The flag parameter is used for altering the default range of
99characters considered for encoding and for altering the visual
100representation.
101The additional character,
102.Fa nextc ,
103is only used when selecting the
104.Dv VIS_CSTYLE

--- 32 unchanged lines hidden (view full) ---

137.Dv NUL Ns 's ) .
138Both forms
139.Dv NUL
140terminate
141.Fa dst .
142The size of
143.Fa dst
144must be four times the number
103.Dv NUL .
104The flag parameter is used for altering the default range of
105characters considered for encoding and for altering the visual
106representation.
107The additional character,
108.Fa nextc ,
109is only used when selecting the
110.Dv VIS_CSTYLE

--- 32 unchanged lines hidden (view full) ---

143.Dv NUL Ns 's ) .
144Both forms
145.Dv NUL
146terminate
147.Fa dst .
148The size of
149.Fa dst
150must be four times the number
145of characters encoded from
151of bytes encoded from
146.Fa src
147(plus one for the
148.Dv NUL ) .
149Both
152.Fa src
153(plus one for the
154.Dv NUL ) .
155Both
150forms return the number of characters in dst (not including
151the trailing
156forms return the number of characters in
157.Fa dst
158(not including the trailing
152.Dv NUL ) .
153The
159.Dv NUL ) .
160The
154.Dq n
161.Dq Nm n
155versions of the functions also take an additional argument
156.Fa dlen
157that indicates the length of the
158.Fa dst
159buffer.
160If
161.Fa dlen
162versions of the functions also take an additional argument
163.Fa dlen
164that indicates the length of the
165.Fa dst
166buffer.
167If
168.Fa dlen
162is not large enough to fix the converted string then the
169is not large enough to fit the converted string then the
163.Fn strnvis
164and
165.Fn strnvisx
166functions return \-1 and set
167.Va errno
168to
169.Dv ENOSPC .
170.Fn strnvis
171and
172.Fn strnvisx
173functions return \-1 and set
174.Va errno
175to
176.Dv ENOSPC .
177The
178.Fn strenvisx
179function takes an additional argument,
180.Fa cerr_ptr ,
181that is used to pass in and out a multibyte conversion error flag.
182This is useful when processing single characters at a time when
183it is possible that the locale may be set to something other
184than the locale of the characters in the input data.
170.Pp
171The functions
172.Fn svis ,
173.Fn snvis ,
174.Fn strsvis ,
175.Fn strsnvis ,
176.Fn strsvisx ,
185.Pp
186The functions
187.Fn svis ,
188.Fn snvis ,
189.Fn strsvis ,
190.Fn strsnvis ,
191.Fn strsvisx ,
192.Fn strsnvisx ,
177and
193and
178.Fn strsnvisx
194.Fn strsenvisx
179correspond to
180.Fn vis ,
181.Fn nvis ,
182.Fn strvis ,
183.Fn strnvis ,
184.Fn strvisx ,
195correspond to
196.Fn vis ,
197.Fn nvis ,
198.Fn strvis ,
199.Fn strnvis ,
200.Fn strvisx ,
201.Fn strnvisx ,
185and
202and
186.Fn strnvisx
203.Fn strenvisx
187but have an additional argument
188.Fa extra ,
189pointing to a
190.Dv NUL
191terminated list of characters.
192These characters will be copied encoded or backslash-escaped into
193.Fa dst .
194These functions are useful e.g. to remove the special meaning

--- 14 unchanged lines hidden (view full) ---

209.Fn nvis ,
210.Fn strvis ,
211.Fn strnvis ,
212.Fn strvisx ,
213and
214.Fn strnvisx ) ,
215and the type of representation used.
216By default, all non-graphic characters,
204but have an additional argument
205.Fa extra ,
206pointing to a
207.Dv NUL
208terminated list of characters.
209These characters will be copied encoded or backslash-escaped into
210.Fa dst .
211These functions are useful e.g. to remove the special meaning

--- 14 unchanged lines hidden (view full) ---

226.Fn nvis ,
227.Fn strvis ,
228.Fn strnvis ,
229.Fn strvisx ,
230and
231.Fn strnvisx ) ,
232and the type of representation used.
233By default, all non-graphic characters,
217except space, tab, and newline are encoded.
218(See
219.Xr isgraph 3 . )
234except space, tab, and newline are encoded (see
235.Xr isgraph 3 ) .
220The following flags
221alter this:
222.Bl -tag -width VIS_WHITEX
223.It Dv VIS_GLOB
236The following flags
237alter this:
238.Bl -tag -width VIS_WHITEX
239.It Dv VIS_GLOB
224Also encode magic characters
240Also encode the magic characters
225.Ql ( * ,
226.Ql \&? ,
227.Ql \&[
228and
229.Ql # )
230recognized by
231.Xr glob 3 .
232.It Dv VIS_SP

--- 5 unchanged lines hidden (view full) ---

238.It Dv VIS_WHITE
239Synonym for
240.Dv VIS_SP
241\&|
242.Dv VIS_TAB
243\&|
244.Dv VIS_NL .
245.It Dv VIS_SAFE
241.Ql ( * ,
242.Ql \&? ,
243.Ql \&[
244and
245.Ql # )
246recognized by
247.Xr glob 3 .
248.It Dv VIS_SP

--- 5 unchanged lines hidden (view full) ---

254.It Dv VIS_WHITE
255Synonym for
256.Dv VIS_SP
257\&|
258.Dv VIS_TAB
259\&|
260.Dv VIS_NL .
261.It Dv VIS_SAFE
246Only encode "unsafe" characters.
262Only encode
263.Dq unsafe
264characters.
247Unsafe means control characters which may cause common terminals to perform
248unexpected functions.
249Currently this form allows space, tab, newline, backspace, bell, and
265Unsafe means control characters which may cause common terminals to perform
266unexpected functions.
267Currently this form allows space, tab, newline, backspace, bell, and
250return - in addition to all graphic characters - unencoded.
268return \(em in addition to all graphic characters \(em unencoded.
251.El
252.Pp
253(The above flags have no effect for
254.Fn svis ,
255.Fn snvis ,
256.Fn strsvis ,
257.Fn strsnvis ,
258.Fn strsvisx ,

--- 23 unchanged lines hidden (view full) ---

282These are the visual formats:
283.Bl -tag -width VIS_CSTYLE
284.It (default)
285Use an
286.Ql M
287to represent meta characters (characters with the 8th
288bit set), and use caret
289.Ql ^
269.El
270.Pp
271(The above flags have no effect for
272.Fn svis ,
273.Fn snvis ,
274.Fn strsvis ,
275.Fn strsnvis ,
276.Fn strsvisx ,

--- 23 unchanged lines hidden (view full) ---

300These are the visual formats:
301.Bl -tag -width VIS_CSTYLE
302.It (default)
303Use an
304.Ql M
305to represent meta characters (characters with the 8th
306bit set), and use caret
307.Ql ^
290to represent control characters see
291.Pf ( Xr iscntrl 3 ) .
308to represent control characters (see
309.Xr iscntrl 3 ) .
292The following formats are used:
293.Bl -tag -width xxxxx
294.It Dv \e^C
295Represents the control character
296.Ql C .
297Spans characters
298.Ql \e000
299through

--- 30 unchanged lines hidden (view full) ---

330Represents Meta-space.
331.El
332.Pp
333.It Dv VIS_CSTYLE
334Use C-style backslash sequences to represent standard non-printable
335characters.
336The following sequences are used to represent the indicated characters:
337.Bd -unfilled -offset indent
310The following formats are used:
311.Bl -tag -width xxxxx
312.It Dv \e^C
313Represents the control character
314.Ql C .
315Spans characters
316.Ql \e000
317through

--- 30 unchanged lines hidden (view full) ---

348Represents Meta-space.
349.El
350.Pp
351.It Dv VIS_CSTYLE
352Use C-style backslash sequences to represent standard non-printable
353characters.
354The following sequences are used to represent the indicated characters:
355.Bd -unfilled -offset indent
338.Li \ea Tn - BEL No (007)
339.Li \eb Tn - BS No (010)
340.Li \ef Tn - NP No (014)
341.Li \en Tn - NL No (012)
342.Li \er Tn - CR No (015)
343.Li \es Tn - SP No (040)
344.Li \et Tn - HT No (011)
345.Li \ev Tn - VT No (013)
346.Li \e0 Tn - NUL No (000)
356.Li \ea Tn \(em BEL No (007)
357.Li \eb Tn \(em BS No (010)
358.Li \ef Tn \(em NP No (014)
359.Li \en Tn \(em NL No (012)
360.Li \er Tn \(em CR No (015)
361.Li \es Tn \(em SP No (040)
362.Li \et Tn \(em HT No (011)
363.Li \ev Tn \(em VT No (013)
364.Li \e0 Tn \(em NUL No (000)
347.Ed
348.Pp
365.Ed
366.Pp
349When using this format, the nextc parameter is looked at to determine
350if a
367When using this format, the
368.Fa nextc
369parameter is looked at to determine if a
351.Dv NUL
352character can be encoded as
353.Ql \e0
354instead of
355.Ql \e000 .
356If
357.Fa nextc
358is an octal digit, the latter representation is used to

--- 10 unchanged lines hidden (view full) ---

369The form is
370.Ql %xx
371where
372.Em x
373represents a lower case hexadecimal digit.
374.It Dv VIS_MIMESTYLE
375Use MIME Quoted-Printable encoding as described in RFC 2045, only don't
376break lines and don't handle CRLF.
370.Dv NUL
371character can be encoded as
372.Ql \e0
373instead of
374.Ql \e000 .
375If
376.Fa nextc
377is an octal digit, the latter representation is used to

--- 10 unchanged lines hidden (view full) ---

388The form is
389.Ql %xx
390where
391.Em x
392represents a lower case hexadecimal digit.
393.It Dv VIS_MIMESTYLE
394Use MIME Quoted-Printable encoding as described in RFC 2045, only don't
395break lines and don't handle CRLF.
377The form is:
378.Ql %XX
396The form is
397.Ql =XX
379where
380.Em X
381represents an upper case hexadecimal digit.
382.El
383.Pp
384There is one additional flag,
385.Dv VIS_NOSLASH ,
386which inhibits the
387doubling of backslashes and the backslash before the default
388format (that is, control characters are represented by
389.Ql ^C
390and
391meta characters as
392.Ql M-C ) .
393With this flag set, the encoding is
394ambiguous and non-invertible.
398where
399.Em X
400represents an upper case hexadecimal digit.
401.El
402.Pp
403There is one additional flag,
404.Dv VIS_NOSLASH ,
405which inhibits the
406doubling of backslashes and the backslash before the default
407format (that is, control characters are represented by
408.Ql ^C
409and
410meta characters as
411.Ql M-C ) .
412With this flag set, the encoding is
413ambiguous and non-invertible.
414.Sh MULTIBYTE CHARACTER SUPPORT
415These functions support multibyte character input.
416The encoding conversion is influenced by the setting of the
417.Ev LC_CTYPE
418environment variable which defines the set of characters
419that can be copied without encoding.
420.Pp
421When 8-bit data is present in the input,
422.Ev LC_CTYPE
423must be set to the correct locale or to the C locale.
424If the locales of the data and the conversion are mismatched,
425multibyte character recognition may fail and encoding will be performed
426byte-by-byte instead.
427.Pp
428As noted above,
429.Fa dst
430must be four times the number of bytes processed from
431.Fa src .
432But note that each multibyte character can be up to
433.Dv MB_LEN_MAX
434bytes
435.\" (see
436.\" .Xr multibyte 3 )
437so in terms of multibyte characters,
438.Fa dst
439must be four times
440.Dv MB_LEN_MAX
441times the number of characters processed from
442.Fa src .
443.Sh ENVIRONMENT
444.Bl -tag -width ".Ev LC_CTYPE"
445.It Ev LC_CTYPE
446Specify the locale of the input data.
447Set to C if the input data locale is unknown.
448.El
395.Sh ERRORS
396The functions
397.Fn nvis
398and
399.Fn snvis
400will return
401.Dv NULL
402and the functions
403.Fn strnvis ,
404.Fn strnvisx ,
405.Fn strsnvis ,
406and
407.Fn strsnvisx ,
408will return \-1 when the
409.Fa dlen
449.Sh ERRORS
450The functions
451.Fn nvis
452and
453.Fn snvis
454will return
455.Dv NULL
456and the functions
457.Fn strnvis ,
458.Fn strnvisx ,
459.Fn strsnvis ,
460and
461.Fn strsnvisx ,
462will return \-1 when the
463.Fa dlen
410destination buffer length size is not enough to perform the conversion while
464destination buffer size is not enough to perform the conversion while
411setting
412.Va errno
413to:
465setting
466.Va errno
467to:
414.Bl -tag -width Er
468.Bl -tag -width ".Bq Er ENOSPC"
415.It Bq Er ENOSPC
416The destination buffer size is not large enough to perform the conversion.
417.El
418.Sh SEE ALSO
419.Xr unvis 1 ,
420.Xr vis 1 ,
421.Xr glob 3 ,
469.It Bq Er ENOSPC
470The destination buffer size is not large enough to perform the conversion.
471.El
472.Sh SEE ALSO
473.Xr unvis 1 ,
474.Xr vis 1 ,
475.Xr glob 3 ,
476.\" .Xr multibyte 3 ,
422.Xr unvis 3
423.Rs
424.%A T. Berners-Lee
425.%T Uniform Resource Locators (URL)
477.Xr unvis 3
478.Rs
479.%A T. Berners-Lee
480.%T Uniform Resource Locators (URL)
426.%O RFC1738
481.%O "RFC 1738"
427.Re
482.Re
483.Rs
484.%T "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies"
485.%O "RFC 2045"
486.Re
428.Sh HISTORY
429The
430.Fn vis ,
431.Fn strvis ,
432and
487.Sh HISTORY
488The
489.Fn vis ,
490.Fn strvis ,
491and
433.Fa strvisx
492.Fn strvisx
434functions first appeared in
435.Bx 4.4 .
436The
437.Fn svis ,
438.Fn strsvis ,
439and
440.Fn strsvisx
441functions appeared in
442.Nx 1.5
443and
493functions first appeared in
494.Bx 4.4 .
495The
496.Fn svis ,
497.Fn strsvis ,
498and
499.Fn strsvisx
500functions appeared in
501.Nx 1.5
502and
444.Fx 10.0 .
503.Fx 9.2 .
445The buffer size limited versions of the functions
446.Po Fn nvis ,
447.Fn strnvis ,
448.Fn strnvisx ,
449.Fn snvis ,
450.Fn strsnvis ,
451and
452.Fn strsnvisx Pc
453appeared in
504The buffer size limited versions of the functions
505.Po Fn nvis ,
506.Fn strnvis ,
507.Fn strnvisx ,
508.Fn snvis ,
509.Fn strsnvis ,
510and
511.Fn strsnvisx Pc
512appeared in
454.Nx 6.0
455and
513and
456.Fx 10.0 .
514.Fx 9.2 .
515Myltibyte character support was added in
516.Nx 7.0
517and
518.Fx 9.2 .