diff options
author | bp <bp@FreeBSD.org> | 2001-03-10 06:10:48 +0000 |
---|---|---|
committer | bp <bp@FreeBSD.org> | 2001-03-10 06:10:48 +0000 |
commit | e9b6e3c42c951f76647a469ad359e996f72bde27 (patch) | |
tree | 604d8e7c7c8b9d1de5bf0a0413d4439911e25b4a /share/man/man9 | |
parent | eacd05832fdd7e81753bc42090fe802d3d2eeebb (diff) | |
download | FreeBSD-src-e9b6e3c42c951f76647a469ad359e996f72bde27.zip FreeBSD-src-e9b6e3c42c951f76647a469ad359e996f72bde27.tar.gz |
Add documentation for mchain API.
Reviewed by: asmodai, ru (mbchain.9)
Diffstat (limited to 'share/man/man9')
-rw-r--r-- | share/man/man9/Makefile | 38 | ||||
-rw-r--r-- | share/man/man9/mbchain.9 | 219 | ||||
-rw-r--r-- | share/man/man9/mdchain.9 | 208 |
3 files changed, 464 insertions, 1 deletions
diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index 9245e6a..d03f67e 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -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 diff --git a/share/man/man9/mbchain.9 b/share/man/man9/mbchain.9 new file mode 100644 index 0000000..a62580d --- /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 . 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 . |