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