Add documentation for mchain API.

Reviewed by:	asmodai, ru (mbchain.9)

1 files changed, 219 insertions, 0 deletions

diff --git a/share/man/man9/mbchain.9 b/share/man/man9/mbchain.9
new file mode 100644
index 000000000000..a62580d2e083
--- /dev/null
+++ b/share/man/man9/mbchain.9
@@ -0,0 +1,219 @@
+.\" -*- 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 20, 2001
+.Dt MBCHAIN 9
+.Os
+.Sh NAME
+.Nm mbchain ,
+.Nm mb_init ,
+.Nm mb_initm ,
+.Nm mb_done ,
+.Nm mb_detach ,
+.Nm mb_fixhdr ,
+.Nm mb_reserve ,
+.Nm mb_put_uint8 ,
+.Nm mb_put_uint16be ,
+.Nm mb_put_uint16le ,
+.Nm mb_put_uint32be ,
+.Nm mb_put_uint32le ,
+.Nm mb_put_int64be ,
+.Nm mb_put_int64le ,
+.Nm mb_put_mem ,
+.Nm mb_put_mbuf ,
+.Nm mb_put_uio
+.Nd "set of functions to build an mbuf chain from various data types"
+.Sh SYNOPSIS
+.Cd options LIBMCHAIN
+.Li kldload libmchain
+.Pp
+.Fd #include <sys/param.h>
+.Fd #include <sys/mchain.h>
+.Ft int
+.Fn mb_init "struct mbchain *mbp"
+.Ft void
+.Fn mb_initm "struct mbchain *mbp" "struct mbuf *m"
+.Ft void
+.Fn mb_done "struct mbchain *mbp"
+.Ft struct mbuf *
+.Fn mb_detach "struct mbchain *mbp"
+.Ft int
+.Fn mb_fixhdr "struct mbchain *mbp"
+.Ft caddr_t
+.Fn mb_reserve "struct mbchain *mbp" "int size"
+.Ft int
+.Fn mb_put_uint8 "struct mbchain *mbp" "u_int8_t x"
+.Ft int
+.Fn mb_put_uint16be "struct mbchain *mbp" "u_int16_t x"
+.Ft int
+.Fn mb_put_uint16le "struct mbchain *mbp" "u_int16_t x"
+.Ft int
+.Fn mb_put_uint32be "struct mbchain *mbp" "u_int32_t x"
+.Ft int
+.Fn mb_put_uint32le "struct mbchain *mbp" "u_int32_t x"
+.Ft int
+.Fn mb_put_int64be "struct mbchain *mbp" "int64_t x"
+.Ft int
+.Fn mb_put_int64le "struct mbchain *mbp" "int64_t x"
+.Ft int
+.Fn mb_put_mem "struct mbchain *mbp" "c_caddr_t source" "int size" "int type"
+.Ft int
+.Fn mb_put_mbuf "struct mbchain *mbp" "struct mbuf *m"
+.Ft int
+.Fn mb_put_uio "struct mbchain *mbp" "struct uio *uiop" "int size"
+.Sh DESCRIPTION
+These functions are used to compose mbuf chains from various data types.
+The
+.Vt mbchain
+structure is used as a working context and should be initialized with a call
+to either
+.Fn mb_init
+or
+.Fn mb_initm .
+It has the following fields:
+.Bl -tag -width "mb_count"
+.It Va "mb_top"
+.Vt ( "struct mbuf *" )
+a pointer to the top of constructed mbuf chain
+.It Va mb_cur
+.Vt ( "struct mbuf *" )
+a pointer to the currently filled mbuf
+.It Va mb_mleft
+.Vt ( int )
+number of bytes left in the current mbuf
+.It Va mb_count
+.Vt ( int )
+total number of bytes placed in the mbuf chain
+.It Va mb_copy
+.Vt ( "mb_copy_t *" )
+user-defined function to perform a copy into mbuf;
+useful if any unusual
+data conversion is necessesary
+.It Va mb_udata
+.Vt ( "void *" )
+user-supplied data which can be used in the
+.Va mb_copy
+function
+.El
+.Pp
+.Fn mb_done
+function disposes an mbuf chain pointed to by
+.Fa mbp->mb_top
+field and sets
+the field to
+.Dv NULL .
+.Pp
+.Fn mb_detach
+function returns the value of
+.Fa mbp->mb_top
+field and sets its value to
+.Dv NULL .
+.Pp
+.Fn mb_fixhdr
+recalculates the length of an mbuf chain and updates the
+.Va m_pkthdr.len
+field of the first mbuf in the chain.
+.Pp
+.Fn mb_reserve
+ensures that the object of the length specified by the
+.Fa size
+argument will fit in the current mbuf (mbuf allocation is performed if
+necessary), and advances all pointers as if the real data was placed.
+Returned
+value will point to the beginning of the reserved space.
+Note that the size
+of the object should not exceed
+.Dv MLEN
+bytes.
+.Pp
+All
+.Fn mb_put_*
+functions perform an actual copy of the data into mbuf chain.
+Functions which have
+.Cm le
+or
+.Cm be
+suffixes will perform conversion to the little\- or big\-endian data formats.
+.Pp
+.Fn mb_put_mem
+function copies
+.Fa size
+bytes of data specified by the
+.Fa source
+argument to 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
+.It Dv MB_MZERO
+do not copy any data, but just fill the destination with zero bytes
+.It Dv MB_MCUSTOM
+call function specified by the
+.Fa mbp->mb_copy
+field
+.El
+.Sh RETURN VALUES
+All
+.Ft int
+functions return zero if successful,
+otherwise error code is returned.
+.Pp
+.Em Note :
+after failure of any function, an mbuf chain is left in the broken state,
+and only
+.Fn mb_done
+function can safely be called to destroy it.
+.Sh EXAMPLES
+.Bd -literal
+struct mbchain *mbp;
+struct mbuf *m;
+
+mb_init(mbp);
+mb_put_uint8(mbp, 33);
+mb_put_uint16le(mbp, length);
+m = m_copym(mbp->mb_top, 0, M_COPYALL, M_TRYWAIT);
+send(m);
+mb_done(mbp);
+.Ed
+.Sh SEE ALSO
+.Xr mbuf 9 ,
+.Xr mdchain 9
+.Sh AUTHORS
+This manual page was written by
+.An Boris Popov Aq bp@FreeBSD.org .