share/man/man9/mbchain.9

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