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.8 2007/08/18 18:58:20 swildner Exp $ 27.\" 28.Dd September 17, 2010 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.\" 46.Ss Mbuf utility macros 47.Ft void * 48.Fn mtod "struct mbuf *mbuf" "type" 49.Fn M_ALIGN "struct mbuf *mbuf" "u_int len" 50.Fn MH_ALIGN "struct mbuf *mbuf" "u_int len" 51.Ft int 52.Fn M_LEADINGSPACE "struct mbuf *mbuf" 53.Ft int 54.Fn M_TRAILINGSPACE "struct mbuf *mbuf" 55.Fn M_PREPEND "struct mbuf *mbuf" "int len" "int how" 56.\" 57.Ss Mbuf allocation functions 58.Ft struct mbuf * 59.Fn m_get "int how" "int type" 60.Ft struct mbuf * 61.Fn m_getm "struct mbuf *orig" "int len" "int how" "int type" 62.Ft struct mbuf * 63.Fn m_getclr "int how" "int type" 64.Ft struct mbuf * 65.Fn m_gethdr "int how" "int type" 66.Ft struct mbuf * 67.Fn m_free "struct mbuf *mbuf" 68.Ft void 69.Fn m_freem "struct mbuf *mbuf" 70.\" 71.Ss Mbuf utility functions 72.Ft void 73.Fn m_adj "struct mbuf *mbuf" "int len" 74.Ft struct mbuf * 75.Fn m_prepend "struct mbuf *mbuf" "int len" "int how" 76.Ft struct mbuf * 77.Fn m_pullup "struct mbuf *mbuf" "int len" 78.Ft struct mbuf * 79.Fn m_copym "struct mbuf *mbuf" "int offset" "int len" "int how" 80.Ft struct mbuf * 81.Fn m_copypacket "struct mbuf *mbuf" "int how" 82.Ft struct mbuf * 83.Fn m_dup "struct mbuf *mbuf" "int how" 84.Ft void 85.Fn m_copydata "const struct mbuf *mbuf" "int offset" "int len" "caddr_t buf" 86.Ft void 87.Fn m_copyback "struct mbuf *mbuf" "int offset" "int len" "caddr_t buf" 88.Ft struct mbuf * 89.Fo m_devget 90.Fa "char *buf" 91.Fa "int len" 92.Fa "int offset" 93.Fa "struct ifnet *ifp" 94.Fa "void (*copy)(char *from, caddr_t to, u_int len)" 95.Fc 96.Ft void 97.Fn m_cat "struct mbuf *m" "struct mbuf *n" 98.Ft struct mbuf * 99.Fn m_split "struct mbuf *mbuf" "int len" "int how" 100.Ft struct mbuf * 101.Fn m_unshare "struct mbuf *mbuf" "int how" 102.\" 103.Sh DESCRIPTION 104An mbuf is a basic unit of memory management in the kernel IPC subsystem. 105Network packets and socket buffers are stored in mbufs. 106A network packet may span multiple mbufs arranged into a chain 107(linked list), 108which allows adding or trimming 109network headers with little overhead. 110.Pp 111While a developer should not bother with mbuf internals without serious 112reason in order to avoid incompatibilities with future changes, it 113is useful to understand the mbuf's general structure. 114.Pp 115An mbuf consists of a variable-sized header and a small internal 116buffer for data. 117The mbuf's total size, 118.Dv MSIZE , 119is a machine-dependent constant defined in 120.In machine/param.h . 121The mbuf header includes: 122.Pp 123.Bl -tag -width "m_nextpkt" -compact -offset indent 124.It Fa m_next 125a pointer to the next buffer in the chain 126.It Fa m_nextpkt 127a pointer to the next chain in the queue 128.It Fa m_data 129a pointer to the data 130.It Fa m_len 131the length of the data 132.It Fa m_type 133the type of data 134.It Fa m_flags 135the mbuf flags 136.El 137.Pp 138The mbuf flag bits are defined as follows: 139.Bd -literal 140/* mbuf flags */ 141#define M_EXT 0x0001 /* has associated external storage */ 142#define M_PKTHDR 0x0002 /* start of record */ 143#define M_EOR 0x0004 /* end of record */ 144#define M_PROTO1 0x0010 /* protocol-specific */ 145#define M_PROTO2 0x0020 /* protocol-specific */ 146#define M_PROTO3 0x0040 /* protocol-specific */ 147#define M_PROTO4 0x0080 /* protocol-specific */ 148#define M_PROTO5 0x0100 /* protocol-specific */ 149 150/* mbuf pkthdr flags, also in m_flags */ 151#define M_BCAST 0x0200 /* send/received as link-level broadcast */ 152#define M_MCAST 0x0400 /* send/received as link-level multicast */ 153#define M_FRAG 0x0800 /* packet is fragment of larger packet */ 154#define M_FIRSTFRAG 0x1000 /* packet is first fragment */ 155#define M_LASTFRAG 0x2000 /* packet is last fragment */ 156.Ed 157.Pp 158The available mbuf types are defined as follows: 159.Bd -literal 160/* mbuf types */ 161#define MT_FREE 0 /* should be on free list */ 162#define MT_DATA 1 /* dynamic (data) allocation */ 163#define MT_HEADER 2 /* packet header */ 164#define MT_SONAME 8 /* socket name */ 165#define MT_FTABLE 11 /* fragment reassembly header */ 166#define MT_CONTROL 14 /* extra-data protocol message */ 167#define MT_OOBDATA 15 /* expedited data */ 168.Ed 169.Pp 170If the 171.Dv M_PKTHDR 172flag is set, a 173.Li struct pkthdr m_pkthdr 174is added to the mbuf header. 175It contains a pointer to the interface 176the packet has been received from 177.Pq Fa struct ifnet *rcvif , 178and the total packet length 179.Pq Fa int len . 180.Pp 181If small enough, data is stored in the mbuf's internal data buffer. 182If the data is sufficiently large, another mbuf may be added to the chain, 183or external storage may be associated with the mbuf. 184.Dv MHLEN 185bytes of data can fit into an mbuf with the 186.Dv M_PKTHDR 187flag set, 188.Dv MLEN 189bytes can otherwise. 190.Pp 191If external storage is being associated with an mbuf, the 192.Dv m_ext 193header is added at the cost of losing the internal data buffer. 194It includes a pointer to external storage, the size of the storage, 195a pointer to a function used for freeing the storage, 196a pointer to an optional argument that can be passed to the function, 197and a pointer to a reference counter. 198An mbuf using external storage has the 199.Dv M_EXT 200flag set. 201.Pp 202The system supplies a default type of external storage buffer called an 203.Dq mbuf cluster . 204Mbuf clusters can be allocated and configured with the use of the 205.Dv MCLGET 206macro. 207Each cluster is 208.Dv MCLBYTES 209in size, where 210.Dv MCLBYTES 211is a machine-dependent constant. 212The system defines an advisory macro 213.Dv MINCLSIZE , 214which is the smallest amount of data to put into a cluster. 215It's equal to the sum of 216.Dv MLEN 217and 218.Dv MHLEN . 219It is typically preferable to store data into an mbuf's data region, if size 220permits, as opposed to allocating a separate mbuf cluster to hold the same 221data. 222.\" 223.Ss Macros and Functions 224There are numerous predefined macros and functions that provide the 225developer with common utilities. 226.\" 227.Bl -ohang -offset indent 228.It Fn mtod mbuf type 229Convert an mbuf pointer to a data pointer. 230The macro expands to the data pointer cast to the pointer of the specified type. 231.Sy Note : 232It is advisable to ensure that there is enough contiguous data in the mbuf. 233See 234.Fn m_pullup 235for details. 236.It Fn MGET mbuf how type 237Allocate an mbuf and initialize it to contain internal data. 238.Fa mbuf 239will point to the allocated mbuf on success, or be set to 240.Dv NULL 241on failure. 242The 243.Fa how 244argument is to be set to 245.Dv MB_WAIT 246or 247.Dv MB_DONTWAIT . 248It specifies whether the caller is willing to block if necessary. 249If 250.Fa how 251is set to 252.Dv MB_WAIT , 253a failed allocation will result in the caller being put 254to sleep for a designated 255.Va kern.ipc.mbuf_wait 256.Xr ( sysctl 8 257tunable) 258number of ticks. 259A number of other mbuf-related 260functions and macros have the same argument because they may 261at some point need to allocate new mbufs. 262.Pp 263Programmers should be careful not to confuse the mbuf allocation flag 264.Dv MB_DONTWAIT 265with the 266.Xr kmalloc 9 267allocation flag, 268.Dv M_NOWAIT . 269They are not the same. 270.It Fn MGETHDR mbuf how type 271Allocate an mbuf and initialize it to contain a packet header 272and internal data. 273See 274.Fn MGET 275for details. 276.It Fn MCLGET mbuf how 277Allocate and attach an mbuf cluster to an mbuf. 278If the macro fails, the 279.Dv M_EXT 280flag won't be set in the mbuf. 281.It Fn M_PREPEND mbuf len how 282This macro operates on an mbuf chain. 283It is an optimized wrapper for 284.Fn m_prepend 285that can make use of possible empty space before data 286(e.g. left after trimming of a link-layer header). 287The new chain pointer or 288.Dv NULL 289is in 290.Fa mbuf 291after the call. 292.El 293.Pp 294The functions are: 295.Bl -ohang -offset indent 296.It Fn m_get how type 297A function version of 298.Fn MGET 299for non-critical paths. 300.It Fn m_getm orig len how type 301Allocate 302.Fa len 303bytes worth of mbufs and mbuf clusters if necessary and append the resulting 304allocated chain to the 305.Fa orig 306mbuf chain, if it is 307.No non- Ns Dv NULL . 308If the allocation fails at any point, 309free whatever was allocated and return 310.Dv NULL . 311If 312.Fa orig 313is 314.No non- Ns Dv NULL , 315it will not be freed. 316It is possible to use 317.Fn m_getm 318to either append 319.Fa len 320bytes to an existing mbuf or mbuf chain 321(for example, one which may be sitting in a pre-allocated ring) 322or to simply perform an all-or-nothing mbuf and mbuf cluster allocation. 323.It Fn m_gethdr how type 324A function version of 325.Fn MGETHDR 326for non-critical paths. 327.It Fn m_getclr how type 328Allocate an mbuf and zero out the data region. 329.El 330.Pp 331The functions below operate on mbuf chains. 332.Bl -ohang -offset indent 333.It Fn m_freem mbuf 334Free an entire mbuf chain, including any external 335storage. 336.\" 337.It Fn m_adj mbuf len 338Trim 339.Fa len 340bytes from the head of an mbuf chain if 341.Fa len 342is positive, from the tail otherwise. 343.\" 344.It Fn m_prepend mbuf len how 345Allocate a new mbuf and prepend it to the chain, handle 346.Dv M_PKTHDR 347properly. 348.Sy Note : 349It doesn't allocate any clusters, so 350.Fa len 351must be less than 352.Dv MLEN 353or 354.Dv MHLEN , 355depending on the 356.Dv M_PKTHDR 357flag setting. 358.\" 359.It Fn m_pullup mbuf len 360Arrange that the first 361.Fa len 362bytes of an mbuf chain are contiguous and lay in the data area of 363.Fa mbuf , 364so they are accessible with 365.Fn mtod mbuf type . 366Return the new chain on success, 367.Dv NULL 368on failure 369(the chain is freed in this case). 370.Sy Note : 371It doesn't allocate any clusters, so 372.Fa len 373must be less than 374.Dv MHLEN . 375.\" 376.It Fn m_copym mbuf offset len how 377Make a copy of an mbuf chain starting 378.Fa offset 379bytes from the beginning, continuing for 380.Fa len 381bytes. 382If 383.Fa len 384is 385.Dv M_COPYALL , 386copy to the end of the mbuf chain. 387.Sy Note : 388The copy is read-only, because clusters are not 389copied, only their reference counts are incremented. 390.\" 391.It Fn m_copypacket mbuf how 392Copy an entire packet including header, which must be present. 393This is an optimized version of the common case 394.Fn m_copym mbuf 0 M_COPYALL how . 395.Sy Note : 396the copy is read-only, because clusters are not 397copied, only their reference counts are incremented. 398.\" 399.It Fn m_dup mbuf how 400Copy a packet header mbuf chain into a completely new chain, including 401copying any mbuf clusters. 402Use this instead of 403.Fn m_copypacket 404when you need a writable copy of an mbuf chain. 405.\" 406.It Fn m_copydata mbuf offset len buf 407Copy data from an mbuf chain starting 408.Fa off 409bytes from the beginning, continuing for 410.Fa len 411bytes, into the indicated buffer 412.Fa buf . 413.\" 414.It Fn m_copyback mbuf offset len buf 415Copy 416.Fa len 417bytes from the buffer 418.Fa buf 419back into the indicated mbuf chain, 420starting at 421.Fa offset 422bytes from the beginning of the chain, extending the mbuf chain if necessary. 423.Sy Note : 424It doesn't allocate any clusters, just adds mbufs to the chain. 425It's safe to set 426.Fa offset 427beyond the current chain end: zeroed mbufs will be allocated to fill the 428space. 429.\" 430.It Fn m_devget buf len offset ifp copy 431Copy data from a device local memory pointed to by 432.Fa buf 433to an mbuf chain. 434The copy is done using a specified copy routine 435.Fa copy , 436or 437.Fn bcopy 438if 439.Fa copy 440is 441.Dv NULL . 442.\" 443.It Fn m_cat m n 444Concatenate 445.Fa n 446to 447.Fa m . 448Both chains must be of the same type. 449.Fa N 450is still valid after the function returned. 451.Sy Note : 452It does not handle 453.Dv M_PKTHDR 454and friends. 455.\" 456.It Fn m_split mbuf len how 457Partition an mbuf chain in two pieces, returning the tail: 458all but the first 459.Fa len 460bytes. 461In case of failure, it returns 462.Dv NULL 463and attempts to restore the chain to its original state. 464.It Fn m_unshare mbuf how 465Create a version of the specified mbuf chain whose 466contents can be safely modified without affecting other users. 467If allocation fails and this operation can not be completed, 468.Dv NULL 469will be returned. 470The original mbuf chain is always reclaimed and the reference 471count of any shared mbuf clusters is decremented. 472As a side-effect of this process the returned 473mbuf chain may be compacted. 474.Pp 475This function is especially useful in the transmit path of 476network code, when data must be encrypted or otherwise 477altered prior to transmission. 478. 479.El 480.Sh STRESS TESTING 481When running a kernel compiled with the option 482.Dv MBUF_STRESS_TEST , 483the following 484.Xr sysctl 8 Ns 485-controlled options may be used to create 486various failure/extreme cases for testing of network drivers 487and other parts of the kernel that rely on 488.Vt mbufs . 489.Bl -tag -width ident 490.It Va net.inet.ip.mbuf_frag_size 491Causes 492.Fn ip_output 493to fragment outgoing 494.Vt mbuf chains 495into fragments of the specified size. 496Setting this variable to 1 is an excellent way to 497test the long 498.Vt mbuf chain 499handling ability of network drivers. 500.It Va kern.ipc.m_defragrandomfailures 501Causes the function 502.Fn m_defrag 503to randomly fail, returning 504.Dv NULL . 505Any piece of code which uses 506.Fn m_defrag 507should be tested with this feature. 508.El 509.Sh RETURN VALUES 510See above. 511.Sh HISTORY 512.\" Please correct me if I'm wrong 513Mbufs appeared in an early version of 514.Bx . 515Besides for being used for network packets, they were used 516to store various dynamic structures, such as routing table 517entries, interface addresses, protocol control blocks, etc. 518.Sh AUTHORS 519The original 520.Nm 521man page was written by Yar Tikhiy. 522