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.3 2004/12/18 21:55:21 liamfoy 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 106An mbuf is a basic unit of memory management in the kernel IPC subsystem. 107Network packets and socket buffers are stored in mbufs. 108A network packet may span multiple mbufs arranged into a chain 109(linked list), 110which allows adding or trimming 111network headers with little overhead. 112.Pp 113While a developer should not bother with mbuf internals without serious 114reason in order to avoid incompatibilities with future changes, it 115is useful to understand the mbuf's general structure. 116.Pp 117An mbuf consists of a variable-sized header and a small internal 118buffer for data. 119The mbuf's total size, 120.Dv MSIZE , 121is a machine-dependent constant defined in 122.Pa machine/param.h . 123The mbuf header includes: 124.Pp 125.Bl -tag -width "m_nextpkt" -compact -offset indent 126.It Fa m_next 127a pointer to the next buffer in the chain 128.It Fa m_nextpkt 129a pointer to the next chain in the queue 130.It Fa m_data 131a pointer to the data 132.It Fa m_len 133the length of the data 134.It Fa m_type 135the type of data 136.It Fa m_flags 137the mbuf flags 138.El 139.Pp 140The 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 160The 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 172If the 173.Dv M_PKTHDR 174flag is set, a 175.Li struct pkthdr m_pkthdr 176is added to the mbuf header. 177It contains a pointer to the interface 178the packet has been received from 179.Pq Fa struct ifnet *rcvif , 180and the total packet length 181.Pq Fa int len . 182.Pp 183If small enough, data is stored in the mbuf's internal data buffer. 184If the data is sufficiently large, another mbuf may be added to the chain, 185or external storage may be associated with the mbuf. 186.Dv MHLEN 187bytes of data can fit into an mbuf with the 188.Dv M_PKTHDR 189flag set, 190.Dv MLEN 191bytes can otherwise. 192.Pp 193If external storage is being associated with an mbuf, the 194.Dv m_ext 195header is added at the cost of losing the internal data buffer. 196It includes a pointer to external storage, the size of the storage, 197a pointer to a function used for freeing the storage, 198a pointer to an optional argument that can be passed to the function, 199and a pointer to a reference counter. 200An mbuf using external storage has the 201.Dv M_EXT 202flag set. 203.Pp 204The system supplies a default type of external storage buffer called an 205.Dq mbuf cluster . 206Mbuf clusters can be allocated and configured with the use of the 207.Dv MCLGET 208macro. 209Each cluster is 210.Dv MCLBYTES 211in size, where MCLBYTES is 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 255kern.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 malloc 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.El 465.Sh RETURN VALUES 466See above. 467.Sh HISTORY 468.\" Please correct me if I'm wrong 469Mbufs appeared in an early version of 470.Bx . 471Besides for being used for network packets, they were used 472to store various dynamic structures, such as routing table 473entries, interface addresses, protocol control blocks, etc. 474.Sh AUTHORS 475The original 476.Nm 477man page was written by Yar Tikhiy. 478