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 <sys/param.h> 37.Fd #include <sys/mbuf.h> 38.\" 39.Ss Mbuf manipulation macros 40.Fn mtod "struct mbuf *mbuf" "any type" 41.Fn MGET "struct mbuf *mbuf" "int how" "short type" 42.Fn MGETHDR "struct mbuf *mbuf" "int how" "short type" 43.Fn MCLGET "struct mbuf *mbuf" "int how" 44.Fn M_PREPEND "struct mbuf *mbuf" "int len" "int how" 45.\" 46.Ss Mbuf manipulation functions 47.Ft struct mbuf * 48.Fn m_get "int how" "int type" 49.Ft struct mbuf * 50.Fn m_getclr "int how" "int type" 51.Ft struct mbuf * 52.Fn m_gethdr "int how" "int type" 53.Ss Mbuf chain manipulation functions 54.Ft void 55.Fn m_freem "struct mbuf *mbuf" 56.Ft void 57.Fn m_adj "struct mbuf *mbuf" "int len" 58.Ft struct mbuf * 59.Fn m_prepend "struct mbuf *mbuf" "int len" "int how" 60.Ft struct mbuf * 61.Fn m_pullup "struct mbuf *mbuf" "int len" 62.Ft struct mbuf * 63.Fn m_copym "struct mbuf *mbuf" "int offset" "int len" "int how" 64.Ft struct mbuf * 65.Fn m_copypacket "struct mbuf *mbuf" "int how" 66.Ft struct mbuf * 67.Fn m_dup "struct mbuf *mbuf" "int how" 68.Ft void 69.Fn m_copydata "struct mbuf *mbuf" "int offset" "int len" "caddr_t buf" 70.Ft void 71.Fn m_copyback "struct mbuf *mbuf" "int offset" "int len" "caddr_t buf" 72.Ft struct mbuf * 73.Fo m_devget 74.Fa "char *buf" 75.Fa "int len" 76.Fa "int offset" 77.Fa "struct ifnet *ifp" 78.Fa "void (*copy)(char *from, caddr_t to, u_int len)" 79.Fc 80.Ft void 81.Fn m_cat "struct mbuf *m" "struct mbuf *n" 82.Ft struct mbuf * 83.Fn m_split "struct mbuf *mbuf" "int len" "int how" 84.\" 85.Sh DESCRIPTION 86Mbuf is a basic unit of memory management in the kernel IPC subsystem. 87Network packets and socket buffers are stored in mbufs. A network packet 88may span multiple mbufs arranged into a chain 89.Pq linked list , 90which allows adding or trimming 91network headers without overhead. 92.Pp 93While a developer should not bother mbuf internals without serious 94reason in order to avoid incompatibilities with future changes, it 95would be useful to know the mbuf general structure. 96.Pp 97Mbuf consists of a variable-length header and a small internal 98buffer for data. Mbuf total size 99.Dv MSIZE 100is a machine-dependent constant defined in 101.Pa machine/param.h . 102The mbuf header includes: 103.Pp 104.Bl -tag -width "m_nextpkt" -compact -offset indent 105.It Fa m_next 106a pointer to the next buffer in the chain 107.It Fa m_nextpkt 108a pointer to the next chain in the queue 109.It Fa m_data 110a pointer to the data 111.It Fa m_len 112the length of the data 113.It Fa m_type 114the type of the data 115.It Fa m_flags 116the mbuf flags 117.El 118.Pp 119The mbuf flag bits are defined as follows: 120.Bd -literal 121/* mbuf flags */ 122#define M_EXT 0x0001 /* has associated external storage */ 123#define M_PKTHDR 0x0002 /* start of record */ 124#define M_EOR 0x0004 /* end of record */ 125#define M_PROTO1 0x0008 /* protocol-specific */ 126#define M_PROTO2 0x0010 /* protocol-specific */ 127#define M_PROTO3 0x0020 /* protocol-specific */ 128#define M_PROTO4 0x0040 /* protocol-specific */ 129#define M_PROTO5 0x0080 /* protocol-specific */ 130 131/* mbuf pkthdr flags, also in m_flags */ 132#define M_BCAST 0x0100 /* send/received as link-level broadcast */ 133#define M_MCAST 0x0200 /* send/received as link-level multicast */ 134#define M_FRAG 0x0400 /* packet is a fragment of a larger packet */ 135#define M_FIRSTFRAG 0x0800 /* packet is first fragment */ 136#define M_LASTFRAG 0x1000 /* packet is last fragment */ 137.Ed 138.Pp 139The possible mbuf types are defined as follows: 140.Bd -literal 141/* mbuf types */ 142#define MT_FREE 0 /* should be on free list */ 143#define MT_DATA 1 /* dynamic (data) allocation */ 144#define MT_HEADER 2 /* packet header */ 145#define MT_SONAME 8 /* socket name */ 146#define MT_FTABLE 11 /* fragment reassembly header */ 147#define MT_CONTROL 14 /* extra-data protocol message */ 148#define MT_OOBDATA 15 /* expedited data */ 149.Ed 150.Pp 151If the 152.Dv M_PKTHDR 153flag is set, a 154.Fa struct pkthdr m_pkthdr 155is added to the mbuf header. It contains a pointer to the interface 156the packet has been received from 157.Pq Fa struct ifnet *rcvif , 158and the total packet length 159.Pq Fa int len . 160.Pp 161Data is placed into the mbuf internal buffer if small enough. If 162it is not, another mbuf may be added to the chain, or external 163storage may be associated with the mbuf. 164.Dv MHLEN 165bytes of data can fit into a mbuf with the 166.Dv M_PKTHDR 167flag set, 168.Dv MLEN 169bytes can otherwise. 170.Pp 171If external storage is being associated with a mbuf, yet another 172header is added at the cost of loosing the internal buffer. It 173includes a pointer to an external buffer, its size, and two pointers 174to storage-specific management routines: one for freeing the buffer, 175and another for accounting references to it. A mbuf using external 176storage has the 177.Dv M_EXT 178flag set. 179.Pp 180The system supplies a macro for allocating 181the external storage in a system-wide pool of fixed-size 182buffers called 183.Dq mbuf clusters , 184each 185.Dv MCLBYTES 186long. 187.Dv MCLBYTES 188is a 189machine-dependent constant. The system defines an advisory macro 190.Dv MINCLSIZE , 191which is the smallest amount of data to put into a cluster. 192It's equal to the sum of 193.Dv MLEN 194and 195.Dv MHLEN . 196The idea is that one should rather add a mbuf to the chain than 197allocate a mbuf cluster, if possible. 198.\" 199.Ss Macros and Functions 200There is plenty of predefined macros and functions that help a 201developer not to worry about mbuf internals. The macros are: 202.\" 203.Bl -ohang -offset indent 204.It Fn mtod mbuf type 205Convert a mbuf pointer to a data pointer. 206The macro expands to the data pointer cast to the pointer to the specified type. 207.Sy Note : 208You must usually ensure that there is enough contiguous data in the mbuf. 209See 210.Fn m_pullup 211for details. 212.It Fn MGET mbuf how type 213Allocate a mbuf and initialize it to contain internal data. 214.Fa Mbuf 215will point to the allocated mbuf on success, or be 216.Dv NULL 217on failure. The 218.Fa how 219argument is to be set to 220.Dv M_WAIT 221or 222.Dv M_DONTWAIT . 223It specifies if the macro can block. If 224.Fa how 225is set to M_WAIT, the macro should never fail, but can block 226forever. A number of other mbuf-related 227functions and macros have the same argument because they may 228need to allocate new mbufs. 229.Sy Caution : 230Never use 231.Dv M_WAIT 232if running at the interrupt level. 233.It Fn MGETHDR mbuf how type 234Allocate a mbuf and initialize it to contain a packet header 235and internal data. See 236.Fn MGET 237for details. 238.It Fn MCLGET mbuf how 239Attach a mbuf cluster to a mbuf. If the macro fails, the 240.Dv M_EXT 241flag won't be set in the mbuf. 242.It Fn M_PREPEND mbuf len how 243This macro operates on a mbuf chain. 244It is an optimized wrapper for 245.Fn m_prepend 246that can make use of possible empty space before data 247.Pq "e.g. left after trimming of a link-layer header" . 248The new chain pointer or 249.Dv NULL 250is in 251.Fa mbuf 252after the call. 253.El 254.Pp 255The functions are: 256.Bl -ohang -offset indent 257.It Fn m_get how type 258A function version of 259.Fn MGET . 260.It Fn m_gethdr how type 261A function version of 262.Fn MGETHDR . 263.It Fn m_getclr how type 264.Fn MGET how type 265first, 266.Fn bzero 267the internal data buffer then. 268.El 269.Pp 270The functions below operate on mbuf chains. 271.Bl -ohang -offset indent 272.It Fn m_freem mbuf 273Free an entire mbuf chain, including any external 274storage. 275.\" 276.It Fn m_adj mbuf len 277Trim 278.Fa len 279bytes from the head of a mbuf chain if 280.Fa len 281is positive, from the tail otherwise. 282.\" 283.It Fn m_prepend mbuf len how 284Allocate a new mbuf and prepend it to the chain, handle 285.Dv M_PKTHDR 286properly. 287.Sy Note : 288It doesn't allocate any clusters, so 289.Fa len 290must be less than 291.Dv MLEN 292or 293.Dv MHLEN , 294depending on the 295.Dv M_PKTHDR flag setting. 296.\" 297.It Fn m_pullup mbuf len 298Arrange that the first 299.Fa len 300bytes of a mbuf chain are contiguous and lay in the data area of 301.Fa mbuf , 302so they are accessible with 303.Fn mtod mbuf type . 304Return the new chain on success, 305.Dv NULL 306on failure 307.Pq the chain is freed in this case . 308.Sy Note : 309It doesn't allocate any clusters, so 310.Fa len 311must be less than 312.Dv MHLEN . 313.\" 314.It Fn m_copym mbuf offset len how 315Make a copy of an mbuf chain starting 316.Fa offset 317bytes from the beginning, continuing for 318.Fa len 319bytes. If 320.Fa len 321is 322.Dv M_COPYALL , 323copy to the end of the mbuf chain. 324.Sy Note : 325The copy is read-only, because clusters are not 326copied, only their reference counts are incremented. 327.\" 328.It Fn m_copypacket mbuf how 329Copy an entire packet including header, which must be present. 330This is an optimized version of the common case 331.Fn m_copym mbuf 0 M_COPYALL how . 332.Sy Note : 333the copy is read-only, because clusters are not 334copied, only their reference counts are incremented. 335.\" 336.It Fn m_dup mbuf how 337Copy a packet header mbuf chain into a completely new chain, including 338copying any mbuf clusters. Use this instead of 339.Fn m_copypacket 340when you need a writable copy of an mbuf chain. 341.\" 342.It Fn m_copydata mbuf offset len buf 343Copy data from a mbuf chain starting 344.Fa off 345bytes from the beginning, continuing for 346.Fa len 347bytes, into the indicated buffer 348.Fa buf . 349.\" 350.It Fn m_copyback mbuf offset len buf 351Copy 352.Fa len 353bytes from the buffer 354.Fa buf 355back into the indicated mbuf chain, 356starting at 357.Fa offset 358bytes from the beginning of the chain, extending the mbuf chain if necessary. 359.Sy Note : 360It doesn't allocate any clusters, just adds mbufs to the chain. It's safe 361to set 362.Fa offset 363beyond the current chain end: zeroed mbufs will be allocated to fill the 364space. 365.\" 366.It Fn m_devget buf len offset ifp copy 367Copy data from a device local memory pointed to by 368.Fa buf 369to a mbuf chain. The copy is done using a specified copy routine 370.Fa copy , 371or 372.Fn bcopy 373if 374.Fa copy 375is 376.Dv NULL . 377.\" 378.It Fn m_cat m n 379Concatenate 380.Fa n 381to 382.Fa m . 383Both chains must be of the same type. 384.Fa N 385is still valid after the function returned. 386.Sy Note : 387It does not handle 388.Dv M_PKTHDR 389and friends. 390.\" 391.It Fn m_split mbuf len how 392Partition an mbuf chain in two pieces, returning the tail: 393all but the first 394.Fa len 395bytes. In case of failure, it returns 396.Dv NULL 397and attempts to restore the chain to its original state. 398.Sh RETURN VALUES 399See above. 400.Sh HISTORY 401.\" Please correct me if I'm wrong 402Mbufs appeared in an early version of BSD. They were used 403to keep various dynamic structures, such as routing table 404entries, interface addresses, protocol control blocks etc 405besides network packets. 406.Sh AUTHORS 407This man page was written by Yar Tikhiy. 408