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 . |