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. 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 "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 return zero if successful, 195otherwise error code is returned. 196.Pp 197.Em Note : 198after failure of any function, an mbuf chain is left in the broken state, 199and only 200.Fn mb_done 201function can safely be called to destroy it. 202.Sh EXAMPLES 203.Bd -literal 204struct mbchain *mbp; 205struct mbuf *m; 206 207mb_init(mbp); 208mb_put_uint8(mbp, 33); 209mb_put_uint16le(mbp, length); 210m = m_copym(mbp->mb_top, 0, M_COPYALL, M_TRYWAIT); 211send(m); 212mb_done(mbp); 213.Ed 214.Sh SEE ALSO 215.Xr mbuf 9 , 216.Xr mdchain 9 217.Sh AUTHORS 218This manual page was written by 219.An Boris Popov Aq bp@FreeBSD.org . 220