Add documentation for mchain API.
Reviewed by: asmodai, ru (mbchain.9)
This commit is contained in:
Boris Popov
parent
f2acaea1b4
commit
a1a5ca5514
@ -20,7 +20,8 @@ MAN9= CONDSPLASSERT.9 DECLARE_MODULE.9 DELAY.9 KASSERT.9 MD5.9 SPLASSERT.9 \
|
||||
get_cyclecounter.9 \
|
||||
ifnet.9 inittodr.9 intro.9 ithread.9 \
|
||||
kernacc.9 kthread.9 \
|
||||
malloc.9 make_dev.9 mbuf.9 microseq.9 microtime.9 microuptime.9 \
|
||||
malloc.9 make_dev.9 mbuf.9 mbchain.9 mdchain.9 \
|
||||
microseq.9 microtime.9 microuptime.9 \
|
||||
mi_switch.9 module.9 mutex.9 \
|
||||
namei.9 \
|
||||
panic.9 pfil.9 physio.9 posix4.9 psignal.9 \
|
||||
@ -167,6 +168,41 @@ MLINKS+=BUS_SETUP_INTR.9 BUS_TEARDOWN_INTR.9
|
||||
MLINKS+=BUS_SETUP_INTR.9 bus_teardown_intr.9
|
||||
MLINKS+=bus_generic_read_ivar.9 bus_generic_write_ivar.9
|
||||
|
||||
MLINKS+=mbchain.9 mb_init.9
|
||||
MLINKS+=mbchain.9 mb_initm.9
|
||||
MLINKS+=mbchain.9 mb_done.9
|
||||
MLINKS+=mbchain.9 mb_detach.9
|
||||
MLINKS+=mbchain.9 mb_fixhdr.9
|
||||
MLINKS+=mbchain.9 mb_reserve.9
|
||||
MLINKS+=mbchain.9 mb_put_uint8.9
|
||||
MLINKS+=mbchain.9 mb_put_uint16be.9
|
||||
MLINKS+=mbchain.9 mb_put_uint16le.9
|
||||
MLINKS+=mbchain.9 mb_put_uint32be.9
|
||||
MLINKS+=mbchain.9 mb_put_uint32le.9
|
||||
MLINKS+=mbchain.9 mb_put_int64be.9
|
||||
MLINKS+=mbchain.9 mb_put_int64le.9
|
||||
MLINKS+=mbchain.9 mb_put_mem.9
|
||||
MLINKS+=mbchain.9 mb_put_mbuf.9
|
||||
MLINKS+=mbchain.9 mb_put_uio.9
|
||||
|
||||
MLINKS+=mdchain.9 md_initm.9
|
||||
MLINKS+=mdchain.9 md_done.9
|
||||
MLINKS+=mdchain.9 md_append_record.9
|
||||
MLINKS+=mdchain.9 md_next_record.9
|
||||
MLINKS+=mdchain.9 md_get_uint8.9
|
||||
MLINKS+=mdchain.9 md_get_uint16.9
|
||||
MLINKS+=mdchain.9 md_get_uint16be.9
|
||||
MLINKS+=mdchain.9 md_get_uint16le.9
|
||||
MLINKS+=mdchain.9 md_get_uint32.9
|
||||
MLINKS+=mdchain.9 md_get_uint32be.9
|
||||
MLINKS+=mdchain.9 md_get_uint32le.9
|
||||
MLINKS+=mdchain.9 md_get_int64.9
|
||||
MLINKS+=mdchain.9 md_get_int64be.9
|
||||
MLINKS+=mdchain.9 md_get_int64le.9
|
||||
MLINKS+=mdchain.9 md_get_mem.9
|
||||
MLINKS+=mdchain.9 md_get_mbuf.9
|
||||
MLINKS+=mdchain.9 md_get_uio.9
|
||||
|
||||
MLINKS+=microtime.9 getmicrotime.9 microtime.9 nanotime.9
|
||||
MLINKS+=microtime.9 getnanotime.9
|
||||
MLINKS+=microuptime.9 getmicrouptime.9 microuptime.9 nanouptime.9
|
||||
|
||||
219
share/man/man9/mbchain.9
Normal file
219
share/man/man9/mbchain.9
Normal file
@ -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 .
|
||||
208
share/man/man9/mdchain.9
Normal file
208
share/man/man9/mdchain.9
Normal file
@ -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 .
|
||||
Loading…
Reference in New Issue
Block a user