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