Replace our implementation of the vis(3) and unvis(3) APIs with

NetBSD's.  This output size limited versions of vis and unvis functions
as well as a set of vis variants that allow arbitrary characters to be
specified for encoding.

Finally, MIME Quoted-Printable encoding as described in RFC 2045 is
supported.

1 files changed, 247 insertions, 0 deletions

diff --git a/contrib/libc-vis/unvis.3 b/contrib/libc-vis/unvis.3
new file mode 100644
index 0000000..472c49d
--- /dev/null
+++ b/contrib/libc-vis/unvis.3
@@ -0,0 +1,247 @@
+.\"	$NetBSD: unvis.3,v 1.23 2011/03/17 14:06:29 wiz Exp $
+.\"	$FreeBSD$
+.\"
+.\" Copyright (c) 1989, 1991, 1993
+.\"	The Regents of the University of California.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"     @(#)unvis.3	8.2 (Berkeley) 12/11/93
+.\"
+.Dd March 12, 2011
+.Dt UNVIS 3
+.Os
+.Sh NAME
+.Nm unvis ,
+.Nm strunvis
+.Nd decode a visual representation of characters
+.Sh LIBRARY
+.Lb libc
+.Sh SYNOPSIS
+.In vis.h
+.Ft int
+.Fn unvis "char *cp" "int c" "int *astate" "int flag"
+.Ft int
+.Fn strunvis "char *dst" "const char *src"
+.Ft int
+.Fn strnunvis "char *dst" "size_t dlen" "const char *src"
+.Ft int
+.Fn strunvisx "char *dst" "const char *src" "int flag"
+.Ft int
+.Fn strnunvisx "char *dst" "size_t dlen" "const char *src" "int flag"
+.Sh DESCRIPTION
+The
+.Fn unvis ,
+.Fn strunvis
+and
+.Fn strunvisx
+functions
+are used to decode a visual representation of characters, as produced
+by the
+.Xr vis 3
+function, back into
+the original form.
+.Pp
+The
+.Fn unvis
+function is called with successive characters in
+.Ar c
+until a valid sequence is recognized, at which time the decoded
+character is available at the character pointed to by
+.Ar cp .
+.Pp
+The
+.Fn strunvis
+function decodes the characters pointed to by
+.Ar src
+into the buffer pointed to by
+.Ar dst .
+The
+.Fn strunvis
+function simply copies
+.Ar src
+to
+.Ar dst ,
+decoding any escape sequences along the way,
+and returns the number of characters placed into
+.Ar dst ,
+or \-1 if an
+invalid escape sequence was detected.
+The size of
+.Ar dst
+should be equal to the size of
+.Ar src
+(that is, no expansion takes place during decoding).
+.Pp
+The
+.Fn strunvisx
+function does the same as the
+.Fn strunvis
+function,
+but it allows you to add a flag that specifies the style the string
+.Ar src
+is encoded with.
+Currently, the supported flags are:
+.Dv VIS_HTTPSTYLE
+and
+.Dv VIS_MIMESTYLE .
+.Pp
+The
+.Fn unvis
+function implements a state machine that can be used to decode an
+arbitrary stream of bytes.
+All state associated with the bytes being decoded is stored outside the
+.Fn unvis
+function (that is, a pointer to the state is passed in), so
+calls decoding different streams can be freely intermixed.
+To start decoding a stream of bytes, first initialize an integer to zero.
+Call
+.Fn unvis
+with each successive byte, along with a pointer
+to this integer, and a pointer to a destination character.
+The
+.Fn unvis
+function has several return codes that must be handled properly.
+They are:
+.Bl -tag -width UNVIS_VALIDPUSH
+.It Li \&0 (zero)
+Another character is necessary; nothing has been recognized yet.
+.It Dv UNVIS_VALID
+A valid character has been recognized and is available at the location
+pointed to by cp.
+.It Dv UNVIS_VALIDPUSH
+A valid character has been recognized and is available at the location
+pointed to by cp; however, the character currently passed in should
+be passed in again.
+.It Dv UNVIS_NOCHAR
+A valid sequence was detected, but no character was produced.
+This return code is necessary to indicate a logical break between characters.
+.It Dv UNVIS_SYNBAD
+An invalid escape sequence was detected, or the decoder is in an unknown state.
+The decoder is placed into the starting state.
+.El
+.Pp
+When all bytes in the stream have been processed, call
+.Fn unvis
+one more time with flag set to
+.Dv UNVIS_END
+to extract any remaining character (the character passed in is ignored).
+.Pp
+The
+.Ar flag
+argument is also used to specify the encoding style of the source.
+If set to
+.Dv VIS_HTTPSTYLE
+or
+.Dv VIS_HTTP1808 ,
+.Fn unvis
+will decode URI strings as specified in RFC 1808.
+If set to
+.Dv VIS_HTTP1866 ,
+.Fn unvis
+will decode URI strings as specified in RFC 1866.
+If set to
+.Dv VIS_MIMESTYLE ,
+.Fn unvis
+will decode MIME Quoted-Printable strings as specified in RFC 2045.
+If set to
+.Dv VIS_NOESCAPE ,
+.Fn unvis
+will not decode \e quoted characters.
+.Pp
+The following code fragment illustrates a proper use of
+.Fn unvis .
+.Bd -literal -offset indent
+int state = 0;
+char out;
+
+while ((ch = getchar()) != EOF) {
+again:
+	switch(unvis(\*[Am]out, ch, \*[Am]state, 0)) {
+	case 0:
+	case UNVIS_NOCHAR:
+		break;
+	case UNVIS_VALID:
+		(void)putchar(out);
+		break;
+	case UNVIS_VALIDPUSH:
+		(void)putchar(out);
+		goto again;
+	case UNVIS_SYNBAD:
+		errx(EXIT_FAILURE, "Bad character sequence!");
+	}
+}
+if (unvis(\*[Am]out, '\e0', \*[Am]state, UNVIS_END) == UNVIS_VALID)
+	(void)putchar(out);
+.Ed
+.Sh ERRORS
+The functions
+.Fn strunvis ,
+.Fn strnunvis ,
+.Fn strunvisx ,
+and
+.Fn strnunvisx
+will return \-1 on error and set
+.Va errno 
+to:
+.Bl -tag -width Er
+.It Bq Er EINVAL
+An invalid escape sequence was detected, or the decoder is in an unknown state.
+.El
+.Pp
+In addition the functions
+.Fn strnunvis 
+and
+.Fn strnunvisx
+will can also set
+.Va errno
+on error to:
+.Bl -tag -width Er
+.It Bq Er ENOSPC
+Not enough space to perform the conversion.
+.El
+.Sh SEE ALSO
+.Xr unvis 1 ,
+.Xr vis 1 ,
+.Xr vis 3
+.Rs
+.%A R. Fielding
+.%T Relative Uniform Resource Locators
+.%O RFC1808
+.Re
+.Sh HISTORY
+The
+.Fn unvis
+function
+first appeared in
+.Bx 4.4 .
+The
+.Fn strnunvis
+and
+.Fn strnunvisx
+functions appeared in
+.Nx 6.0
+and
+.Fx 10.0 .