1.\" $NetBSD: mbuf.9,v 1.22 2002/05/12 15:48: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_pulldown , 54.Nm m_pullup , 55.Nm m_split , 56.Nm m_adj , 57.Nm m_free , 58.Nm m_freem , 59.Nm mtod , 60.Nm mtocl , 61.Nm cltom , 62.Nm MGET , 63.Nm MGETHDR , 64.Nm MEXTMALLOC , 65.Nm MEXTADD , 66.Nm MCLGET , 67.Nm M_COPY_PKTHDR , 68.Nm M_ALIGN , 69.Nm MH_ALIGN , 70.Nm M_LEADINGSPACE , 71.Nm M_TRAILINGSPACE , 72.Nm M_PREPEND , 73.Nm MCHTYPE , 74.Nm MEXTREMOVE , 75.Nm MFREE , 76.Nd "functions and macros for managing memory used by networking code" 77.Sh SYNOPSIS 78.Fd #include \*[Lt]sys/mbuf.h\*[Gt] 79.Ft struct mbuf * 80.Fn m_get "int nowait" "int type" 81.Ft struct mbuf * 82.Fn m_getclr "int nowait" "int type" 83.Ft struct mbuf * 84.Fn m_gethdr "int nowait" "int type" 85.Ft struct mbuf * 86.Fn m_devget "char *buf" "int totlen" "int off0" "struct ifnet *ifp" "void (*copy)(const void *, void *, size_t)" 87.Ft struct mbuf * 88.Fn m_copym "struct mbuf *m" "int off0" "int len" "int wait" 89.Ft struct mbuf * 90.Fn m_copypacket "struct mbuf *m" "int how" 91.Ft void 92.Fn m_copydata "struct mbuf *m" "int off" "int len" "caddr_t cp" 93.Ft void 94.Fn m_copyback "struct mbuf *m0" "int off" "int len" "caddr_t cp" 95.Ft void 96.Fn m_cat "struct mbuf *m" "struct mbuf *n" 97.Ft struct mbuf * 98.Fn m_dup "struct mbuf *m" "int off0" "int len" "int wait" 99.Ft struct mbuf * 100.Fn m_prepend "struct mbuf *m" "int len" "int how" 101.Ft struct mbuf * 102.Fn m_pulldown "struct mbuf *m" "int off" "int len" "int *offp" 103.Ft struct mbuf * 104.Fn m_pullup "struct mbuf *n" "int len" 105.Ft struct mbuf * 106.Fn m_split "struct mbuf *m0" "int len0" "int wait" 107.Ft void 108.Fn m_adj "struct mbuf *mp" "int req_len" 109.Ft struct mbuf * 110.Fn m_free "struct mbuf *m" 111.Ft void 112.Fn m_freem "struct mbuf *m" 113.Ft datatype 114.Fn mtod "struct mbuf *m" "datatype" 115.Ft u_long 116.Fn mtocl "void *datapointer" 117.Ft caddr_t 118.Fn cltom "u_long clusternum" 119.Ft void 120.Fn MGET "struct mbuf *m" "int how" "int type" 121.Ft void 122.Fn MGETHDR "struct mbuf *m" "int how" "int type" 123.Ft void 124.Fn MEXTMALLOC "struct mbuf *m" "int len" "int how" 125.Ft void 126.Fn MEXTADD "struct mbuf *m" "caddr_t buf" "int size" "int type" "void (*free)(caddr_t, u_int, void *)" "void *arg" 127.Ft void 128.Fn MCLGET "struct mbuf *m" "int how" 129.Ft void 130.Fn M_COPY_PKTHDR "struct mbuf *to" "struct mbuf *from" 131.Ft void 132.Fn M_ALIGN "struct mbuf *m" "int len" 133.Ft void 134.Fn MH_ALIGN "struct mbuf *m" "int len" 135.Ft int 136.Fn M_LEADINGSPACE "struct mbuf *m" 137.Ft int 138.Fn M_TRAILINGSPACE "struct mbuf *m" 139.Ft void 140.Fn M_PREPEND "struct mbuf *m" "int plen" "int how" 141.Ft void 142.Fn MCHTYPE "struct mbuf *m" "int type" 143.Ft void 144.Fn MEXTREMOVE "struct mbuf *m" 145.Ft void 146.Fn MFREE "struct mbuf *m" "struct mbuf *n" 147.Sh DESCRIPTION 148The 149.Nm 150functions and macros provide an easy and consistent way to handle 151a networking stack's memory management needs. 152An 153.Nm 154consists of a header and a data area. 155It is of a fixed size, 156.Dv MSIZE 157.Pq defined in Aq Pa machine/param.h , 158which includes overhead. 159The header contains a pointer to the next 160.Nm 161in the 162.Sq "mbuf chain" , 163a pointer to the next 164.Sq "mbuf chain" , 165a pointer to the data area, the amount of data in this mbuf, its type 166and a 167.Dv flags 168field. 169.Pp 170The 171.Dv type 172variable can signify: 173.Bl -tag -compact -offset indent -width "XXXXXXXXXXX" 174.It Dv MT_FREE 175the mbuf should be on the ``free'' list 176.It Dv MT_DATA 177data was dynamically allocated 178.It Dv MT_HEADER 179data is a packet header 180.It Dv MT_SONAME 181data is a socket name 182.It Dv MT_SOOPTS 183data is socket options 184.It Dv MT_FTABLE 185data is the fragment reassembly header 186.It Dv MT_CONTROL 187mbuf contains ancillary \&(protocol control\&) data 188.It Dv MT_OOBDATA 189mbuf contains out-of-band data. 190.El 191.Pp 192The 193.Dv flags 194variable contains information describing the 195.Nm "" , 196notably: 197.Bl -tag -compact -offset indent -width "XXXXXXXXXXX" 198.It Dv M_EXT 199has external storage 200.It Dv M_PKTHDR 201is start of record 202.It Dv M_EOR 203is end of record 204.It Dv M_CLUSTER 205external storage is a cluster. 206.El 207.Pp 208If an 209.Nm 210designates the start of a record 211.Pq Dv M_PKTHDR , 212its 213.Dv flags 214field may contain additional information describing the content of 215the record: 216.Bl -tag -compact -offset indent -width "XXXXXXXXXXX" 217.It Dv M_BCAST 218sent/received as link-level broadcast 219.It Dv M_MCAST 220sent/received as link-level multicast 221.It Dv M_LINK0 , 222.It Dv M_LINK1 , 223.It Dv M_LINK2 224three link-level specific flags. 225.El 226.Pp 227An 228.Nm 229may add a single 230.Sq "mbuf cluster" 231of 232.Dv MCLBYTES 233bytes 234.Pq also defined in Aq Pa machine/param.h , 235which has no additional overhead 236and is used instead of the internal data area; this is done when at least 237.Dv MINCLSIZE 238bytes of data must be stored. 239.Pp 240When the 241.Dv M_EXT 242flag is raised for an mbuf, 243the external storage area could be shared among multiple mbufs. 244Be careful when you attempt to overwrite the data content of the mbuf. 245.Bl -tag -width compact 246.It Fn m_get "int nowait" "int type" 247Allocates an mbuf and initializes it to contain internal data. 248The 249.Fa nowait 250parameter is a choice of 251.Dv M_WAIT / M_DONTWAIT 252from caller. 253.Dv M_WAIT 254means the call cannot fail, but may take forever. 255The 256.Fa type 257parameter is an mbuf type. 258.It Fn m_getclr "int nowait" "int type" 259Allocates an mbuf and initializes it to contain internal data, then 260zeros the data area. 261The 262.Fa nowait 263parameter is a choice of 264.Dv M_WAIT / M_DONTWAIT 265from caller. 266The 267.Fa type 268parameter is an mbuf type. 269.It Fn m_gethdr "int nowait" "int type" 270Allocates an mbuf and initializes it to contain a packet header and internal 271data. 272The 273.Fa nowait 274parameter is a choice of 275.Dv M_WAIT / M_DONTWAIT 276from caller. 277The 278.Fa type 279parameter is an mbuf type. 280.It Fn m_devget "char *buf" "int totlen" "int off0" "struct ifnet *ifp" "void (*copy)(const void *, void *, size_t)" 281Copies 282.Fa len 283bytes from device local memory into mbufs using copy routine 284.Fa copy . 285If parameter 286.Fa off 287is non-zero, the packet is supposed to be trailer-encapsulated and 288.Fa off 289bytes plus the type and length fields will be skipped before copying. 290Returns the top of the mbuf chain it created. 291.It Fn m_copym "struct mbuf *m" "int off0" "int len" "int wait" 292Creates a copy of an mbuf chain starting 293.Fa off0 294bytes from the beginning, continuing for 295.Fa len 296bytes. If the 297.Fa len 298requested is 299.Dv M_COPYALL , 300the complete mbuf chain will be copied. 301The 302.Fa wait 303parameter is a choice of 304.Dv M_WAIT / M_DONTWAIT 305from caller. 306.It Fn m_copypacket "struct mbuf *m" "int how" 307Copies an entire packet, including header (which must be present). 308This function is an optimization of the common case 309.Li m_copym(m, 0, Dv M_COPYALL, Fa how ) . 310.It Fn m_copydata "struct mbuf *m" "int off" "int len" "caddr_t cp" 311Copies 312.Fa len 313bytes data from mbuf chain 314.Fa m 315into the buffer 316.Fa cp , 317starting 318.Fa off 319bytes from the beginning. 320.It Fn m_copyback "struct mbuf *m0" "int off" "int len" "caddr_t cp" 321Copies 322.Fa len 323bytes data from buffer 324.Fa cp 325back into the mbuf chain 326.Fa m0 , 327starting 328.Fa off 329bytes from the beginning, extending the mbuf chain if necessary. 330.It Fn m_cat "struct mbuf *m" "struct mbuf *n" 331Concatenates mbuf chain 332.Fa n 333to 334.Fa m . 335Both chains must be of the same type; packet headers will 336.Em not 337be updated if present. 338.It Fn m_dup "struct mbuf *m" "int off0" "int len" "int wait" 339Similarly to 340.Fn m_copym , 341the function creates a copy of an mbuf chain starting 342.Fa off0 343bytes from the beginning, continuing for 344.Fa len 345bytes. 346While 347.Fn m_copym 348tries to share external storage for mbufs with 349.Dv M_EXT 350flag, 351.Fn m_dup 352will deep-copy the whole data content into new mbuf chain 353and avoids shared external storage. 354.It Fn m_prepend "struct mbuf *m" "int len" "int how" 355Lesser-used path for 356.Fn M_PREPEND : 357allocates new mbuf 358.Fa m 359of size 360.Fa len 361to prepend to the chain, copying junk along. 362The 363.Fa how 364parameter is a choice of 365.Dv M_WAIT / M_DONTWAIT 366from caller. 367.It Fn m_pulldown "struct mbuf *m" "int off" "int len" "int *offp" 368Rearranges an mbuf chain so that 369.Fa len 370bytes from offset 371.Fa off 372are contiguous and in the data area of an mbuf. 373The return value points to an mbuf in the middle of the mbuf chain 374.Fa m . 375If we call the return value 376.Fa n , 377the contiguous data region is available at 378.Li "mtod(n, caddr_t) + *offp" , 379or 380.Li "mtod(n, caddr_t)" 381if 382.Fa offp 383is 384.Dv NULL . 385The top of the mbuf chain 386.Fa m , 387and mbufs up to 388.Fa off , 389will not be modified. 390On successful return, it is guaranteed that the mbuf pointed to by 391.Fa n 392does not have a shared external storage, 393therefore it is safe to update the contiguous region. 394Returns 395.Dv NULL 396and frees the mbuf chain on failure. 397.Fa len 398must be smaller or equal than 399.Dv MCLBYTES . 400.It Fn m_pullup "struct mbuf *m" "int len" 401Rearranges an mbuf chain so that 402.Fa len 403bytes are contiguous 404and in the data area of an mbuf (so that 405.Fn mtod 406will work for a structure of size 407.Fa len ) . 408Returns the resulting 409mbuf chain on success, frees it and returns 410.Dv NULL 411on failure. 412If there is room, it will add up to 413.Dv max_protohdr 414- 415.Fa len 416extra bytes to the 417contiguous region to possibly avoid being called again. 418.Fa len 419must be smaller or equal than 420.Dv MHLEN . 421.It Fn m_split "struct mbuf *m0" "int len0" "int wait" 422Partitions an mbuf chain in two pieces, returning the tail, 423which is all but the first 424.Fa len0 425bytes. In case of failure, it returns 426.Dv NULL 427and attempts to 428restore the chain to its original state. 429.It Fn m_adj "struct mbuf *mp" "int req_len" 430Shaves off 431.Fa req_len 432bytes from head or tail of the (valid) data area. 433If 434.Fa req_len 435is greater than zero, front bytes are being shaved off, if it's smaller, 436from the back (and if it is zero, the mbuf will stay bearded). 437This function does not move data in any way, but is used to manipulate the 438data area pointer and data length variable of the mbuf in a non-clobbering 439way. 440.It Fn m_free "struct mbuf *m" 441Frees mbuf 442.Fa m . 443.It Fn m_freem "struct mbuf *m" 444Frees the mbuf chain beginning with 445.Fa m . 446This function contains the elementary sanity check for a 447.Dv NULL 448pointer. 449.It Fn mtod "struct mbuf *m" "datatype" 450Returns a pointer to the data contained in the specified mbuf 451.Fa m , 452type-casted to the specified data type 453.Fa datatype . 454Implemented as a macro. 455.It Fn mtocl "void *datapointer" 456Takes a 457.Fa datapointer 458within an mbuf cluster and returns the cluster index number of the mbuf 459owning the data. 460Avoid this; it may be deprecated in the future. 461Implemented as a macro. 462.It Fn cltom "u_long clusternum" 463Takes an mbuf cluster index number 464.Fa clusternum 465and returns a pointer to the beginning of the cluster. 466Avoid this; it may be deprecated in the future. 467Implemented as a macro. 468.It Fn MGET "struct mbuf *m" "int how" "int type" 469Allocates mbuf 470.Fa m 471and initializes it to contain internal data. 472See 473.Fn m_get . 474Implemented as a macro. 475.It Fn MGETHDR "struct mbuf *m" "int how" "int type" 476Allocates mbuf 477.Fa m 478and initializes it to contain a packet header. 479See 480.Fn m_gethdr . 481Implemented as a macro. 482.It Fn MEXTMALLOC "struct mbuf *m" "int len" "int how" 483Allocates external storage of size 484.Fa len 485for mbuf 486.Fa m . 487The 488.Fa how 489parameter is a choice of 490.Dv M_WAIT / M_DONTWAIT 491from caller. 492The flag 493.Dv M_EXT 494is set upon success. 495Implemented as a macro. 496.It Fn MEXTADD "struct mbuf *m" "caddr_t buf" "int size" "int type" "void (*free)(caddr_t, u_int, void *)" "void *arg" 497Adds pre-allocated external storage 498.Fa buf 499to a normal mbuf 500.Fa m ; 501the parameters 502.Fa size , 503.Fa type , 504.Fa free 505and 506.Fa arg 507describe the external storage. 508.Fa size 509is the size of the storage, 510.Fa type 511describes its 512.Xr malloc 9 513type, 514.Fa free 515is a free routine (if not the usual one), and 516.Fa arg 517is a possible argument to the free routine. 518The flag 519.Dv M_EXT 520is set upon success. 521Implemented as a macro. 522.It Fn MCLGET "struct mbuf *m" "int how" 523Allocates and adds an mbuf cluster to a normal mbuf 524.Fa m . 525The 526.Fa how 527parameter is a choice of 528.Dv M_WAIT / M_DONTWAIT 529from caller. 530The flag 531.Dv M_EXT 532is set upon success. 533Implemented as a macro. 534.It Fn M_COPY_PKTHDR "struct mbuf *to" "struct mbuf *from" 535Copies the mbuf pkthdr from mbuf 536.Fa from 537to mbuf 538.Fa to . 539.Fa from 540must have the type flag 541.Dv M_PKTHDR 542set, and 543.Fa to 544must be empty. 545Implemented as a macro. 546.It Fn M_ALIGN "struct mbuf *m" "int len" 547Sets the data pointer of a newly allocated mbuf 548.Fa m 549to 550.Fa len 551bytes from the end of the mbuf data area, so that 552.Fa len 553bytes of data written to the mbuf 554.Fa m , 555starting at the data pointer, will be aligned to the end of the data area. 556Implemented as a macro. 557.It Fn MH_ALIGN "struct mbuf *m" "int len" 558Sets the data pointer of a newly allocated packetheader mbuf 559.Fa m 560to 561.Fa len 562bytes from the end of the mbuf data area, so that 563.Fa len 564bytes of data written to the mbuf 565.Fa m , 566starting at the data pointer, will be aligned to the end of the data area. 567Implemented as a macro. 568.It Fn M_LEADINGSPACE "struct mbuf *m" 569Returns the amount of space available before the current start of valid 570data in mbuf 571.Fa m . 572Returns 0 if the mbuf data part is shared across multiple mbufs 573.Pq i.e. not writable . 574Implemented as a macro. 575.It Fn M_TRAILINGSPACE "struct mbuf *m" 576Returns the amount of space available after the current end of valid 577data in mbuf 578.Fa m . 579Returns 0 if the mbuf data part is shared across multiple mbufs 580.Pq i.e. not writable . 581Implemented as a macro. 582.It Fn M_PREPEND "struct mbuf *m" "int plen" "int how" 583Prepends space of size 584.Fa plen 585to mbuf 586.Fa m . 587If a new mbuf must be allocated, 588.Fa how 589specifies whether to wait. 590If 591.Fa how 592is 593.Dv M_DONTWAIT 594and allocation fails, the original mbuf chain is freed and 595.Fa m 596is set to 597.Dv NULL . 598Implemented as a macro. 599.It Fn MCHTYPE "struct mbuf *m" "int type" 600Change mbuf 601.Fa m 602to new type 603.Fa type . 604Implemented as a macro. 605.It Fn MEXTREMOVE "struct mbuf *m" 606Removes external storage from mbuf 607.Fa m . 608The flag 609.Dv M_EXT 610is removed. 611Implemented as a macro. 612.It Fn MFREE "struct mbuf *m" "struct mbuf *n" 613Frees a single mbuf 614.Fa m 615and places the successor, if any, in mbuf 616.Fa n . 617Implemented as a macro. 618.El 619.Sh FILES 620The 621.Nm 622management functions are implemented within the file 623.Pa sys/kern/uipc_mbuf.c . 624Function prototypes, and the functions implemented as macros 625are located in 626.Pa sys/sys/mbuf.h . 627Both pathnames are relative to the root of the 628.Nx 629source tree, 630.Pa /usr/src . 631.Sh SEE ALSO 632.Pa /usr/share/doc/smm/18.net , 633.Xr netstat 1 , 634.Xr malloc 9 635.Rs 636.%A Jun-ichiro Hagino 637.%T "Mbuf issues in 4.4BSD IPv6/IPsec support (experiences from KAME IPv6/IPsec implemntation)" 638.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference" 639.%D June 2000 640.Re 641.Sh AUTHORS 642The original mbuf data structures were designed by Rob Gurwitz 643when he did the initial TCP/IP implementation at BBN. 644.br 645Further extensions and enhancements were made by Bill Joy, Sam Leffler, 646and Mike Karels at CSRG. 647.br 648Current implementation of external storage by Matt Thomas 649.br 650\*[Lt]matt@3am-software.com\*[Gt] and Jason R. Thorpe \*[Lt]thorpej@NetBSD.ORG\*[Gt]. 651