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.\" $FreeBSD$ 26.\" 27.Dd February 20, 2001 28.Dt MBCHAIN 9 29.Os 30.Sh NAME 31.Nm mbchain , 32.Nm mb_init , 33.Nm mb_initm , 34.Nm mb_done , 35.Nm mb_detach , 36.Nm mb_fixhdr , 37.Nm mb_reserve , 38.Nm mb_put_uint8 , 39.Nm mb_put_uint16be , 40.Nm mb_put_uint16le , 41.Nm mb_put_uint32be , 42.Nm mb_put_uint32le , 43.Nm mb_put_int64be , 44.Nm mb_put_int64le , 45.Nm mb_put_mem , 46.Nm mb_put_mbuf , 47.Nm mb_put_uio 48.Nd "set of functions to build an mbuf chain from various data types" 49.Sh SYNOPSIS 50.Cd options LIBMCHAIN 51.Li kldload libmchain 52.Pp 53.In sys/param.h 54.In sys/uio.h 55.In sys/mchain.h 56.Ft int 57.Fn mb_init "struct mbchain *mbp" 58.Ft void 59.Fn mb_initm "struct mbchain *mbp" "struct mbuf *m" 60.Ft void 61.Fn mb_done "struct mbchain *mbp" 62.Ft struct mbuf * 63.Fn mb_detach "struct mbchain *mbp" 64.Ft int 65.Fn mb_fixhdr "struct mbchain *mbp" 66.Ft caddr_t 67.Fn mb_reserve "struct mbchain *mbp" "int size" 68.Ft int 69.Fn mb_put_uint8 "struct mbchain *mbp" "u_int8_t x" 70.Ft int 71.Fn mb_put_uint16be "struct mbchain *mbp" "u_int16_t x" 72.Ft int 73.Fn mb_put_uint16le "struct mbchain *mbp" "u_int16_t x" 74.Ft int 75.Fn mb_put_uint32be "struct mbchain *mbp" "u_int32_t x" 76.Ft int 77.Fn mb_put_uint32le "struct mbchain *mbp" "u_int32_t x" 78.Ft int 79.Fn mb_put_int64be "struct mbchain *mbp" "int64_t x" 80.Ft int 81.Fn mb_put_int64le "struct mbchain *mbp" "int64_t x" 82.Ft int 83.Fn mb_put_mem "struct mbchain *mbp" "c_caddr_t source" "int size" "int type" 84.Ft int 85.Fn mb_put_mbuf "struct mbchain *mbp" "struct mbuf *m" 86.Ft int 87.Fn mb_put_uio "struct mbchain *mbp" "struct uio *uiop" "int size" 88.Sh DESCRIPTION 89These functions are used to compose mbuf chains from various data types. 90The 91.Vt mbchain 92structure is used as a working context and should be initialized with a call 93to either 94.Fn mb_init 95or 96.Fn mb_initm . 97It has the following fields: 98.Bl -tag -width ".Va mb_count" 99.It Va "mb_top" 100.Pq Vt "struct mbuf *" 101A pointer to the top of constructed mbuf chain. 102.It Va mb_cur 103.Pq Vt "struct mbuf *" 104A pointer to the currently filled mbuf. 105.It Va mb_mleft 106.Pq Vt int 107Number of bytes left in the current mbuf. 108.It Va mb_count 109.Pq Vt int 110Total number of bytes placed in the mbuf chain. 111.It Va mb_copy 112.Pq Vt "mb_copy_t *" 113User-defined function to perform a copy into mbuf; 114useful if any unusual 115data conversion is necessary. 116.It Va mb_udata 117.Pq Vt "void *" 118User-supplied data which can be used in the 119.Va mb_copy 120function. 121.El 122.Pp 123.Fn mb_done 124function disposes an mbuf chain pointed to by 125.Fa mbp->mb_top 126field and sets 127the field to 128.Dv NULL . 129.Pp 130.Fn mb_detach 131function returns the value of 132.Fa mbp->mb_top 133field and sets its value to 134.Dv NULL . 135.Pp 136.Fn mb_fixhdr 137recalculates the length of an mbuf chain and updates the 138.Va m_pkthdr.len 139field of the first mbuf in the chain. 140It returns the calculated length. 141.Pp 142.Fn mb_reserve 143ensures that the object of the length specified by the 144.Fa size 145argument will fit in the current mbuf (mbuf allocation is performed if 146necessary), and advances all pointers as if the real data was placed. 147Returned 148value will point to the beginning of the reserved space. 149Note that the size 150of the object should not exceed 151.Dv MLEN 152bytes. 153.Pp 154All 155.Fn mb_put_* 156functions perform an actual copy of the data into mbuf chain. 157Functions which have 158.Cm le 159or 160.Cm be 161suffixes will perform conversion to the little\- or big\-endian data formats. 162.Pp 163.Fn mb_put_mem 164function copies 165.Fa size 166bytes of data specified by the 167.Fa source 168argument to an mbuf chain. 169The 170.Fa type 171argument specifies the method used to perform a copy, 172and can be one of the following: 173.Bl -tag -width ".Dv MB_MINLINE" 174.It Dv MB_MSYSTEM 175Use 176.Fn bcopy 177function. 178.It Dv MB_MUSER 179Use 180.Xr copyin 9 181function. 182.It Dv MB_MINLINE 183Use an 184.Dq inline 185loop which does not call any function. 186.It Dv MB_MZERO 187Do not copy any data, but just fill the destination with zero bytes. 188.It Dv MB_MCUSTOM 189Call function specified by the 190.Fa mbp->mb_copy 191field. 192.El 193.Sh RETURN VALUES 194All 195.Ft int 196functions except 197.Fn mb_fixhdr 198return zero if successful and an error code otherwise. 199.Pp 200.Em Note : 201after failure of any function, an mbuf chain is left in the broken state, 202and only 203.Fn mb_done 204function can safely be called to destroy it. 205.Sh EXAMPLES 206.Bd -literal 207struct mbchain *mbp; 208struct mbuf *m; 209 210mb_init(mbp); 211mb_put_uint8(mbp, 33); 212mb_put_uint16le(mbp, length); 213m = m_copym(mbp->mb_top, 0, M_COPYALL, M_TRYWAIT); 214send(m); 215mb_done(mbp); 216.Ed 217.Sh SEE ALSO 218.Xr mbuf 9 , 219.Xr mdchain 9 220.Sh AUTHORS 221This manual page was written by 222.An Boris Popov Aq bp@FreeBSD.org . 223