1.\" $NetBSD: mbuf.9,v 1.17 2001/09/04 02:51:16 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 <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) __P((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 *n" "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 type" "void (*free) __P((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) __P((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 *n" "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 type" "void (*free) __P((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 type , 503.Fa free 504and 505.Fa arg 506describe the external storage. 507.Fa type 508describes the 509.Xr malloc 9 510type of the storage, 511.Fa free 512is a free routine (if not the usual one), and 513.Fa arg 514is a possible argument to the free routine. 515The flag 516.Dv M_EXT 517is set upon success. 518Implemented as a macro. 519.It Fn MCLGET "struct mbuf *m" "int how" 520Allocates and adds an mbuf cluster to a normal mbuf 521.Fa m . 522The 523.Fa how 524parameter is a choice of 525.Dv M_WAIT / M_DONTWAIT 526from caller. 527The flag 528.Dv M_EXT 529is set upon success. 530Implemented as a macro. 531.It Fn M_COPY_PKTHDR "struct mbuf *to" "struct mbuf *from" 532Copies the mbuf pkthdr from mbuf 533.Fa from 534to mbuf 535.Fa to . 536.Fa from 537must have the type flag 538.Dv M_PKTHDR 539set, and 540.Fa to 541must be empty. 542Implemented as a macro. 543.It Fn M_ALIGN "struct mbuf *m" "int len" 544Sets the data pointer of a newly allocated mbuf 545.Fa m 546to 547.Fa len 548bytes from the end of the mbuf data area, so that 549.Fa len 550bytes of data written to the mbuf 551.Fa m , 552starting at the data pointer, will be aligned to the end of the data area. 553Implemented as a macro. 554.It Fn MH_ALIGN "struct mbuf *m" "int len" 555Sets the data pointer of a newly allocated packetheader mbuf 556.Fa m 557to 558.Fa len 559bytes from the end of the mbuf data area, so that 560.Fa len 561bytes of data written to the mbuf 562.Fa m , 563starting at the data pointer, will be aligned to the end of the data area. 564Implemented as a macro. 565.It Fn M_LEADINGSPACE "struct mbuf *m" 566Returns the amount of space available before the current start of valid 567data in mbuf 568.Fa m . 569Returns 0 if the mbuf data part is shared across multiple mbufs 570.Pq i.e. not writable . 571Implemented as a macro. 572.It Fn M_TRAILINGSPACE "struct mbuf *m" 573Returns the amount of space available after the current end of valid 574data in mbuf 575.Fa m . 576Returns 0 if the mbuf data part is shared across multiple mbufs 577.Pq i.e. not writable . 578Implemented as a macro. 579.It Fn M_PREPEND "struct mbuf *m" "int plen" "int how" 580Prepends space of size 581.Fa plen 582to mbuf 583.Fa m . 584If a new mbuf must be allocated, 585.Fa how 586specifies whether to wait. 587If 588.Fa how 589is 590.Dv M_DONTWAIT 591and allocation fails, the original mbuf chain is freed and 592.Fa m 593is set to 594.Dv NULL . 595Implemented as a macro. 596.It Fn MCHTYPE "struct mbuf *m" "int type" 597Change mbuf 598.Fa m 599to new type 600.Fa type . 601Implemented as a macro. 602.It Fn MEXTREMOVE "struct mbuf *m" 603Removes external storage from mbuf 604.Fa m . 605The flag 606.Dv M_EXT 607is removed. 608Implemented as a macro. 609.It Fn MFREE "struct mbuf *m" "struct mbuf *n" 610Frees a single mbuf 611.Fa m 612and places the successor, if any, in mbuf 613.Fa n . 614Implemented as a macro. 615.El 616.\" .Sh ERRORS 617.Sh SEE ALSO 618.Pa /usr/share/doc/smm/18.net , 619.Xr netstat 1 , 620.Xr malloc 9 621.Rs 622.%A Jun-ichiro Hagino 623.%T "Mbuf issues in 4.4BSD IPv6/IPsec support (experiences from KAME IPv6/IPsec implemntation)" 624.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference" 625.%D June 2000 626.Re 627.Sh AUTHORS 628The original mbuf data structures were designed by Rob Gurwitz 629when he did the initial TCP/IP implementation at BBN. 630.br 631Further extensions and enhancements were made by Bill Joy, Sam Leffler, 632and Mike Karels at CSRG. 633.br 634Current implementation of external storage by Matt Thomas 635.br 636<matt@3am-software.com> and Jason R. Thorpe <thorpej@NetBSD.ORG>. 637.Sh FILES 638The 639.Nm 640management functions are implemented within the file 641.Pa sys/kern/uipc_mbuf.c . 642Function prototypes, and the functions implemented as macros 643are located in 644.Pa sys/sys/mbuf.h . 645Both pathnames are relative to the root of the 646.Nx 647source tree, 648.Pa /usr/src . 649.\" .Sh HISTORY 650