Skip to content

GitLab

L
libbsd
Commit 2d7de186 authored by Guillem Jover's avatar Guillem Jover
2 Browse files
Options

Update vis/unvis modules from NetBSD

parent 3efad641
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 1592 additions and 523 deletions
COPYING
View file @ 2d7de186
......@@ -122,7 +122,6 @@ Files:
src/strmode.c
src/strnstr.c
src/unvis.c
src/vis.c
Copyright:
Copyright © 1980, 1982, 1986, 1989-1994
The Regents of the University of California. All rights reserved.
......@@ -315,6 +314,16 @@ License: BSD-2-clause-NetBSD
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
Files:
src/vis.c
Copyright:
Copyright © 1989, 1993
The Regents of the University of California. All rights reserved.
.
Copyright © 1999, 2005 The NetBSD Foundation, Inc.
All rights reserved.
License: BSD-3-clause-Regents and BSD-2-clause-NetBSD
Files:
include/bsd/sys/endian.h
man/byteorder.3bsd
......
include/bsd/vis.h
View file @ 2d7de186
/* $NetBSD: vis.h,v 1.25 2017/04/23 01:57:36 christos Exp $ */
/*-
* Copyright (c) 1990, 1993
* The Regents of the University of California. All rights reserved.
......@@ -27,7 +29,6 @@
* SUCH DAMAGE.
*
* @(#)vis.h 8.1 (Berkeley) 6/2/93
* $FreeBSD: src/include/vis.h,v 1.11 2003/10/30 10:40:49 phk Exp $
*/
#ifndef LIBBSD_VIS_H
......@@ -38,25 +39,34 @@
/*
* to select alternate encoding format
*/
#define VIS_OCTAL 0x01 /* use octal \ddd format */
#define VIS_CSTYLE 0x02 /* use \[nrft0..] where appropriate */
#define VIS_OCTAL 0x0001 /* use octal \ddd format */
#define VIS_CSTYLE 0x0002 /* use \[nrft0..] where appropriate */
/*
* to alter set of characters encoded (default is to encode all
* non-graphic except space, tab, and newline).
*/
#define VIS_SP 0x04 /* also encode space */
#define VIS_TAB 0x08 /* also encode tab */
#define VIS_NL 0x10 /* also encode newline */
#define VIS_SP 0x0004 /* also encode space */
#define VIS_TAB 0x0008 /* also encode tab */
#define VIS_NL 0x0010 /* also encode newline */
#define VIS_WHITE (VIS_SP | VIS_TAB | VIS_NL)
#define VIS_SAFE 0x20 /* only encode "unsafe" characters */
#define VIS_SAFE 0x0020 /* only encode "unsafe" characters */
#define VIS_DQ 0x8000 /* also encode double quotes */
/*
* other
*/
#define VIS_NOSLASH 0x40 /* inhibit printing '\' */
#define VIS_HTTPSTYLE 0x80 /* http-style escape % HEX HEX */
#define VIS_GLOB 0x100 /* encode glob(3) magics */
#define VIS_NOSLASH 0x0040 /* inhibit printing '\' */
#define VIS_HTTP1808 0x0080 /* http-style escape % hex hex */
#define VIS_HTTPSTYLE 0x0080 /* http-style escape % hex hex */
#define VIS_MIMESTYLE 0x0100 /* mime-style escape = HEX HEX */
#define VIS_HTTP1866 0x0200 /* http-style &#num; or &string; */
#define VIS_NOESCAPE 0x0400 /* don't decode `\' */
#define _VIS_END 0x0800 /* for unvis */
#define VIS_GLOB 0x1000 /* encode glob(3) magic characters */
#define VIS_SHELL 0x2000 /* encode shell special characters [not glob] */
#define VIS_META (VIS_WHITE | VIS_GLOB | VIS_SHELL)
#define VIS_NOLOCALE 0x4000 /* encode using the C locale */
/*
* unvis return codes
......@@ -70,7 +80,7 @@
/*
* unvis flags
*/
#define UNVIS_END 1 /* no more characters */
#define UNVIS_END _VIS_END /* no more characters */
#ifdef LIBBSD_OVERLAY
#include <sys/cdefs.h>
......@@ -80,12 +90,33 @@
__BEGIN_DECLS
char *vis(char *, int, int, int);
char *nvis(char *, size_t, int, int, int);
char *svis(char *, int, int, int, const char *);
char *snvis(char *, size_t, int, int, int, const char *);
int strvis(char *, const char *, int);
int stravis(char **, const char *, int);
int strnvis(char *, size_t, const char *, int);
int strsvis(char *, const char *, int, const char *);
int strsnvis(char *, size_t, const char *, int, const char *);
int strvisx(char *, const char *, size_t, int);
int strnvis(char *, const char *, size_t, int);
int strnvisx(char *, size_t, const char *, size_t, int);
int strenvisx(char *, size_t, const char *, size_t, int, int *);
int strsvisx(char *, const char *, size_t, int, const char *);
int strsnvisx(char *, size_t, const char *, size_t, int, const char *);
int strsenvisx(char *, size_t, const char *, size_t , int, const char *,
int *);
int strunvis(char *, const char *);
int strnunvis(char *, size_t, const char *);
int strunvisx(char *, const char *, int);
ssize_t strnunvis(char *, const char *, size_t);
int strnunvisx(char *, size_t, const char *, int);
int unvis(char *, int, int *, int);
__END_DECLS
......
man/unvis.3bsd
View file @ 2d7de186
.\" $OpenBSD: unvis.3,v 1.15 2005/07/22 03:16:58 jaredy Exp $
.\" $NetBSD: unvis.3,v 1.29 2017/10/24 19:14:55 abhinav Exp $
.\"
.\" Copyright (c) 1989, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
......@@ -27,13 +27,17 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd $Mdocdate: May 31 2007 $
.\" @(#)unvis.3 8.2 (Berkeley) 12/11/93
.\"
.Dd March 12, 2011
.Dt UNVIS 3bsd
.Os
.Sh NAME
.Nm unvis ,
.Nm strunvis ,
.Nm strnunvis
.Nm strnunvis ,
.Nm strunvisx ,
.Nm strnunvisx
.Nd decode a visual representation of characters
.Sh LIBRARY
.ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
......@@ -44,88 +48,91 @@
.Xr libbsd 7
for include usage.)
.Ft int
.Fn unvis "char *cp" "char c" "int *astate" "int flag"
.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 strunvis "char *dst" "char *src"
.Ft ssize_t
.Fn strnunvis "char *dst" "char *src" "size_t size"
.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 strnunvis
functions are used to decode a visual representation of characters,
as produced by the
.Fn strunvisx
functions
are used to decode a visual representation of characters, as produced
by the
.Xr vis 3bsd
function, back into the original form.
function, back into
the original form.
.Pp
The
.Fn unvis
is called with successive characters in
.Fa c
until a valid
sequence is recognized, at which time the decoded character is
available at the character pointed to by
.Fa cp .
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
decodes the characters pointed to by
.Fa src
function decodes the characters pointed to by
.Ar src
into the buffer pointed to by
.Fa dst .
.Pp
.Fn strnunvis
decodes the characters pointed to by
.Fa src
into the buffer pointed to by
.Fa dst ,
writing a maximum of
.Fa size
bytes.
.Ar dst .
The
.Fn strunvis
function simply copies
.Fa src
.Ar src
to
.Fa dst ,
.Ar dst ,
decoding any escape sequences along the way,
and returns the number of characters placed into
.Fa dst ,
.Ar dst ,
or \-1 if an
invalid escape sequence was detected.
The size of
.Fa dst
should be
equal to the size of
.Fa src
.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
terminates the destination string with a trailing NUL byte;
.Fn strnunvis
does so if
.Fa size
is larger than 0.
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.
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.
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.
.Sh RETURN VALUES
The
.Fn unvis
function has several return codes that must be handled properly.
They are:
.Bl -tag -width UNVIS_VALIDPUSH
.It Li \&0 (zero)
.It Li \&0 No (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
......@@ -140,30 +147,41 @@ however, the character currently passed in should be passed in again.
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.
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
.Fa flag
set to
one more time with flag set to
.Dv UNVIS_END
to extract any remaining character (the character passed in is ignored).
.Pp
The
.Fn strunvis
function returns the number of bytes written (not counting
the trailing NUL byte) or \-1 if an error occurred.
.Fa 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 entity references and numeric character references
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
.Ql \e
quoted characters.
.Pp
The
.Fn strnunvis
function returns the number of bytes (not counting the trailing NUL byte)
that would be needed to fully convert the input string, or \-1 if an
error occurred.
.Sh EXAMPLES
The following code fragment illustrates a proper use of
.Fn unvis .
.Bd -literal -offset indent
......@@ -177,25 +195,72 @@ again:
case UNVIS_NOCHAR:
break;
case UNVIS_VALID:
(void) putchar(out);
(void)putchar(out);
break;
case UNVIS_VALIDPUSH:
(void) putchar(out);
(void)putchar(out);
goto again;
case UNVIS_SYNBAD:
(void)fprintf(stderr, "bad sequence!\en");
exit(1);
errx(EXIT_FAILURE, "Bad character sequence!");
}
}
if (unvis(&out, (char)0, &state, UNVIS_END) == UNVIS_VALID)
(void) putchar(out);
if (unvis(&out, '\e0', &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 3bsd
.Rs
.%A R. Fielding
.%T Relative Uniform Resource Locators
.%O RFC1808
.Re
.Sh HISTORY
The
.Fn unvis
function first appeared in
function
first appeared in
.Bx 4.4 .
The
.Fn strnunvis
and
.Fn strnunvisx
functions appeared in
.Nx 6.0 .
.Sh BUGS
The names
.Dv VIS_HTTP1808
and
.Dv VIS_HTTP1866
are wrong.
Percent-encoding was defined in RFC 1738, the original RFC for URL.
RFC 1866 defines HTML 2.0, an application of SGML, from which it
inherits concepts of numeric character references and entity
references.
man/vis.3bsd
View file @ 2d7de186
.\" $OpenBSD: vis.3,v 1.23 2005/08/28 19:51:27 millert Exp $
.\" $NetBSD: vis.3,v 1.49 2017/08/05 20:22:29 wiz Exp $
.\"
.\" Copyright (c) 1989, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
......@@ -27,53 +27,87 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd $Mdocdate: May 31 2007 $
.\" @(#)vis.3 8.1 (Berkeley) 6/9/93
.\"
.Dd April 22, 2017
.Dt VIS 3bsd
.Os
.Sh NAME
.Nm vis ,
.Nm nvis ,
.Nm strvis ,
.Nm stravis ,
.Nm strnvis ,
.Nm strvisx
.Nm strvisx ,
.Nm strnvisx ,
.Nm strenvisx ,
.Nm svis ,
.Nm snvis ,
.Nm strsvis ,
.Nm strsnvis ,
.Nm strsvisx ,
.Nm strsnvisx ,
.Nm strsenvisx
.Nd visually encode characters
.Sh LIBRARY
.ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
.Lb libbsd
.Sh SYNOPSIS
.In stdlib.h
.In vis.h
(See
.Xr libbsd 7
for include usage.)
.Ft char *
.Fn vis "char *dst" "int c" "int flag" "int nextc"
.Ft char *
.Fn nvis "char *dst" "size_t dlen" "int c" "int flag" "int nextc"
.Ft int
.Fn strvis "char *dst" "const char *src" "int flag"
.Ft int
.Fn strnvis "char *dst" "const char *src" "size_t size" "int flag"
.Fn stravis "char **dst" "const char *src" "int flag"
.Ft int
.Fn strnvis "char *dst" "size_t dlen" "const char *src" "int flag"
.Ft int
.Fn strvisx "char *dst" "const char *src" "size_t len" "int flag"
.Ft int
.Fn strnvisx "char *dst" "size_t dlen" "const char *src" "size_t len" "int flag"
.Ft int
.Fn strenvisx "char *dst" "size_t dlen" "const char *src" "size_t len" "int flag" "int *cerr_ptr"
.Ft char *
.Fn svis "char *dst" "int c" "int flag" "int nextc" "const char *extra"
.Ft char *
.Fn snvis "char *dst" "size_t dlen" "int c" "int flag" "int nextc" "const char *extra"
.Ft int
.Fn strsvis "char *dst" "const char *src" "int flag" "const char *extra"
.Ft int
.Fn strsnvis "char *dst" "size_t dlen" "const char *src" "int flag" "const char *extra"
.Ft int
.Fn strsvisx "char *dst" "const char *src" "size_t len" "int flag" "const char *extra"
.Ft int
.Fn strsnvisx "char *dst" "size_t dlen" "const char *src" "size_t len" "int flag" "const char *extra"
.Ft int
.Fn strsenvisx "char *dst" "size_t dlen" "const char *src" "size_t len" "int flag" "const char *extra" "int *cerr_ptr"
.Sh DESCRIPTION
The
.Fn vis
function copies into
function
copies into
.Fa dst
a string which represents the character
.Fa c .
If
.Fa c
needs no encoding, it is copied in unaltered.
The string is NUL terminated and a pointer to the end of the string is
The string is null terminated, and a pointer to the end of the string is
returned.
The maximum length of any encoding is four
characters (not including the trailing NUL);
bytes (not including the trailing
.Dv NUL ) ;
thus, when
encoding a set of characters into a buffer, the size of the buffer should
be four times the number of characters encoded, plus one for the trailing
NUL.
The
.Fa flag
parameter is used for altering the default range of
be four times the number of bytes encoded, plus one for the trailing
.Dv NUL .
The flag parameter is used for altering the default range of
characters considered for encoding and for altering the visual
representation.
The additional character,
......@@ -84,9 +118,11 @@ encoding format (explained below).
.Pp
The
.Fn strvis ,
.Fn strnvis
.Fn stravis ,
.Fn strnvis ,
.Fn strvisx ,
and
.Fn strvisx
.Fn strnvisx
functions copy into
.Fa dst
a visual representation of
......@@ -94,89 +130,153 @@ the string
.Fa src .
The
.Fn strvis
function encodes characters from
.Fa src
up to the first NUL.
The
and
.Fn strnvis
function encodes characters from
functions encode characters from
.Fa src
up to the first NUL or the end of
.Fa dst ,
as indicated by
.Fa size .
up to the
first
.Dv NUL .
The
.Fn strvisx
function encodes exactly
and
.Fn strnvisx
functions encode exactly
.Fa len
characters from
.Fa src
(this
is useful for encoding a block of data that may contain NULs).
All three forms NUL terminate
.Fa dst ,
except for
.Fn strnvis
when
.Fa size
is zero, in which case
.Fa dst
is not touched.
For
.Fn strvis
and
.Fn strvisx ,
the size of
is useful for encoding a block of data that may contain
.Dv NUL Ns 's ) .
Both forms
.Dv NUL
terminate
.Fa dst .
The size of
.Fa dst
must be four times the number
of characters encoded from
of bytes encoded from
.Fa src
(plus one for the NUL).
.Fn strvis
and
.Fn strvisx
return the number of characters in
(plus one for the
.Dv NUL ) .
Both
forms return the number of characters in
.Fa dst
(not including the trailing NUL).
.Fn strnvis
returns the length that
(not including the trailing
.Dv NUL ) .
The
.Fn stravis
function allocates space dynamically to hold the string.
The
.Dq Nm n
versions of the functions also take an additional argument
.Fa dlen
that indicates the length of the
.Fa dst
would become if it were of unlimited size (similar to
.Xr snprintf 3
or
.Xr strlcpy 3bsd ) .
This can be used to detect truncation but it also means that
the return value of
buffer.
If
.Fa dlen
is not large enough to fit the converted string then the
.Fn strnvis
must not be used without checking it against
.Fa size .
and
.Fn strnvisx
functions return \-1 and set
.Va errno
to
.Dv ENOSPC .
The
.Fn strenvisx
function takes an additional argument,
.Fa cerr_ptr ,
that is used to pass in and out a multibyte conversion error flag.
This is useful when processing single characters at a time when
it is possible that the locale may be set to something other
than the locale of the characters in the input data.
.Pp
The functions
.Fn svis ,
.Fn snvis ,
.Fn strsvis ,
.Fn strsnvis ,
.Fn strsvisx ,
.Fn strsnvisx ,
and
.Fn strsenvisx
correspond to
.Fn vis ,
.Fn nvis ,
.Fn strvis ,
.Fn strnvis ,
.Fn strvisx ,
.Fn strnvisx ,
and
.Fn strenvisx
but have an additional argument
.Fa extra ,
pointing to a
.Dv NUL
terminated list of characters.
These characters will be copied encoded or backslash-escaped into
.Fa dst .
These functions are useful e.g. to remove the special meaning
of certain characters to shells.
.Pp
The encoding is a unique, invertible representation composed entirely of
graphic characters; it can be decoded back into the original form using
the
.Xr unvis 3bsd
or
.Xr unvis 3bsd ,
.Xr strunvis 3bsd
or
.Xr strnunvis 3bsd
functions.
.Pp
There are two parameters that can be controlled: the range of
characters that are encoded, and the type
of representation used.
By default, all non-graphic characters
except space, tab, and newline are encoded