Add documentation for mchain API.

Reviewed by:	asmodai, ru (mbchain.9)

1 files changed, 208 insertions, 0 deletions

diff --git a/share/man/man9/mdchain.9 b/share/man/man9/mdchain.9
new file mode 100644
index 0000000..f1a2763
--- /dev/null
+++ b/share/man/man9/mdchain.9
@@ -0,0 +1,208 @@
+.\" -*- nroff -*-
+.\"
+.\" Copyright (c) 2001 Boris Popov
+.\"
+.\" 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.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``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 DEVELOPERS 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.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd February 28, 2001
+.Dt MDCHAIN 9
+.Os
+.Sh NAME
+.Nm mdchain ,
+.Nm md_initm ,
+.Nm md_done ,
+.Nm md_append_record ,
+.Nm md_next_record ,
+.Nm md_get_uint8 ,
+.Nm md_get_uint16 ,
+.Nm md_get_uint16be ,
+.Nm md_get_uint16le ,
+.Nm md_get_uint32 ,
+.Nm md_get_uint32be ,
+.Nm md_get_uint32le ,
+.Nm md_get_int64 ,
+.Nm md_get_int64be ,
+.Nm md_get_int64le ,
+.Nm md_get_mem ,
+.Nm md_get_mbuf ,
+.Nm md_get_uio
+.Nd "set of functions to dissect an mbuf chain to various data types"
+.Sh SYNOPSIS
+.Cd options LIBMCHAIN
+.Li kldload libmchain
+.Pp
+.Fd #include <sys/param.h>
+.Fd #include <sys/mchain.h>
+.Ft void
+.Fn md_initm "struct mdchain *mdp" "struct mbuf *m"
+.Ft void
+.Fn md_done "struct mdchain *mdp"
+.Ft void
+.Fn md_append_record "struct mdchain *mdp" "struct mbuf *top"
+.Ft int
+.Fn md_next_record "struct mdchain *mdp"
+.Ft int
+.Fn md_get_uint8 "struct mdchain *mdp" "u_int8_t x"
+.Ft int
+.Fn md_get_uint16 "struct mdchain *mdp" "u_int16_t x"
+.Ft int
+.Fn md_get_uint16be "struct mdchain *mdp" "u_int16_t x"
+.Ft int
+.Fn md_get_uint16le "struct mdchain *mdp" "u_int16_t x"
+.Ft int
+.Fn md_get_uint32 "struct mdchain *mdp" "u_int32_t x"
+.Ft int
+.Fn md_get_uint32be "struct mdchain *mdp" "u_int32_t x"
+.Ft int
+.Fn md_get_uint32le "struct mdchain *mdp" "u_int32_t x"
+.Ft int
+.Fn md_get_int64 "struct mdchain *mdp" "int64_t x"
+.Ft int
+.Fn md_get_int64be "struct mdchain *mdp" "int64_t x"
+.Ft int
+.Fn md_get_int64le "struct mdchain *mdp" "int64_t x"
+.Ft int
+.Fn md_get_mem "struct mdchain *mdp" "caddr_t target" "int size" "int type"
+.Ft int
+.Fn md_get_mbuf "struct mdchain *mdp" "struct mbuf *m"
+.Ft int
+.Fn md_get_uio "struct mdchain *mdp" "struct uio *uiop" "int size"
+.Sh DESCRIPTION
+These functions are used to decompose mbuf chains to various data types.
+The
+.Vt mdchain
+structure is used as a working context
+and should be initialized via call of
+.Fn mb_initm
+function.
+It has the following fields:
+.Bl -tag -width "md_top"
+.It Va "md_top"
+.Vt ( "struct mbuf *" )
+a pointer to the top of the parsed mbuf chain
+.It Va md_cur
+.Vt ( "struct mbuf *" )
+a pointer to the currently parsed mbuf
+.It Va md_pas
+.Vt ( int )
+offset in the current mbuf
+.El
+.Pp
+The
+.Fn md_done
+function disposes of an mbuf chain pointed to by the
+.Fa mdp->md_top
+field and sets the field to
+.Dv NULL .
+.Pp
+The
+.Fn md_append_record
+appends a new mbuf chain using
+.Va m_nextpkt
+field to form a signle linked list of mbuf chains.
+If
+.Va mdp->md_top
+field is
+.Dv NULL ,
+then this function behaves exactly as
+.Fn md_initm
+function.
+.Pp
+The
+.Fn md_next_record
+extracts next mbuf chain and disposes current if any.
+For new mbuf chain it calls
+.Fn md_initm
+function.
+If there is no data left function returns
+.Dv ENOENT .
+.Pp
+All
+.Fn md_get_*
+functions perform an actual copy of the data from an mbuf chain.
+Functions which have
+.Cm le
+or
+.Cm be
+suffixes will perform conversion to the little- or big-endian data formats.
+.Pp
+.Fn md_get_mem
+function copies
+.Fa size
+bytes of data specified by the
+.Fa source
+argument from an mbuf chain.
+The
+.Fa type
+argument specifies the method used to perform a copy,
+and can be one of the following:
+.Bl -tag -width "MB_MINLINE"
+.It Dv MB_MSYSTEM
+use
+.Fn bcopy
+function
+.It Dv MB_MUSER
+use
+.Xr copyin 9
+function
+.It Dv MB_MINLINE
+use an
+.Dq inline
+loop which does not call any function
+.El
+.Pp
+If
+.Ar target is
+.Dv NULL ,
+an actual copy is not performed and function just skips given number of bytes.
+.Sh RETURN VALUES
+All
+.Ft int
+functions return zero if successful,
+otherwise an error code is returned.
+.Pp
+.Em Note :
+after failure of any function,
+a mbuf chain is left in the broken state and only the
+.Fn md_done
+function can safely be called to destroy it.
+.Sh EXAMPLES
+.Bd -literal
+struct mdchain *mdp;
+struct mbuf *m;
+u_int16_t length;
+u_int8_t byte;
+.Pp
+receive(so, &m);
+md_initm(mdp, m);
+if (md_get_uint8(mdp, &byte) != 0 ||
+    md_get_uint16le(mdp, &length) != 0)
+	error = EBADRPC;
+mb_done(mdp);
+.Ed
+.Sh SEE ALSO
+.Xr mbuf 9 ,
+.Xr mbchain 9
+.Sh AUTHORS
+This manual page was written by
+.An Boris Popov Aq bp@FreeBSD.org .