1.\" -*- nroff -*- 2.\" 3.\" Copyright (c) 2001 Boris Popov 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 15.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 16.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 17.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 18.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 19.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 20.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 21.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 22.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 23.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 24.\" 25.Dd February 20, 2001 26.Dt MBCHAIN 9 27.Os 28.Sh NAME 29.Nm mbchain , 30.Nm mb_init , 31.Nm mb_initm , 32.Nm mb_done , 33.Nm mb_detach , 34.Nm mb_fixhdr , 35.Nm mb_reserve , 36.Nm mb_put_uint8 , 37.Nm mb_put_uint16be , 38.Nm mb_put_uint16le , 39.Nm mb_put_uint32be , 40.Nm mb_put_uint32le , 41.Nm mb_put_int64be , 42.Nm mb_put_int64le , 43.Nm mb_put_mem , 44.Nm mb_put_mbuf , 45.Nm mb_put_uio 46.Nd "set of functions to build an mbuf chain from various data types" 47.Sh SYNOPSIS 48.Cd options LIBMCHAIN 49.Li kldload libmchain 50.Pp 51.In sys/param.h 52.In sys/uio.h 53.In sys/mchain.h 54.Ft int 55.Fn mb_init "struct mbchain *mbp" 56.Ft void 57.Fn mb_initm "struct mbchain *mbp" "struct mbuf *m" 58.Ft void 59.Fn mb_done "struct mbchain *mbp" 60.Ft struct mbuf * 61.Fn mb_detach "struct mbchain *mbp" 62.Ft int 63.Fn mb_fixhdr "struct mbchain *mbp" 64.Ft caddr_t 65.Fn mb_reserve "struct mbchain *mbp" "int size" 66.Ft int 67.Fn mb_put_uint8 "struct mbchain *mbp" "uint8_t x" 68.Ft int 69.Fn mb_put_uint16be "struct mbchain *mbp" "uint16_t x" 70.Ft int 71.Fn mb_put_uint16le "struct mbchain *mbp" "uint16_t x" 72.Ft int 73.Fn mb_put_uint32be "struct mbchain *mbp" "uint32_t x" 74.Ft int 75.Fn mb_put_uint32le "struct mbchain *mbp" "uint32_t x" 76.Ft int 77.Fn mb_put_int64be "struct mbchain *mbp" "int64_t x" 78.Ft int 79.Fn mb_put_int64le "struct mbchain *mbp" "int64_t x" 80.Ft int 81.Fn mb_put_mem "struct mbchain *mbp" "c_caddr_t source" "int size" "int type" 82.Ft int 83.Fn mb_put_mbuf "struct mbchain *mbp" "struct mbuf *m" 84.Ft int 85.Fn mb_put_uio "struct mbchain *mbp" "struct uio *uiop" "int size" 86.Sh DESCRIPTION 87These functions are used to compose mbuf chains from various data types. 88The 89.Vt mbchain 90structure is used as a working context and should be initialized with a call 91to either 92.Fn mb_init 93or 94.Fn mb_initm . 95It has the following fields: 96.Bl -tag -width ".Va mb_count" 97.It Va "mb_top" 98.Pq Vt "struct mbuf *" 99A pointer to the top of constructed mbuf chain. 100.It Va mb_cur 101.Pq Vt "struct mbuf *" 102A pointer to the currently filled mbuf. 103.It Va mb_mleft 104.Pq Vt int 105Number of bytes left in the current mbuf. 106.It Va mb_count 107.Pq Vt int 108Total number of bytes placed in the mbuf chain. 109.It Va mb_copy 110.Pq Vt "mb_copy_t *" 111User-defined function to perform a copy into mbuf; 112useful if any unusual 113data conversion is necessary. 114.It Va mb_udata 115.Pq Vt "void *" 116User-supplied data which can be used in the 117.Va mb_copy 118function. 119.El 120.Pp 121.Fn mb_done 122function disposes an mbuf chain pointed to by 123.Fa mbp->mb_top 124field and sets 125the field to 126.Dv NULL . 127.Pp 128.Fn mb_detach 129function returns the value of 130.Fa mbp->mb_top 131field and sets its value to 132.Dv NULL . 133.Pp 134.Fn mb_fixhdr 135recalculates the length of an mbuf chain and updates the 136.Va m_pkthdr.len 137field of the first mbuf in the chain. 138It returns the calculated length. 139.Pp 140.Fn mb_reserve 141ensures that the object of the length specified by the 142.Fa size 143argument will fit in the current mbuf (mbuf allocation is performed if 144necessary), and advances all pointers as if the real data was placed. 145Returned 146value will point to the beginning of the reserved space. 147Note that the size 148of the object should not exceed 149.Dv MLEN 150bytes. 151.Pp 152All 153.Fn mb_put_* 154functions perform an actual copy of the data into mbuf chain. 155Functions which have 156.Cm le 157or 158.Cm be 159suffixes will perform conversion to the little\- or big\-endian data formats. 160.Pp 161.Fn mb_put_mem 162function copies 163.Fa size 164bytes of data specified by the 165.Fa source 166argument to an mbuf chain. 167The 168.Fa type 169argument specifies the method used to perform a copy, 170and can be one of the following: 171.Bl -tag -width ".Dv MB_MINLINE" 172.It Dv MB_MSYSTEM 173Use 174.Fn bcopy 175function. 176.It Dv MB_MUSER 177Use 178.Xr copyin 9 179function. 180.It Dv MB_MINLINE 181Use an 182.Dq inline 183loop which does not call any function. 184.It Dv MB_MZERO 185Do not copy any data, but just fill the destination with zero bytes. 186.It Dv MB_MCUSTOM 187Call function specified by the 188.Fa mbp->mb_copy 189field. 190.El 191.Sh RETURN VALUES 192All 193.Ft int 194functions except 195.Fn mb_fixhdr 196return zero if successful and an error code otherwise. 197.Pp 198.Em Note : 199after failure of any function, an mbuf chain is left in the broken state, 200and only 201.Fn mb_done 202function can safely be called to destroy it. 203.Sh EXAMPLES 204.Bd -literal 205struct mbchain *mbp; 206struct mbuf *m; 207 208mb_init(mbp); 209mb_put_uint8(mbp, 33); 210mb_put_uint16le(mbp, length); 211m = m_copym(mbp->mb_top, 0, M_COPYALL, M_WAIT); 212send(m); 213mb_done(mbp); 214.Ed 215.Sh SEE ALSO 216.Xr mbuf 9 , 217.Xr mdchain 9 218.Sh AUTHORS 219This manual page was written by 220.An Boris Popov Aq Mt bp@FreeBSD.org . 221