| unvis.3 (244401) | unvis.3 (248302) |
|---|---|
| 1.\" $NetBSD: unvis.3,v 1.23 2011/03/17 14:06:29 wiz Exp $ 2.\" $FreeBSD: head/contrib/libc-vis/unvis.3 244401 2012-12-18 16:37:24Z brooks $ | 1.\" $NetBSD: unvis.3,v 1.27 2012/12/15 07:34:36 wiz Exp $ 2.\" $FreeBSD: head/contrib/libc-vis/unvis.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 --- 110 unchanged lines hidden (view full) --- 121.Fn unvis 122with each successive byte, along with a pointer 123to this integer, and a pointer to a destination character. 124The 125.Fn unvis 126function has several return codes that must be handled properly. 127They are: 128.Bl -tag -width UNVIS_VALIDPUSH | 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 --- 110 unchanged lines hidden (view full) --- 121.Fn unvis 122with each successive byte, along with a pointer 123to this integer, and a pointer to a destination character. 124The 125.Fn unvis 126function has several return codes that must be handled properly. 127They are: 128.Bl -tag -width UNVIS_VALIDPUSH |
| 129.It Li \&0 (zero) | 129.It Li \&0 No (zero) |
| 130Another character is necessary; nothing has been recognized yet. 131.It Dv UNVIS_VALID 132A valid character has been recognized and is available at the location | 130Another character is necessary; nothing has been recognized yet. 131.It Dv UNVIS_VALID 132A valid character has been recognized and is available at the location |
| 133pointed to by cp. | 133pointed to by 134.Fa cp . |
| 134.It Dv UNVIS_VALIDPUSH 135A valid character has been recognized and is available at the location | 135.It Dv UNVIS_VALIDPUSH 136A valid character has been recognized and is available at the location |
| 136pointed to by cp; however, the character currently passed in should 137be passed in again. | 137pointed to by 138.Fa cp ; 139however, the character currently passed in should be passed in again. |
| 138.It Dv UNVIS_NOCHAR 139A valid sequence was detected, but no character was produced. 140This return code is necessary to indicate a logical break between characters. 141.It Dv UNVIS_SYNBAD 142An invalid escape sequence was detected, or the decoder is in an unknown state. 143The decoder is placed into the starting state. 144.El 145.Pp 146When all bytes in the stream have been processed, call 147.Fn unvis 148one more time with flag set to 149.Dv UNVIS_END 150to extract any remaining character (the character passed in is ignored). 151.Pp 152The | 140.It Dv UNVIS_NOCHAR 141A valid sequence was detected, but no character was produced. 142This return code is necessary to indicate a logical break between characters. 143.It Dv UNVIS_SYNBAD 144An invalid escape sequence was detected, or the decoder is in an unknown state. 145The decoder is placed into the starting state. 146.El 147.Pp 148When all bytes in the stream have been processed, call 149.Fn unvis 150one more time with flag set to 151.Dv UNVIS_END 152to extract any remaining character (the character passed in is ignored). 153.Pp 154The |
| 153.Ar flag | 155.Fa flag |
| 154argument is also used to specify the encoding style of the source. 155If set to 156.Dv VIS_HTTPSTYLE 157or 158.Dv VIS_HTTP1808 , 159.Fn unvis 160will decode URI strings as specified in RFC 1808. 161If set to 162.Dv VIS_HTTP1866 , 163.Fn unvis | 156argument is also used to specify the encoding style of the source. 157If set to 158.Dv VIS_HTTPSTYLE 159or 160.Dv VIS_HTTP1808 , 161.Fn unvis 162will decode URI strings as specified in RFC 1808. 163If set to 164.Dv VIS_HTTP1866 , 165.Fn unvis |
| 164will decode URI strings as specified in RFC 1866. | 166will decode entity references and numeric character references 167as specified in RFC 1866. |
| 165If set to 166.Dv VIS_MIMESTYLE , 167.Fn unvis 168will decode MIME Quoted-Printable strings as specified in RFC 2045. 169If set to 170.Dv VIS_NOESCAPE , 171.Fn unvis | 168If set to 169.Dv VIS_MIMESTYLE , 170.Fn unvis 171will decode MIME Quoted-Printable strings as specified in RFC 2045. 172If set to 173.Dv VIS_NOESCAPE , 174.Fn unvis |
| 172will not decode \e quoted characters. | 175will not decode 176.Ql \e 177quoted characters. |
| 173.Pp 174The following code fragment illustrates a proper use of 175.Fn unvis . 176.Bd -literal -offset indent 177int state = 0; 178char out; 179 180while ((ch = getchar()) != EOF) { --- 18 unchanged lines hidden (view full) --- 199.Sh ERRORS 200The functions 201.Fn strunvis , 202.Fn strnunvis , 203.Fn strunvisx , 204and 205.Fn strnunvisx 206will return \-1 on error and set | 178.Pp 179The following code fragment illustrates a proper use of 180.Fn unvis . 181.Bd -literal -offset indent 182int state = 0; 183char out; 184 185while ((ch = getchar()) != EOF) { --- 18 unchanged lines hidden (view full) --- 204.Sh ERRORS 205The functions 206.Fn strunvis , 207.Fn strnunvis , 208.Fn strunvisx , 209and 210.Fn strnunvisx 211will return \-1 on error and set |
| 207.Va errno | 212.Va errno |
| 208to: 209.Bl -tag -width Er 210.It Bq Er EINVAL 211An invalid escape sequence was detected, or the decoder is in an unknown state. 212.El 213.Pp 214In addition the functions | 213to: 214.Bl -tag -width Er 215.It Bq Er EINVAL 216An invalid escape sequence was detected, or the decoder is in an unknown state. 217.El 218.Pp 219In addition the functions |
| 215.Fn strnunvis | 220.Fn strnunvis |
| 216and 217.Fn strnunvisx 218will can also set 219.Va errno 220on error to: 221.Bl -tag -width Er 222.It Bq Er ENOSPC 223Not enough space to perform the conversion. --- 15 unchanged lines hidden (view full) --- 239.Bx 4.4 . 240The 241.Fn strnunvis 242and 243.Fn strnunvisx 244functions appeared in 245.Nx 6.0 246and | 221and 222.Fn strnunvisx 223will can also set 224.Va errno 225on error to: 226.Bl -tag -width Er 227.It Bq Er ENOSPC 228Not enough space to perform the conversion. --- 15 unchanged lines hidden (view full) --- 244.Bx 4.4 . 245The 246.Fn strnunvis 247and 248.Fn strnunvisx 249functions appeared in 250.Nx 6.0 251and |
| 247.Fx 10.0 . | 252.Fx 9.2 . 253.Sh BUGS 254The names 255.Dv VIS_HTTP1808 256and 257.Dv VIS_HTTP1866 258are wrong. 259Percent-encoding was defined in RFC 1738, the original RFC for URL. 260RFC 1866 defines HTML 2.0, an application of SGML, from which it 261inherits concepts of numeric character references and entity 262references. |