1.\" $NetBSD: mbuf.9,v 1.12 2001/04/09 17:14:38 wiz Exp $ 2.\" 3.\" Copyright (c) 1997 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This documentation is derived from text contributed to The NetBSD Foundation 7.\" by S.P.Zeidler (aka stargazer). 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd October 3, 1997 38.Dt MBUF 9 39.Os 40.Sh NAME 41.Nm mbuf , 42.Nm m_get , 43.Nm m_getclr , 44.Nm m_gethdr , 45.Nm m_devget , 46.Nm m_copym , 47.Nm m_copypacket , 48.Nm m_copydata , 49.Nm m_copyback , 50.Nm m_cat , 51.Nm m_dup , 52.Nm m_prepend , 53.Nm m_pullup , 54.Nm m_split , 55.Nm m_adj , 56.Nm m_free , 57.Nm m_freem , 58.Nm mtod , 59.Nm mtocl , 60.Nm cltom , 61.Nm MGET , 62.Nm MGETHDR , 63.Nm MEXTMALLOC , 64.Nm MEXTADD , 65.Nm MCLGET , 66.Nm M_COPY_PKTHDR , 67.Nm M_ALIGN , 68.Nm MH_ALIGN , 69.Nm M_LEADINGSPACE , 70.Nm M_TRAILINGSPACE , 71.Nm M_PREPEND , 72.Nm MCHTYPE , 73.Nm MEXTREMOVE , 74.Nm MFREE , 75.Nd "functions and macros for managing memory used by networking code" 76.Sh SYNOPSIS 77.Fd #include <sys/mbuf.h> 78.Ft struct mbuf * 79.Fn m_get "int nowait" "int type" 80.Ft struct mbuf * 81.Fn m_getclr "int nowait" "int type" 82.Ft struct mbuf * 83.Fn m_gethdr "int nowait" "int type" 84.Ft struct mbuf * 85.Fn m_devget "char *buf" "int totlen" "int off0" "struct ifnet *ifp" "void (*copy) __P((const void *, void *, size_t))" 86.Ft struct mbuf * 87.Fn m_copym "struct mbuf *m" "int off0" "int len" "int wait" 88.Ft struct mbuf * 89.Fn m_copypacket "struct mbuf *m" "int how" 90.Ft void 91.Fn m_copydata "struct mbuf *m" "int off" "int len" "caddr_t cp" 92.Ft void 93.Fn m_copyback "struct mbuf *m0" "int off" "int len" "caddr_t cp" 94.Ft void 95.Fn m_cat "struct mbuf *m" "struct mbuf *n" 96.Ft struct mbuf * 97.Fn m_dup "struct mbuf *m" "int off0" "int len" "int wait" 98.Ft struct mbuf * 99.Fn m_prepend "struct mbuf *m" "int len" "int how" 100.Ft struct mbuf * 101.Fn m_pullup "struct mbuf *n" "int len" 102.Ft struct mbuf * 103.Fn m_split "struct mbuf *m0" "int len0" "int wait" 104.Ft void 105.Fn m_adj "struct mbuf *mp" "int req_len" 106.Ft struct mbuf * 107.Fn m_free "struct mbuf *m" 108.Ft void 109.Fn m_freem "struct mbuf *m" 110.Ft int 111.Fn mtod "struct mbuf *m" "datatype" 112.Ft u_long 113.Fn mtocl "void *datapointer" 114.Ft caddr_t 115.Fn cltom "u_long clusternum" 116.Ft void 117.Fn MGET "struct mbuf *m" "int how" "int type" 118.Ft void 119.Fn MGETHDR "struct mbuf *m" "int how" "int type" 120.Ft void 121.Fn MEXTMALLOC "struct mbuf *m" "int len" "int how" 122.Ft void 123.Fn MEXTADD "struct mbuf *m" "caddr_t buf" "int type" "void (*free) __P((caddr_t, u_int, void *))" "void *arg" 124.Ft void 125.Fn MCLGET "struct mbuf *m" "int how" 126.Ft void 127.Fn M_COPY_PKTHDR "struct mbuf *to" "struct mbuf *from" 128.Ft void 129.Fn M_ALIGN "struct mbuf *m" "int len" 130.Ft void 131.Fn MH_ALIGN "struct mbuf *m" "int len" 132.Ft int 133.Fn M_LEADINGSPACE "struct mbuf *m" 134.Ft int 135.Fn M_TRAILINGSPACE "struct mbuf *m" 136.Ft void 137.Fn M_PREPEND "struct mbuf *m" "int plen" "int how" 138.Ft void 139.Fn MCHTYPE "struct mbuf *m" "int type" 140.Ft void 141.Fn MEXTREMOVE "struct mbuf *m" 142.Ft void 143.Fn MFREE "struct mbuf *m" "struct mbuf *n" 144.Sh DESCRIPTION 145The 146.Nm 147functions and macros provide an easy and consistent way to handle 148a networking stack's memory management needs. 149An 150.Nm 151consists of a header and a data area. 152It is of a fixed size, 153.Dv MSIZE 154.Pq defined in Aq Pa machine/param.h , 155which includes overhead. 156The header contains a pointer to the next 157.Nm 158in the 159.Sq "mbuf chain" , 160a pointer to the next 161.Sq "mbuf chain" , 162a pointer to the data area, the amount of data in this mbuf, its type 163and a 164.Dv flags 165field. 166.Pp 167The 168.Dv type 169variable can signify: 170.Bl -tag -compact -offset indent -width "XXXXXXXXXXX" 171.It Dv MT_FREE 172the mbuf should be on the ``free'' list 173.It Dv MT_DATA 174data was dynamically allocated 175.It Dv MT_HEADER 176data is a packet header 177.It Dv MT_SONAME 178data is a socket name 179.It Dv MT_SOOPTS 180data is socket options 181.It Dv MT_FTABLE 182data is the fragment reassembly header 183.It Dv MT_CONTROL 184mbuf contains ancillary \&(protocol control\&) data 185.It Dv MT_OOBDATA 186mbuf contains out-of-band data. 187.El 188.Pp 189The 190.Dv flags 191variable contains information describing the 192.Nm "" , 193notably: 194.Bl -tag -compact -offset indent -width "XXXXXXXXXXX" 195.It Dv M_EXT 196has external storage 197.It Dv M_PKTHDR 198is start of record 199.It Dv M_EOR 200is end of record 201.It Dv M_CLUSTER 202external storage is a cluster. 203.El 204.Pp 205If an 206.Nm 207designates the start of a record 208.Pq Dv M_PKTHDR , 209its 210.Dv flags 211field may contain additional information describing the content of 212the record: 213.Bl -tag -compact -offset indent -width "XXXXXXXXXXX" 214.It Dv M_BCAST 215sent/received as link-level broadcast 216.It Dv M_MCAST 217sent/received as link-level multicast 218.It Dv M_LINK0 , 219.It Dv M_LINK1 , 220.It Dv M_LINK2 221three link-level specific flags. 222.El 223.Pp 224An 225.Nm 226may add a single 227.Sq "mbuf cluster" 228of 229.Dv MCLBYTES 230bytes 231.Pq also defined in Aq Pa machine/param.h , 232which has no additional overhead 233and is used instead of the internal data area; this is done when at least 234.Dv MINCLSIZE 235bytes of data must be stored. 236.Pp 237When the 238.Dv M_EXT 239flag is raised for an mbuf, 240the external storage area could be shared among multiple mbufs. 241Be careful when you attempt to overwrite the data content of the mbuf. 242.Bl -tag -width compact 243.It Fn m_get "int nowait" "int type" 244Allocates an mbuf and initializes it to contain internal data. 245The 246.Fa nowait 247parameter is a choice of 248.Dv M_WAIT / M_DONTWAIT 249from caller. 250.Dv M_WAIT 251means the call cannot fail, but may take forever. 252The 253.Fa type 254parameter is an mbuf type. 255.It Fn m_getclr "int nowait" "int type" 256Allocates an mbuf and initializes it to contain internal data, then 257zeros the data area. 258The 259.Fa nowait 260parameter is a choice of 261.Dv M_WAIT / M_DONTWAIT 262from caller. 263The 264.Fa type 265parameter is an mbuf type. 266.It Fn m_gethdr "int nowait" "int type" 267Allocates an mbuf and initializes it to contain a packet header and internal 268data. 269The 270.Fa nowait 271parameter is a choice of 272.Dv M_WAIT / M_DONTWAIT 273from caller. 274The 275.Fa type 276parameter is an mbuf type. 277.It Fn m_devget "char *buf" "int totlen" "int off0" "struct ifnet *ifp" "void (*copy) __P((const void *, void *, size_t))" 278Copies 279.Fa len 280bytes from device local memory into mbufs using copy routine 281.Fa copy . 282If parameter 283.Fa off 284is non-zero, the packet is supposed to be trailer-encapsulated and 285.Fa off 286bytes plus the type and length fields will be skipped before copying. 287Returns the top of the mbuf chain it created. 288.It Fn m_copym "struct mbuf *m" "int off0" "int len" "int wait" 289Creates a copy of an mbuf chain starting 290.Fa off0 291bytes from the beginning, continuing for 292.Fa len 293bytes. If the 294.Fa len 295requested is 296.Dv M_COPYALL , 297the complete mbuf chain will be copied. 298The 299.Fa wait 300parameter is a choice of 301.Dv M_WAIT / M_DONTWAIT 302from caller. 303.It Fn m_copypacket "struct mbuf *m" "int how" 304Copies an entire packet, including header (which must be present). 305This function is an optimization of the common case 306.Li m_copym(m, 0, Dv M_COPYALL, Fa how ) . 307.It Fn m_copydata "struct mbuf *m" "int off" "int len" "caddr_t cp" 308Copies 309.Fa len 310bytes data from mbuf chain 311.Fa m 312into the buffer 313.Fa cp , 314starting 315.Fa off 316bytes from the beginning. 317.It Fn m_copyback "struct mbuf *m0" "int off" "int len" "caddr_t cp" 318Copies 319.Fa len 320bytes data from buffer 321.Fa cp 322back into the mbuf chain 323.Fa m0 , 324starting 325.Fa off 326bytes from the beginning, extending the mbuf chain if necessary. 327.It Fn m_cat "struct mbuf *m" "struct mbuf *n" 328Concatenates mbuf chain 329.Fa n 330to 331.Fa m . 332Both chains must be of the same type; packet headers will 333.Em not 334be updated if present. 335.It Fn m_dup "struct mbuf *m" "int off0" "int len" "int wait" 336Similarly to 337.Fn m_copym , 338the function creates a copy of an mbuf chain starting 339.Fa off0 340bytes from the beginning, continuing for 341.Fa len 342bytes. 343While 344.Fn m_copym 345tries to share external storage for mbufs with 346.Dv M_EXT 347flag, 348.Fn m_dup 349will deep-copy the whole data content into new mbuf chain 350and avoids shared external storage. 351.It Fn m_prepend "struct mbuf *m" "int len" "int how" 352Lesser-used path for 353.Fn M_PREPEND : 354allocates new mbuf 355.Fa m 356of size 357.Fa len 358to prepend to the chain, copying junk along. 359The 360.Fa how 361parameter is a choice of 362.Dv M_WAIT / M_DONTWAIT 363from caller. 364.It Fn m_pullup "struct mbuf *m" "int len" 365Rearranges an mbuf chain so that 366.Fa len 367bytes are contiguous 368and in the data area of an mbuf (so that 369.Fn mtod 370will work for a structure of size 371.Fa len ) . 372Returns the resulting 373mbuf chain on success, frees it and returns 374.Dv NULL 375on failure. 376If there is room, it will add up to 377.Dv max_protohdr 378- 379.Fa len 380extra bytes to the 381contiguous region to possibly avoid being called again. 382.It Fn m_split "struct mbuf *m0" "int len0" "int wait" 383Partitions an mbuf chain in two pieces, returning the tail, 384which is all but the first 385.Fa len0 386bytes. In case of failure, it returns 387.Dv NULL 388and attempts to 389restore the chain to its original state. 390.It Fn m_adj "struct mbuf *mp" "int req_len" 391Shaves off 392.Fa req_len 393bytes from head or tail of the (valid) data area. 394If 395.Fa req_len 396is greater than zero, front bytes are being shaved off, if it's smaller, 397from the back (and if it is zero, the mbuf will stay bearded). 398This function does not move data in any way, but is used to manipulate the 399data area pointer and data length variable of the mbuf in a non-clobbering 400way. 401.It Fn m_free "struct mbuf *m" 402Frees mbuf 403.Fa m . 404.It Fn m_freem "struct mbuf *m" 405Frees the mbuf chain beginning with 406.Fa m . 407This function contains the elementary sanity check for a 408.Dv NULL 409pointer. 410.It Fn mtod "struct mbuf *m" "datatype" 411Returns a pointer to the data contained in the specified mbuf 412.Fa m , 413type-casted to the specified data type 414.Fa datatype . 415Implemented as a macro. 416.It Fn mtocl "void *datapointer" 417Takes a 418.Fa datapointer 419within an mbuf cluster and returns the cluster index number of the mbuf 420owning the data. 421Avoid this; it may be deprecated in the future. 422Implemented as a macro. 423.It Fn cltom "u_long clusternum" 424Takes an mbuf cluster index number 425.Fa clusternum 426and returns a pointer to the beginning of the cluster. 427Avoid this; it may be deprecated in the future. 428Implemented as a macro. 429.It Fn MGET "struct mbuf *m" "int how" "int type" 430Allocates mbuf 431.Fa m 432and initializes it to contain internal data. 433See 434.Fn m_get . 435Implemented as a macro. 436.It Fn MGETHDR "struct mbuf *m" "int how" "int type" 437Allocates mbuf 438.Fa m 439and initializes it to contain a packet header. 440See 441.Fn m_gethdr . 442Implemented as a macro. 443.It Fn MEXTMALLOC "struct mbuf *m" "int len" "int how" 444Allocates external storage of size 445.Fa len 446for mbuf 447.Fa m . 448The 449.Fa how 450parameter is a choice of 451.Dv M_WAIT / M_DONTWAIT 452from caller. 453The flag 454.Dv M_EXT 455is set upon success. 456Implemented as a macro. 457.It Fn MEXTADD "struct mbuf *m" "caddr_t buf" "int type" "void (*free) __P((caddr_t, u_int, void *))" "void *arg" 458Adds pre-allocated external storage 459.Fa buf 460to a normal mbuf 461.Fa m ; 462the parameters 463.Fa type , 464.Fa free 465and 466.Fa arg 467describe the external storage. 468.Fa type 469describes the 470.Xr malloc 9 471type of the storage, 472.Fa free 473is a free routine (if not the usual one), and 474.Fa arg 475is a possible argument to the free routine. 476The flag 477.Dv M_EXT 478is set upon success. 479Implemented as a macro. 480.It Fn MCLGET "struct mbuf *m" "int how" 481Allocates and adds an mbuf cluster to a normal mbuf 482.Fa m . 483The 484.Fa how 485parameter is a choice of 486.Dv M_WAIT / M_DONTWAIT 487from caller. 488The flag 489.Dv M_EXT 490is set upon success. 491Implemented as a macro. 492.It Fn M_COPY_PKTHDR "struct mbuf *to" "struct mbuf *from" 493Copies the mbuf pkthdr from mbuf 494.Fa from 495to mbuf 496.Fa to . 497.Fa from 498must have the type flag 499.Dv M_PKTHDR 500set, and 501.Fa to 502must be empty. 503Implemented as a macro. 504.It Fn M_ALIGN "struct mbuf *m" "int len" 505Sets the data pointer of a newly allocated mbuf 506.Fa m 507to 508.Fa len 509bytes from the end of the mbuf data area, so that 510.Fa len 511bytes of data written to the mbuf 512.Fa m , 513starting at the data pointer, will be aligned to the end of the data area. 514Implemented as a macro. 515.It Fn MH_ALIGN "struct mbuf *m" "int len" 516Sets the data pointer of a newly allocated packetheader mbuf 517.Fa m 518to 519.Fa len 520bytes from the end of the mbuf data area, so that 521.Fa len 522bytes of data written to the mbuf 523.Fa m , 524starting at the data pointer, will be aligned to the end of the data area. 525Implemented as a macro. 526.It Fn M_LEADINGSPACE "struct mbuf *m" 527Returns the amount of space available before the current start of valid 528data in mbuf 529.Fa m . 530Implemented as a macro. 531.It Fn M_TRAILINGSPACE "struct mbuf *m" 532Returns the amount of space available after the current end of valid 533data in mbuf 534.Fa m . 535Implemented as a macro. 536.It Fn M_PREPEND "struct mbuf *m" "int plen" "int how" 537Prepends space of size 538.Fa plen 539to mbuf 540.Fa m . 541If a new mbuf must be allocated, 542.Fa how 543specifies whether to wait. 544If 545.Fa how 546is 547.Dv M_DONTWAIT 548and allocation fails, the original mbuf chain is freed and 549.Fa m 550is set to 551.Dv NULL . 552Implemented as a macro. 553.It Fn MCHTYPE "struct mbuf *m" "int type" 554Change mbuf 555.Fa m 556to new type 557.Fa type . 558Implemented as a macro. 559.It Fn MEXTREMOVE "struct mbuf *m" 560Removes external storage from mbuf 561.Fa m . 562The flag 563.Dv M_EXT 564is removed. 565Implemented as a macro. 566.It Fn MFREE "struct mbuf *m" "struct mbuf *n" 567Frees a single mbuf 568.Fa m 569and places the successor, if any, in mbuf 570.Fa n . 571Implemented as a macro. 572.El 573.\" .Sh ERRORS 574.Sh SEE ALSO 575.Pa /usr/share/doc/smm/18.net , 576.Xr netstat 1 , 577.Xr malloc 9 578.Sh AUTHORS 579The original mbuf data structures were designed by Rob Gurwitz 580when he did the initial TCP/IP implementation at BBN. 581.br 582Further extensions and enhancements were made by Bill Joy, Sam Leffler, 583and Mike Karels at CSRG. 584.br 585Current implementation of external storage by Matt Thomas 586.br 587<matt@3am-software.com> and Jason R. Thorpe <thorpej@NetBSD.ORG>. 588.Sh FILES 589The 590.Nm 591management functions are implemented within the file 592.Pa sys/kern/uipc_mbuf.c . 593Function prototypes, and the functions implemented as macros 594are located in 595.Pa sys/sys/mbuf.h . 596Both pathnames are relative to the root of the 597.Nx 598source tree, 599.Pa /usr/src . 600.\" .Sh HISTORY 601