1.\" $NetBSD: mbuf.9,v 1.27 2003/04/16 13:35:30 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.In sys/mbuf.h 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. 297If the 298.Fa len 299requested is 300.Dv M_COPYALL , 301the complete mbuf chain will be copied. 302The 303.Fa wait 304parameter is a choice of 305.Dv M_WAIT / M_DONTWAIT 306from caller. 307.It Fn m_copypacket "struct mbuf *m" "int how" 308Copies an entire packet, including header (which must be present). 309This function is an optimization of the common case 310.Li m_copym(m, 0, Dv M_COPYALL, Fa how ) . 311.It Fn m_copydata "struct mbuf *m" "int off" "int len" "caddr_t cp" 312Copies 313.Fa len 314bytes data from mbuf chain 315.Fa m 316into the buffer 317.Fa cp , 318starting 319.Fa off 320bytes from the beginning. 321.It Fn m_copyback "struct mbuf *m0" "int off" "int len" "caddr_t cp" 322Copies 323.Fa len 324bytes data from buffer 325.Fa cp 326back into the mbuf chain 327.Fa m0 , 328starting 329.Fa off 330bytes from the beginning, extending the mbuf chain if necessary. 331.It Fn m_cat "struct mbuf *m" "struct mbuf *n" 332Concatenates mbuf chain 333.Fa n 334to 335.Fa m . 336Both chains must be of the same type; packet headers will 337.Em not 338be updated if present. 339.It Fn m_dup "struct mbuf *m" "int off0" "int len" "int wait" 340Similarly to 341.Fn m_copym , 342the function creates a copy of an mbuf chain starting 343.Fa off0 344bytes from the beginning, continuing for 345.Fa len 346bytes. 347While 348.Fn m_copym 349tries to share external storage for mbufs with 350.Dv M_EXT 351flag, 352.Fn m_dup 353will deep-copy the whole data content into new mbuf chain 354and avoids shared external storage. 355.It Fn m_prepend "struct mbuf *m" "int len" "int how" 356Lesser-used path for 357.Fn M_PREPEND : 358allocates new mbuf 359.Fa m 360of size 361.Fa len 362to prepend to the chain, copying junk along. 363The 364.Fa how 365parameter is a choice of 366.Dv M_WAIT / M_DONTWAIT 367from caller. 368.It Fn m_pulldown "struct mbuf *m" "int off" "int len" "int *offp" 369Rearranges an mbuf chain so that 370.Fa len 371bytes from offset 372.Fa off 373are contiguous and in the data area of an mbuf. 374The return value points to an mbuf in the middle of the mbuf chain 375.Fa m . 376If we call the return value 377.Fa n , 378the contiguous data region is available at 379.Li "mtod(n, caddr_t) + *offp" , 380or 381.Li "mtod(n, caddr_t)" 382if 383.Fa offp 384is 385.Dv NULL . 386The top of the mbuf chain 387.Fa m , 388and mbufs up to 389.Fa off , 390will not be modified. 391On successful return, it is guaranteed that the mbuf pointed to by 392.Fa n 393does not have a shared external storage, 394therefore it is safe to update the contiguous region. 395Returns 396.Dv NULL 397and frees the mbuf chain on failure. 398.Fa len 399must be smaller or equal than 400.Dv MCLBYTES . 401.It Fn m_pullup "struct mbuf *m" "int len" 402Rearranges an mbuf chain so that 403.Fa len 404bytes are contiguous 405and in the data area of an mbuf (so that 406.Fn mtod 407will work for a structure of size 408.Fa len ) . 409Returns the resulting 410mbuf chain on success, frees it and returns 411.Dv NULL 412on failure. 413If there is room, it will add up to 414.Dv max_protohdr 415- 416.Fa len 417extra bytes to the 418contiguous region to possibly avoid being called again. 419.Fa len 420must be smaller or equal than 421.Dv MHLEN . 422.It Fn m_split "struct mbuf *m0" "int len0" "int wait" 423Partitions an mbuf chain in two pieces, returning the tail, 424which is all but the first 425.Fa len0 426bytes. 427In case of failure, it returns 428.Dv NULL 429and attempts to 430restore the chain to its original state. 431.It Fn m_adj "struct mbuf *mp" "int req_len" 432Shaves off 433.Fa req_len 434bytes from head or tail of the (valid) data area. 435If 436.Fa req_len 437is greater than zero, front bytes are being shaved off, if it's smaller, 438from the back (and if it is zero, the mbuf will stay bearded). 439This function does not move data in any way, but is used to manipulate the 440data area pointer and data length variable of the mbuf in a non-clobbering 441way. 442.It Fn m_free "struct mbuf *m" 443Frees mbuf 444.Fa m . 445.It Fn m_freem "struct mbuf *m" 446Frees the mbuf chain beginning with 447.Fa m . 448This function contains the elementary sanity check for a 449.Dv NULL 450pointer. 451.It Fn mtod "struct mbuf *m" "datatype" 452Returns a pointer to the data contained in the specified mbuf 453.Fa m , 454type-casted to the specified data type 455.Fa datatype . 456Implemented as a macro. 457.It Fn mtocl "void *datapointer" 458Takes a 459.Fa datapointer 460within an mbuf cluster and returns the cluster index number of the mbuf 461owning the data. 462Avoid this; it may be deprecated in the future. 463Implemented as a macro. 464.It Fn cltom "u_long clusternum" 465Takes an mbuf cluster index number 466.Fa clusternum 467and returns a pointer to the beginning of the cluster. 468Avoid this; it may be deprecated in the future. 469Implemented as a macro. 470.It Fn MGET "struct mbuf *m" "int how" "int type" 471Allocates mbuf 472.Fa m 473and initializes it to contain internal data. 474See 475.Fn m_get . 476Implemented as a macro. 477.It Fn MGETHDR "struct mbuf *m" "int how" "int type" 478Allocates mbuf 479.Fa m 480and initializes it to contain a packet header. 481See 482.Fn m_gethdr . 483Implemented as a macro. 484.It Fn MEXTMALLOC "struct mbuf *m" "int len" "int how" 485Allocates external storage of size 486.Fa len 487for mbuf 488.Fa m . 489The 490.Fa how 491parameter is a choice of 492.Dv M_WAIT / M_DONTWAIT 493from caller. 494The flag 495.Dv M_EXT 496is set upon success. 497Implemented as a macro. 498.It Fn MEXTADD "struct mbuf *m" "caddr_t buf" "int size" "int type" "void (*free)(caddr_t, u_int, void *)" "void *arg" 499Adds pre-allocated external storage 500.Fa buf 501to a normal mbuf 502.Fa m ; 503the parameters 504.Fa size , 505.Fa type , 506.Fa free 507and 508.Fa arg 509describe the external storage. 510.Fa size 511is the size of the storage, 512.Fa type 513describes its 514.Xr malloc 9 515type, 516.Fa free 517is a free routine (if not the usual one), and 518.Fa arg 519is a possible argument to the free routine. 520The flag 521.Dv M_EXT 522is set upon success. 523Implemented as a macro. 524.It Fn MCLGET "struct mbuf *m" "int how" 525Allocates and adds an mbuf cluster to a normal mbuf 526.Fa m . 527The 528.Fa how 529parameter is a choice of 530.Dv M_WAIT / M_DONTWAIT 531from caller. 532The flag 533.Dv M_EXT 534is set upon success. 535Implemented as a macro. 536.It Fn M_COPY_PKTHDR "struct mbuf *to" "struct mbuf *from" 537Copies the mbuf pkthdr from mbuf 538.Fa from 539to mbuf 540.Fa to . 541.Fa from 542must have the type flag 543.Dv M_PKTHDR 544set, and 545.Fa to 546must be empty. 547Implemented as a macro. 548.It Fn M_ALIGN "struct mbuf *m" "int len" 549Sets the data pointer of a newly allocated mbuf 550.Fa m 551to 552.Fa len 553bytes from the end of the mbuf data area, so that 554.Fa len 555bytes of data written to the mbuf 556.Fa m , 557starting at the data pointer, will be aligned to the end of the data area. 558Implemented as a macro. 559.It Fn MH_ALIGN "struct mbuf *m" "int len" 560Sets the data pointer of a newly allocated packetheader mbuf 561.Fa m 562to 563.Fa len 564bytes from the end of the mbuf data area, so that 565.Fa len 566bytes of data written to the mbuf 567.Fa m , 568starting at the data pointer, will be aligned to the end of the data area. 569Implemented as a macro. 570.It Fn M_LEADINGSPACE "struct mbuf *m" 571Returns the amount of space available before the current start of valid 572data in mbuf 573.Fa m . 574Returns 0 if the mbuf data part is shared across multiple mbufs 575.Pq i.e. not writable . 576Implemented as a macro. 577.It Fn M_TRAILINGSPACE "struct mbuf *m" 578Returns the amount of space available after the current end of valid 579data in mbuf 580.Fa m . 581Returns 0 if the mbuf data part is shared across multiple mbufs 582.Pq i.e. not writable . 583Implemented as a macro. 584.It Fn M_PREPEND "struct mbuf *m" "int plen" "int how" 585Prepends space of size 586.Fa plen 587to mbuf 588.Fa m . 589If a new mbuf must be allocated, 590.Fa how 591specifies whether to wait. 592If 593.Fa how 594is 595.Dv M_DONTWAIT 596and allocation fails, the original mbuf chain is freed and 597.Fa m 598is set to 599.Dv NULL . 600Implemented as a macro. 601.It Fn MCHTYPE "struct mbuf *m" "int type" 602Change mbuf 603.Fa m 604to new type 605.Fa type . 606Implemented as a macro. 607.It Fn MEXTREMOVE "struct mbuf *m" 608Removes external storage from mbuf 609.Fa m . 610The flag 611.Dv M_EXT 612is removed. 613Implemented as a macro. 614.It Fn MFREE "struct mbuf *m" "struct mbuf *n" 615Frees a single mbuf 616.Fa m 617and places the successor, if any, in mbuf 618.Fa n . 619Implemented as a macro. 620.El 621.Sh FILES 622The 623.Nm 624management functions are implemented within the file 625.Pa sys/kern/uipc_mbuf.c . 626Function prototypes, and the functions implemented as macros 627are located in 628.Pa sys/sys/mbuf.h . 629Both pathnames are relative to the root of the 630.Nx 631source tree, 632.Pa /usr/src . 633.Sh SEE ALSO 634.Pa /usr/share/doc/smm/18.net , 635.Xr netstat 1 , 636.Xr malloc 9 637.Rs 638.%A Jun-ichiro Hagino 639.%T "Mbuf issues in 4.4BSD IPv6/IPsec support (experiences from KAME IPv6/IPsec implementation)" 640.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference" 641.%D June 2000 642.Re 643.Sh AUTHORS 644The original mbuf data structures were designed by Rob Gurwitz 645when he did the initial TCP/IP implementation at BBN. 646.br 647Further extensions and enhancements were made by Bill Joy, Sam Leffler, 648and Mike Karels at CSRG. 649.br 650Current implementation of external storage by 651.An Matt Thomas 652.Aq matt@3am-software.com 653and 654.An Jason R. Thorpe 655.Aq thorpej@NetBSD.org . 656