share/man/man9/mbuf.9

   1 .\" Copyright (c) 2000 FreeBSD Inc.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL [your name] OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD: src/share/man/man9/mbuf.9,v 1.27.2.1 2003/05/28 13:53:18 yar Exp $
  26 .\" $DragonFly: src/share/man/man9/mbuf.9,v 1.2 2003/06/17 04:37:01 dillon Exp $
  27 .\"
  28 .Dd October 17, 2000
  29 .Dt MBUF 9
  30 .Os
  31 .\"
  32 .Sh NAME
  33 .Nm mbuf
  34 .Nd "memory management in the kernel IPC subsystem"
  35 .\"
  36 .Sh SYNOPSIS
  37 .In sys/param.h
  38 .In sys/systm.h
  39 .In sys/mbuf.h
  40 .\"
  41 .Ss Mbuf allocation macros
  42 .Fn MGET "struct mbuf *mbuf" "int how" "short type"
  43 .Fn MGETHDR "struct mbuf *mbuf" "int how" "short type"
  44 .Fn MCLGET "struct mbuf *mbuf" "int how"
  45 .Fn MFREE "struct mbuf *mbuf" "struct mbuf *successor"
  46 .\"
  47 .Ss Mbuf utility macros
  48 .Ft void *
  49 .Fn mtod "struct mbuf *mbuf" "type"
  50 .Ft int
  51 .Fn M_COPY_PKTHDR "struct mbuf *to" "struct mbuf *from"
  52 .Fn M_ALIGN "struct mbuf *mbuf" "u_int len"
  53 .Fn MH_ALIGN "struct mbuf *mbuf" "u_int len"
  54 .Ft int
  55 .Fn M_LEADINGSPACE "struct mbuf *mbuf"
  56 .Ft int
  57 .Fn M_TRAILINGSPACE "struct mbuf *mbuf"
  58 .Fn M_PREPEND "struct mbuf *mbuf" "int len" "int how"
  59 .Fn MCHTYPE "struct mbuf *mbuf" "u_int type"
  60 .\"
  61 .Ss Mbuf allocation functions
  62 .Ft struct mbuf *
  63 .Fn m_get "int how" "int type"
  64 .Ft struct mbuf *
  65 .Fn m_getm "struct mbuf *orig" "int len" "int how" "int type"
  66 .Ft struct mbuf *
  67 .Fn m_getclr "int how" "int type"
  68 .Ft struct mbuf *
  69 .Fn m_gethdr "int how" "int type"
  70 .Ft struct mbuf *
  71 .Fn m_free "struct mbuf *mbuf"
  72 .Ft void
  73 .Fn m_freem "struct mbuf *mbuf"
  74 .\"
  75 .Ss Mbuf utility functions
  76 .Ft void
  77 .Fn m_adj "struct mbuf *mbuf" "int len"
  78 .Ft struct mbuf *
  79 .Fn m_prepend "struct mbuf *mbuf" "int len" "int how"
  80 .Ft struct mbuf *
  81 .Fn m_pullup "struct mbuf *mbuf" "int len"
  82 .Ft struct mbuf *
  83 .Fn m_copym "struct mbuf *mbuf" "int offset" "int len" "int how"
  84 .Ft struct mbuf *
  85 .Fn m_copypacket "struct mbuf *mbuf" "int how"
  86 .Ft struct mbuf *
  87 .Fn m_dup "struct mbuf *mbuf" "int how"
  88 .Ft void
  89 .Fn m_copydata "const struct mbuf *mbuf" "int offset" "int len" "caddr_t buf"
  90 .Ft void
  91 .Fn m_copyback "struct mbuf *mbuf" "int offset" "int len" "caddr_t buf"
  92 .Ft struct mbuf *
  93 .Fo m_devget
  94 .Fa "char *buf"
  95 .Fa "int len"
  96 .Fa "int offset"
  97 .Fa "struct ifnet *ifp"
  98 .Fa "void (*copy)(char *from, caddr_t to, u_int len)"
  99 .Fc
 100 .Ft void
 101 .Fn m_cat "struct mbuf *m" "struct mbuf *n"
 102 .Ft struct mbuf *
 103 .Fn m_split "struct mbuf *mbuf" "int len" "int how"
 104 .\"
 105 .Sh DESCRIPTION
 106 An mbuf is a basic unit of memory management in the kernel IPC subsystem.
 107 Network packets and socket buffers are stored in mbufs.
 108 A network packet may span multiple mbufs arranged into a chain
 109 (linked list),
 110 which allows adding or trimming
 111 network headers with little overhead.
 112 .Pp
 113 While a developer should not bother with mbuf internals without serious
 114 reason in order to avoid incompatibilities with future changes, it
 115 is useful to understand the mbuf's general structure.
 116 .Pp
 117 An mbuf consists of a variable-sized header and a small internal
 118 buffer for data.
 119 The mbuf's total size,
 120 .Dv MSIZE ,
 121 is a machine-dependent constant defined in
 122 .Pa machine/param.h .
 123 The mbuf header includes:
 124 .Pp
 125 .Bl -tag -width "m_nextpkt" -compact -offset indent
 126 .It Fa m_next
 127 a pointer to the next buffer in the chain
 128 .It Fa m_nextpkt
 129 a pointer to the next chain in the queue
 130 .It Fa m_data
 131 a pointer to the data
 132 .It Fa m_len
 133 the length of the data
 134 .It Fa m_type
 135 the type of data
 136 .It Fa m_flags
 137 the mbuf flags
 138 .El
 139 .Pp
 140 The mbuf flag bits are defined as follows:
 141 .Bd -literal
 142 /* mbuf flags */
 143 #define M_EXT           0x0001  /* has associated external storage */
 144 #define M_PKTHDR        0x0002  /* start of record */
 145 #define M_EOR           0x0004  /* end of record */
 146 #define M_PROTO1        0x0010  /* protocol-specific */
 147 #define M_PROTO2        0x0020  /* protocol-specific */
 148 #define M_PROTO3        0x0040  /* protocol-specific */
 149 #define M_PROTO4        0x0080  /* protocol-specific */
 150 #define M_PROTO5        0x0100  /* protocol-specific */
 151
 152 /* mbuf pkthdr flags, also in m_flags */
 153 #define M_BCAST         0x0200  /* send/received as link-level broadcast */
 154 #define M_MCAST         0x0400  /* send/received as link-level multicast */
 155 #define M_FRAG          0x0800  /* packet is fragment of larger packet */
 156 #define M_FIRSTFRAG     0x1000  /* packet is first fragment */
 157 #define M_LASTFRAG      0x2000  /* packet is last fragment */
 158 .Ed
 159 .Pp
 160 The available mbuf types are defined as follows:
 161 .Bd -literal
 162 /* mbuf types */
 163 #define MT_FREE         0       /* should be on free list */
 164 #define MT_DATA         1       /* dynamic (data) allocation */
 165 #define MT_HEADER       2       /* packet header */
 166 #define MT_SONAME       8       /* socket name */
 167 #define MT_FTABLE       11      /* fragment reassembly header */
 168 #define MT_CONTROL      14      /* extra-data protocol message */
 169 #define MT_OOBDATA      15      /* expedited data  */
 170 .Ed
 171 .Pp
 172 If the
 173 .Dv M_PKTHDR
 174 flag is set, a
 175 .Li struct pkthdr m_pkthdr
 176 is added to the mbuf header.
 177 It contains a pointer to the interface
 178 the packet has been received from
 179 .Pq Fa struct ifnet *rcvif ,
 180 and the total packet length
 181 .Pq Fa int len .
 182 .Pp
 183 If small enough, data is stored in the mbuf's internal data buffer.
 184 If the data is sufficiently large, another mbuf may be added to the chain,
 185 or external storage may be associated with the mbuf.
 186 .Dv MHLEN
 187 bytes of data can fit into an mbuf with the
 188 .Dv M_PKTHDR
 189 flag set,
 190 .Dv MLEN
 191 bytes can otherwise.
 192 .Pp
 193 If external storage is being associated with an mbuf, the
 194 .Dv m_ext
 195 header is added at the cost of losing the internal data buffer.
 196 It includes a pointer to external storage, the size of the storage,
 197 a pointer to a function used for freeing the storage,
 198 a pointer to an optional argument that can be passed to the function,
 199 and a pointer to a reference counter.
 200 An mbuf using external storage has the
 201 .Dv M_EXT
 202 flag set.
 203 .Pp
 204 The system supplies a default type of external storage buffer called an
 205 .Dq mbuf cluster .
 206 Mbuf clusters can be allocated and configured with the use of the
 207 .Dv MCLGET
 208 macro.
 209 Each cluster is
 210 .Dv MCLBYTES
 211 in size, where MCLBYTES is a machine-dependent constant.
 212 The system defines an advisory macro
 213 .Dv MINCLSIZE ,
 214 which is the smallest amount of data to put into a cluster.
 215 It's equal to the sum of
 216 .Dv MLEN
 217 and
 218 .Dv MHLEN .
 219 It is typically preferable to store data into an mbuf's data region, if size
 220 permits, as opposed to allocating a separate mbuf cluster to hold the same
 221 data.
 222 .\"
 223 .Ss Macros and Functions
 224 There are numerous predefined macros and functions that provide the
 225 developer with common utilities.
 226 .\"
 227 .Bl -ohang -offset indent
 228 .It Fn mtod mbuf type
 229 Convert an mbuf pointer to a data pointer.
 230 The macro expands to the data pointer cast to the pointer of the specified type.
 231 .Sy Note :
 232 It is advisable to ensure that there is enough contiguous data in the mbuf.
 233 See
 234 .Fn m_pullup
 235 for details.
 236 .It Fn MGET mbuf how type
 237 Allocate an mbuf and initialize it to contain internal data.
 238 .Fa mbuf
 239 will point to the allocated mbuf on success, or be set to
 240 .Dv NULL
 241 on failure.
 242 The
 243 .Fa how
 244 argument is to be set to
 245 .Dv M_WAIT
 246 or
 247 .Dv M_DONTWAIT .
 248 It specifies whether the caller is willing to block if necessary.
 249 If
 250 .Fa how
 251 is set to
 252 .Dv M_WAIT ,
 253 a failed allocation will result in the caller being put
 254 to sleep for a designated
 255 kern.ipc.mbuf_wait
 256 .Xr ( sysctl 8
 257 tunable)
 258 number of ticks.
 259 A number of other mbuf-related
 260 functions and macros have the same argument because they may
 261 at some point need to allocate new mbufs.
 262 .Pp
 263 Programmers should be careful not to confuse the mbuf allocation flag
 264 .Dv M_DONTWAIT
 265 with the
 266 .Xr malloc 9
 267 allocation flag,
 268 .Dv M_NOWAIT .
 269 They are not the same.
 270 .It Fn MGETHDR mbuf how type
 271 Allocate an mbuf and initialize it to contain a packet header
 272 and internal data.
 273 See
 274 .Fn MGET
 275 for details.
 276 .It Fn MCLGET mbuf how
 277 Allocate and attach an mbuf cluster to an mbuf.
 278 If the macro fails, the
 279 .Dv M_EXT
 280 flag won't be set in the mbuf.
 281 .It Fn M_PREPEND mbuf len how
 282 This macro operates on an mbuf chain.
 283 It is an optimized wrapper for
 284 .Fn m_prepend
 285 that can make use of possible empty space before data
 286 (e.g. left after trimming of a link-layer header).
 287 The new chain pointer or
 288 .Dv NULL
 289 is in
 290 .Fa mbuf
 291 after the call.
 292 .El
 293 .Pp
 294 The functions are:
 295 .Bl -ohang -offset indent
 296 .It Fn m_get how type
 297 A function version of
 298 .Fn MGET
 299 for non-critical paths.
 300 .It Fn m_getm orig len how type
 301 Allocate
 302 .Fa len
 303 bytes worth of mbufs and mbuf clusters if necessary and append the resulting
 304 allocated chain to the
 305 .Fa orig
 306 mbuf chain, if it is
 307 .No non- Ns Dv NULL .
 308 If the allocation fails at any point,
 309 free whatever was allocated and return
 310 .Dv NULL .
 311 If
 312 .Fa orig
 313 is
 314 .No non- Ns Dv NULL ,
 315 it will not be freed.
 316 It is possible to use
 317 .Fn m_getm
 318 to either append
 319 .Fa len
 320 bytes to an existing mbuf or mbuf chain
 321 (for example, one which may be sitting in a pre-allocated ring)
 322 or to simply perform an all-or-nothing mbuf and mbuf cluster allocation.
 323 .It Fn m_gethdr how type
 324 A function version of
 325 .Fn MGETHDR
 326 for non-critical paths.
 327 .It Fn m_getclr how type
 328 Allocate an mbuf and zero out the data region.
 329 .El
 330 .Pp
 331 The functions below operate on mbuf chains.
 332 .Bl -ohang -offset indent
 333 .It Fn m_freem mbuf
 334 Free an entire mbuf chain, including any external
 335 storage.
 336 .\"
 337 .It Fn m_adj mbuf len
 338 Trim
 339 .Fa len
 340 bytes from the head of an mbuf chain if
 341 .Fa len
 342 is positive, from the tail otherwise.
 343 .\"
 344 .It Fn m_prepend mbuf len how
 345 Allocate a new mbuf and prepend it to the chain, handle
 346 .Dv M_PKTHDR
 347 properly.
 348 .Sy Note :
 349 It doesn't allocate any clusters, so
 350 .Fa len
 351 must be less than
 352 .Dv MLEN
 353 or
 354 .Dv MHLEN ,
 355 depending on the
 356 .Dv M_PKTHDR
 357 flag setting.
 358 .\"
 359 .It Fn m_pullup mbuf len
 360 Arrange that the first
 361 .Fa len
 362 bytes of an mbuf chain are contiguous and lay in the data area of
 363 .Fa mbuf ,
 364 so they are accessible with
 365 .Fn mtod mbuf type .
 366 Return the new chain on success,
 367 .Dv NULL
 368 on failure
 369 (the chain is freed in this case).
 370 .Sy Note :
 371 It doesn't allocate any clusters, so
 372 .Fa len
 373 must be less than
 374 .Dv MHLEN .
 375 .\"
 376 .It Fn m_copym mbuf offset len how
 377 Make a copy of an mbuf chain starting
 378 .Fa offset
 379 bytes from the beginning, continuing for
 380 .Fa len
 381 bytes.
 382 If
 383 .Fa len
 384 is
 385 .Dv M_COPYALL ,
 386 copy to the end of the mbuf chain.
 387 .Sy Note :
 388 The copy is read-only, because clusters are not
 389 copied, only their reference counts are incremented.
 390 .\"
 391 .It Fn m_copypacket mbuf how
 392 Copy an entire packet including header, which must be present.
 393 This is an optimized version of the common case
 394 .Fn m_copym mbuf 0 M_COPYALL how .
 395 .Sy Note :
 396 the copy is read-only, because clusters are not
 397 copied, only their reference counts are incremented.
 398 .\"
 399 .It Fn m_dup mbuf how
 400 Copy a packet header mbuf chain into a completely new chain, including
 401 copying any mbuf clusters.
 402 Use this instead of
 403 .Fn m_copypacket
 404 when you need a writable copy of an mbuf chain.
 405 .\"
 406 .It Fn m_copydata mbuf offset len buf
 407 Copy data from an mbuf chain starting
 408 .Fa off
 409 bytes from the beginning, continuing for
 410 .Fa len
 411 bytes, into the indicated buffer
 412 .Fa buf .
 413 .\"
 414 .It Fn m_copyback mbuf offset len buf
 415 Copy
 416 .Fa len
 417 bytes from the buffer
 418 .Fa buf
 419 back into the indicated mbuf chain,
 420 starting at
 421 .Fa offset
 422 bytes from the beginning of the chain, extending the mbuf chain if necessary.
 423 .Sy Note :
 424 It doesn't allocate any clusters, just adds mbufs to the chain.
 425 It's safe to set
 426 .Fa offset
 427 beyond the current chain end: zeroed mbufs will be allocated to fill the
 428 space.
 429 .\"
 430 .It Fn m_devget buf len offset ifp copy
 431 Copy data from a device local memory pointed to by
 432 .Fa buf
 433 to an mbuf chain.
 434 The copy is done using a specified copy routine
 435 .Fa copy ,
 436 or
 437 .Fn bcopy
 438 if
 439 .Fa copy
 440 is
 441 .Dv NULL .
 442 .\"
 443 .It Fn m_cat m n
 444 Concatenate
 445 .Fa n
 446 to
 447 .Fa m .
 448 Both chains must be of the same type.
 449 .Fa N
 450 is still valid after the function returned.
 451 .Sy Note :
 452 It does not handle
 453 .Dv M_PKTHDR
 454 and friends.
 455 .\"
 456 .It Fn m_split mbuf len how
 457 Partition an mbuf chain in two pieces, returning the tail:
 458 all but the first
 459 .Fa len
 460 bytes.
 461 In case of failure, it returns
 462 .Dv NULL
 463 and attempts to restore the chain to its original state.
 464 .El
 465 .Sh RETURN VALUES
 466 See above.
 467 .Sh HISTORY
 468 .\" Please correct me if I'm wrong
 469 Mbufs appeared in an early version of
 470 .Bx .
 471 Besides for being used for network packets, they were used
 472 to store various dynamic structures, such as routing table
 473 entries, interface addresses, protocol control blocks, etc.
 474 .Sh AUTHORS
 475 The original
 476 .Nm
 477 man page was written by Yar Tikhiy.