| 1 |
< |
.\" $NetBSD: vis.3,v 1.29 2012/12/14 22:55:59 christos Exp $ |
| 2 |
< |
.\" $FreeBSD$ |
| 1 |
> |
.\" $NetBSD: vis.3,v 1.39 2013/02/20 20:05:26 christos Exp $ |
| 2 |
> |
.\" $FreeBSD: release/9.2.0/contrib/libc-vis/vis.3 249560 2013-04-16 19:27:09Z brooks $ |
| 3 |
|
.\" |
| 4 |
|
.\" Copyright (c) 1989, 1991, 1993 |
| 5 |
|
.\" The Regents of the University of California. All rights reserved. |
| 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 |
| 40 |
|
.Nm strnvis , |
| 41 |
|
.Nm strvisx , |
| 42 |
|
.Nm strnvisx , |
| 43 |
+ |
.Nm strenvisx , |
| 44 |
|
.Nm svis , |
| 45 |
|
.Nm snvis , |
| 46 |
|
.Nm strsvis , |
| 47 |
|
.Nm strsnvis , |
| 48 |
< |
.Nm strsvisx |
| 49 |
< |
.Nm strsnvisx |
| 48 |
> |
.Nm strsvisx , |
| 49 |
> |
.Nm strsnvisx , |
| 50 |
> |
.Nm strsenvisx |
| 51 |
|
.Nd visually encode characters |
| 52 |
|
.Sh LIBRARY |
| 53 |
|
.Lb libc |
| 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" |
| 70 |
|
.Ft char * |
| 71 |
|
.Fn svis "char *dst" "int c" "int flag" "int nextc" "const char *extra" |
| 72 |
|
.Ft char * |
| 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" |
| 84 |
|
.Sh DESCRIPTION |
| 85 |
|
The |
| 86 |
|
.Fn vis |
| 95 |
|
The string is null terminated, and a pointer to the end of the string is |
| 96 |
|
returned. |
| 97 |
|
The maximum length of any encoding is four |
| 98 |
< |
characters (not including the trailing |
| 98 |
> |
bytes (not including the trailing |
| 99 |
|
.Dv NUL ) ; |
| 100 |
|
thus, when |
| 101 |
|
encoding a set of characters into a buffer, the size of the buffer should |
| 102 |
< |
be four times the number of characters encoded, plus one for the trailing |
| 102 |
> |
be four times the number of bytes encoded, plus one for the trailing |
| 103 |
|
.Dv NUL . |
| 104 |
|
The flag parameter is used for altering the default range of |
| 105 |
|
characters considered for encoding and for altering the visual |
| 148 |
|
The size of |
| 149 |
|
.Fa dst |
| 150 |
|
must be four times the number |
| 151 |
< |
of characters encoded from |
| 151 |
> |
of bytes encoded from |
| 152 |
|
.Fa src |
| 153 |
|
(plus one for the |
| 154 |
|
.Dv NUL ) . |
| 155 |
|
Both |
| 156 |
< |
forms return the number of characters in dst (not including |
| 157 |
< |
the trailing |
| 156 |
> |
forms return the number of characters in |
| 157 |
> |
.Fa dst |
| 158 |
> |
(not including the trailing |
| 159 |
|
.Dv NUL ) . |
| 160 |
|
The |
| 161 |
< |
.Dq n |
| 161 |
> |
.Dq Nm n |
| 162 |
|
versions of the functions also take an additional argument |
| 163 |
|
.Fa dlen |
| 164 |
|
that indicates the length of the |
| 166 |
|
buffer. |
| 167 |
|
If |
| 168 |
|
.Fa dlen |
| 169 |
< |
is not large enough to fix the converted string then the |
| 169 |
> |
is not large enough to fit the converted string then the |
| 170 |
|
.Fn strnvis |
| 171 |
|
and |
| 172 |
|
.Fn strnvisx |
| 174 |
|
.Va errno |
| 175 |
|
to |
| 176 |
|
.Dv ENOSPC . |
| 177 |
+ |
The |
| 178 |
+ |
.Fn strenvisx |
| 179 |
+ |
function takes an additional argument, |
| 180 |
+ |
.Fa cerr_ptr , |
| 181 |
+ |
that is used to pass in and out a multibyte conversion error flag. |
| 182 |
+ |
This is useful when processing single characters at a time when |
| 183 |
+ |
it is possible that the locale may be set to something other |
| 184 |
+ |
than the locale of the characters in the input data. |
| 185 |
|
.Pp |
| 186 |
|
The functions |
| 187 |
|
.Fn svis , |
| 189 |
|
.Fn strsvis , |
| 190 |
|
.Fn strsnvis , |
| 191 |
|
.Fn strsvisx , |
| 192 |
+ |
.Fn strsnvisx , |
| 193 |
|
and |
| 194 |
< |
.Fn strsnvisx |
| 194 |
> |
.Fn strsenvisx |
| 195 |
|
correspond to |
| 196 |
|
.Fn vis , |
| 197 |
|
.Fn nvis , |
| 198 |
|
.Fn strvis , |
| 199 |
|
.Fn strnvis , |
| 200 |
|
.Fn strvisx , |
| 201 |
+ |
.Fn strnvisx , |
| 202 |
|
and |
| 203 |
< |
.Fn strnvisx |
| 203 |
> |
.Fn strenvisx |
| 204 |
|
but have an additional argument |
| 205 |
|
.Fa extra , |
| 206 |
|
pointing to a |
| 231 |
|
.Fn strnvisx ) , |
| 232 |
|
and the type of representation used. |
| 233 |
|
By default, all non-graphic characters, |
| 234 |
< |
except space, tab, and newline are encoded. |
| 235 |
< |
(See |
| 219 |
< |
.Xr isgraph 3 . ) |
| 234 |
> |
except space, tab, and newline are encoded (see |
| 235 |
> |
.Xr isgraph 3 ) . |
| 236 |
|
The following flags |
| 237 |
|
alter this: |
| 238 |
|
.Bl -tag -width VIS_WHITEX |
| 239 |
|
.It Dv VIS_GLOB |
| 240 |
< |
Also encode magic characters |
| 240 |
> |
Also encode the magic characters |
| 241 |
|
.Ql ( * , |
| 242 |
|
.Ql \&? , |
| 243 |
|
.Ql \&[ |
| 259 |
|
\&| |
| 260 |
|
.Dv VIS_NL . |
| 261 |
|
.It Dv VIS_SAFE |
| 262 |
< |
Only encode "unsafe" characters. |
| 262 |
> |
Only encode |
| 263 |
> |
.Dq unsafe |
| 264 |
> |
characters. |
| 265 |
|
Unsafe means control characters which may cause common terminals to perform |
| 266 |
|
unexpected functions. |
| 267 |
|
Currently this form allows space, tab, newline, backspace, bell, and |
| 268 |
< |
return - in addition to all graphic characters - unencoded. |
| 268 |
> |
return \(em in addition to all graphic characters \(em unencoded. |
| 269 |
|
.El |
| 270 |
|
.Pp |
| 271 |
|
(The above flags have no effect for |
| 305 |
|
to represent meta characters (characters with the 8th |
| 306 |
|
bit set), and use caret |
| 307 |
|
.Ql ^ |
| 308 |
< |
to represent control characters see |
| 309 |
< |
.Pf ( Xr iscntrl 3 ) . |
| 308 |
> |
to represent control characters (see |
| 309 |
> |
.Xr iscntrl 3 ) . |
| 310 |
|
The following formats are used: |
| 311 |
|
.Bl -tag -width xxxxx |
| 312 |
|
.It Dv \e^C |
| 353 |
|
characters. |
| 354 |
|
The following sequences are used to represent the indicated characters: |
| 355 |
|
.Bd -unfilled -offset indent |
| 356 |
< |
.Li \ea Tn - BEL No (007) |
| 357 |
< |
.Li \eb Tn - BS No (010) |
| 358 |
< |
.Li \ef Tn - NP No (014) |
| 359 |
< |
.Li \en Tn - NL No (012) |
| 360 |
< |
.Li \er Tn - CR No (015) |
| 361 |
< |
.Li \es Tn - SP No (040) |
| 362 |
< |
.Li \et Tn - HT No (011) |
| 363 |
< |
.Li \ev Tn - VT No (013) |
| 364 |
< |
.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) |
| 365 |
|
.Ed |
| 366 |
|
.Pp |
| 367 |
< |
When using this format, the nextc parameter is looked at to determine |
| 368 |
< |
if a |
| 367 |
> |
When using this format, the |
| 368 |
> |
.Fa nextc |
| 369 |
> |
parameter is looked at to determine if a |
| 370 |
|
.Dv NUL |
| 371 |
|
character can be encoded as |
| 372 |
|
.Ql \e0 |
| 393 |
|
.It Dv VIS_MIMESTYLE |
| 394 |
|
Use MIME Quoted-Printable encoding as described in RFC 2045, only don't |
| 395 |
|
break lines and don't handle CRLF. |
| 396 |
< |
The form is: |
| 397 |
< |
.Ql %XX |
| 396 |
> |
The form is |
| 397 |
> |
.Ql =XX |
| 398 |
|
where |
| 399 |
|
.Em X |
| 400 |
|
represents an upper case hexadecimal digit. |
| 411 |
|
.Ql M-C ) . |
| 412 |
|
With this flag set, the encoding is |
| 413 |
|
ambiguous and non-invertible. |
| 414 |
+ |
.Sh MULTIBYTE CHARACTER SUPPORT |
| 415 |
+ |
These functions support multibyte character input. |
| 416 |
+ |
The encoding conversion is influenced by the setting of the |
| 417 |
+ |
.Ev LC_CTYPE |
| 418 |
+ |
environment variable which defines the set of characters |
| 419 |
+ |
that can be copied without encoding. |
| 420 |
+ |
.Pp |
| 421 |
+ |
When 8-bit data is present in the input, |
| 422 |
+ |
.Ev LC_CTYPE |
| 423 |
+ |
must be set to the correct locale or to the C locale. |
| 424 |
+ |
If the locales of the data and the conversion are mismatched, |
| 425 |
+ |
multibyte character recognition may fail and encoding will be performed |
| 426 |
+ |
byte-by-byte instead. |
| 427 |
+ |
.Pp |
| 428 |
+ |
As noted above, |
| 429 |
+ |
.Fa dst |
| 430 |
+ |
must be four times the number of bytes processed from |
| 431 |
+ |
.Fa src . |
| 432 |
+ |
But note that each multibyte character can be up to |
| 433 |
+ |
.Dv MB_LEN_MAX |
| 434 |
+ |
bytes |
| 435 |
+ |
.\" (see |
| 436 |
+ |
.\" .Xr multibyte 3 ) |
| 437 |
+ |
so in terms of multibyte characters, |
| 438 |
+ |
.Fa dst |
| 439 |
+ |
must be four times |
| 440 |
+ |
.Dv MB_LEN_MAX |
| 441 |
+ |
times the number of characters processed from |
| 442 |
+ |
.Fa src . |
| 443 |
+ |
.Sh ENVIRONMENT |
| 444 |
+ |
.Bl -tag -width ".Ev LC_CTYPE" |
| 445 |
+ |
.It Ev LC_CTYPE |
| 446 |
+ |
Specify the locale of the input data. |
| 447 |
+ |
Set to C if the input data locale is unknown. |
| 448 |
+ |
.El |
| 449 |
|
.Sh ERRORS |
| 450 |
|
The functions |
| 451 |
|
.Fn nvis |
| 461 |
|
.Fn strsnvisx , |
| 462 |
|
will return \-1 when the |
| 463 |
|
.Fa dlen |
| 464 |
< |
destination buffer length size is not enough to perform the conversion while |
| 464 |
> |
destination buffer size is not enough to perform the conversion while |
| 465 |
|
setting |
| 466 |
|
.Va errno |
| 467 |
|
to: |
| 468 |
< |
.Bl -tag -width Er |
| 468 |
> |
.Bl -tag -width ".Bq Er ENOSPC" |
| 469 |
|
.It Bq Er ENOSPC |
| 470 |
|
The destination buffer size is not large enough to perform the conversion. |
| 471 |
|
.El |
| 473 |
|
.Xr unvis 1 , |
| 474 |
|
.Xr vis 1 , |
| 475 |
|
.Xr glob 3 , |
| 476 |
+ |
.\" .Xr multibyte 3 , |
| 477 |
|
.Xr unvis 3 |
| 478 |
|
.Rs |
| 479 |
|
.%A T. Berners-Lee |
| 480 |
|
.%T Uniform Resource Locators (URL) |
| 481 |
< |
.%O RFC1738 |
| 481 |
> |
.%O "RFC 1738" |
| 482 |
|
.Re |
| 483 |
+ |
.Rs |
| 484 |
+ |
.%T "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies" |
| 485 |
+ |
.%O "RFC 2045" |
| 486 |
+ |
.Re |
| 487 |
|
.Sh HISTORY |
| 488 |
|
The |
| 489 |
|
.Fn vis , |
| 490 |
|
.Fn strvis , |
| 491 |
|
and |
| 492 |
< |
.Fa strvisx |
| 492 |
> |
.Fn strvisx |
| 493 |
|
functions first appeared in |
| 494 |
|
.Bx 4.4 . |
| 495 |
|
The |
| 500 |
|
functions appeared in |
| 501 |
|
.Nx 1.5 |
| 502 |
|
and |
| 503 |
< |
.Fx 10.0 . |
| 503 |
> |
.Fx 9.2 . |
| 504 |
|
The buffer size limited versions of the functions |
| 505 |
|
.Po Fn nvis , |
| 506 |
|
.Fn strnvis , |
| 510 |
|
and |
| 511 |
|
.Fn strsnvisx Pc |
| 512 |
|
appeared in |
| 454 |
– |
.Nx 6.0 |
| 513 |
|
and |
| 514 |
< |
.Fx 10.0 . |
| 514 |
> |
.Fx 9.2 . |
| 515 |
> |
Myltibyte character support was added in |
| 516 |
> |
.Nx 7.0 |
| 517 |
> |
and |
| 518 |
> |
.Fx 9.2 . |
