1.\" $NetBSD: mbuf.9,v 1.64 2018/05/07 10:53:45 maxv 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.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd May 7, 2018 31.Dt MBUF 9 32.Os 33.Sh NAME 34.Nm mbuf , 35.Nm m_get , 36.Nm m_gethdr , 37.Nm m_devget , 38.Nm m_copym , 39.Nm m_copypacket , 40.Nm m_copydata , 41.Nm m_copyback , 42.Nm m_copyback_cow , 43.Nm m_cat , 44.Nm m_dup , 45.Nm m_makewritable , 46.Nm m_pulldown , 47.Nm m_pullup , 48.Nm m_copyup , 49.Nm m_split , 50.Nm m_adj , 51.Nm m_apply , 52.Nm m_free , 53.Nm m_freem , 54.Nm mtod , 55.Nm MGET , 56.Nm MGETHDR , 57.Nm MEXTMALLOC , 58.Nm MEXTADD , 59.Nm MCLGET , 60.Nm M_COPY_PKTHDR , 61.Nm M_MOVE_PKTHDR , 62.Nm m_remove_pkthdr , 63.Nm M_ALIGN , 64.Nm MH_ALIGN , 65.Nm M_LEADINGSPACE , 66.Nm M_TRAILINGSPACE , 67.Nm M_PREPEND , 68.Nm MCHTYPE 69.Nd "functions and macros for managing memory used by networking code" 70.Sh SYNOPSIS 71.In sys/mbuf.h 72.Ft struct mbuf * 73.Fn m_get "int how" "int type" 74.Ft struct mbuf * 75.Fn m_gethdr "int how" "int type" 76.Ft struct mbuf * 77.Fn m_devget "char *buf" "int totlen" "int off0" "struct ifnet *ifp" "void (*copy)(const void *, void *, size_t)" 78.Ft struct mbuf * 79.Fn m_copym "struct mbuf *m" "int off" "int len" "int wait" 80.Ft struct mbuf * 81.Fn m_copypacket "struct mbuf *m" "int how" 82.Ft void 83.Fn m_copydata "struct mbuf *m" "int off" "int len" "void *cp" 84.Ft void 85.Fn m_copyback "struct mbuf *m0" "int off" "int len" "void *cp" 86.Ft struct mbuf * 87.Fn m_copyback_cow "struct mbuf *m0" "int off" "int len" "void *cp" "int how" 88.Ft int 89.Fn m_makewritable "struct mbuf **mp" "int off" "int len" "int how" 90.Ft void 91.Fn m_cat "struct mbuf *m" "struct mbuf *n" 92.Ft struct mbuf * 93.Fn m_dup "struct mbuf *m" "int off" "int len" "int wait" 94.Ft struct mbuf * 95.Fn m_pulldown "struct mbuf *m" "int off" "int len" "int *offp" 96.Ft struct mbuf * 97.Fn m_pullup "struct mbuf *n" "int len" 98.Ft struct mbuf * 99.Fn m_copyup "struct mbuf *m" "int len" "int dstoff" 100.Ft struct mbuf * 101.Fn m_split "struct mbuf *m0" "int len" "int wait" 102.Ft void 103.Fn m_adj "struct mbuf *mp" "int req_len" 104.Ft int 105.Fn m_apply "struct mbuf *m" "int off" "int len" "int *f(void *, void *, unsigned int)" "void *arg" 106.Ft struct mbuf * 107.Fn m_free "struct mbuf *m" 108.Ft void 109.Fn m_freem "struct mbuf *m" 110.Ft datatype 111.Fn mtod "struct mbuf *m" "datatype" 112.Ft void 113.Fn MGET "struct mbuf *m" "int how" "int type" 114.Ft void 115.Fn MGETHDR "struct mbuf *m" "int how" "int type" 116.Ft void 117.Fn MEXTMALLOC "struct mbuf *m" "int len" "int how" 118.Ft void 119.Fn MEXTADD "struct mbuf *m" "void *buf" "int size" "int type" "void (*free)(struct mbuf *, void *, size_t, void *)" "void *arg" 120.Ft void 121.Fn MCLGET "struct mbuf *m" "int how" 122.Ft void 123.Fn M_COPY_PKTHDR "struct mbuf *to" "struct mbuf *from" 124.Ft void 125.Fn M_MOVE_PKTHDR "struct mbuf *to" "struct mbuf *from" 126.Ft void 127.Fn m_remove_pkthdr "struct mbuf *m" 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.Sh DESCRIPTION 141The 142.Nm 143functions and macros provide an easy and consistent way to handle 144a networking stack's memory management needs. 145An 146.Nm 147consists of a header and a data area. 148It is of a fixed size, 149.Dv MSIZE 150.Pq defined in Aq Pa machine/param.h , 151which includes the size of the header. 152The header contains a pointer to the next 153.Nm 154in the 155.Sq "mbuf chain" , 156a pointer to the next 157.Sq "mbuf chain" , 158a pointer to the data area, the amount of data in this mbuf, its type 159and a 160.Dv flags 161field. 162.Pp 163The 164.Dv type 165variable can signify: 166.Bl -tag -compact -offset indent -width "XXXXXXXXXXX" 167.It Dv MT_FREE 168the mbuf should be on the ``free'' list 169.It Dv MT_DATA 170data was dynamically allocated 171.It Dv MT_HEADER 172data is a packet header 173.It Dv MT_SONAME 174data is a socket name 175.It Dv MT_SOOPTS 176data is socket options 177.It Dv MT_FTABLE 178data is the fragment reassembly header 179.It Dv MT_CONTROL 180mbuf contains ancillary \&(protocol control\&) data 181.It Dv MT_OOBDATA 182mbuf contains out-of-band data. 183.El 184.Pp 185The 186.Dv flags 187variable contains information describing the 188.Nm , 189notably: 190.Bl -tag -compact -offset indent -width "XXXXXXXXXXX" 191.It Dv M_EXT 192has external storage 193.It Dv M_PKTHDR 194is start of record 195.It Dv M_EOR 196is end of record 197.El 198.Pp 199If an 200.Nm 201designates the start of a record 202.Pq Dv M_PKTHDR , 203its 204.Dv flags 205field may contain additional information describing the content of 206the record: 207.Bl -tag -compact -offset indent -width "XXXXXXXXXXX" 208.It Dv M_BCAST 209sent/received as link-level broadcast 210.It Dv M_MCAST 211sent/received as link-level multicast 212.El 213.Pp 214An 215.Nm 216may add a single 217.Sq "mbuf cluster" 218of 219.Dv MCLBYTES 220bytes 221.Pq defined in Aq Pa machine/param.h , 222which has no additional overhead 223and is used instead of the internal data area; this is done when at least 224.Dv MINCLSIZE 225bytes of data must be stored. 226.Pp 227When the 228.Dv M_EXT 229flag is set on an mbuf, 230the external storage area could be shared among multiple mbufs. 231Therefore, care must be taken when overwriting the data content of an 232mbuf, because its external storage could be considered as read-only. 233.Bl -tag -width compact 234.It Fn m_get "int how" "int type" 235Allocates an mbuf and initializes it to contain internal data. 236The 237.Fa how 238parameter is a choice of 239.Dv M_WAIT / M_DONTWAIT 240from caller. 241.Dv M_WAIT 242means the call cannot fail, but may take forever. 243The 244.Fa type 245parameter is an mbuf type. 246.It Fn m_gethdr "int how" "int type" 247Allocates an mbuf and initializes it to contain a packet header and internal 248data. 249The 250.Fa how 251parameter is a choice of 252.Dv M_WAIT / M_DONTWAIT 253from caller. 254The 255.Fa type 256parameter is an mbuf type. 257.It Fn m_devget "char *buf" "int totlen" "int off0" "struct ifnet *ifp" "void (*copy)(const void *, void *, size_t)" 258Copies 259.Fa len 260bytes from device local memory into mbufs using copy routine 261.Fa copy . 262If parameter 263.Fa off 264is non-zero, the packet is supposed to be trailer-encapsulated and 265.Fa off 266bytes plus the type and length fields will be skipped before copying. 267Returns the top of the mbuf chain it created. 268.It Fn m_copym "struct mbuf *m" "int off" "int len" "int wait" 269Creates a copy of an mbuf chain starting 270.Fa off 271bytes from the beginning, continuing for 272.Fa len 273bytes. 274If the 275.Fa len 276requested is 277.Dv M_COPYALL , 278the complete mbuf chain will be copied. 279The 280.Fa wait 281parameter is a choice of 282.Dv M_WAIT / M_DONTWAIT 283from caller. 284.It Fn m_copypacket "struct mbuf *m" "int how" 285Copies an entire packet, including header. 286This function is an optimization of the common case 287.Li m_copym ( m , 0 , Dv M_COPYALL , Fa how ) . 288However, contrary to 289.Fn m_copym , 290a header must be present. 291It is incorrect to use 292.Fn m_copypacket 293with an mbuf that does not have a header. 294.It Fn m_copydata "struct mbuf *m" "int off" "int len" "void *cp" 295Copies 296.Fa len 297bytes data from mbuf chain 298.Fa m 299into the buffer 300.Fa cp , 301starting 302.Fa off 303bytes from the beginning. 304.It Fn m_copyback "struct mbuf *m0" "int off" "int len" "void *cp" 305Copies 306.Fa len 307bytes data from buffer 308.Fa cp 309back into the mbuf chain 310.Fa m0 , 311starting 312.Fa off 313bytes from the beginning of the chain, extending the mbuf chain if necessary. 314.Fn m_copyback 315can only fail when extending the chain. 316The caller should check for this kind of failure 317by checking the resulting length of the chain in that case. 318It is an error to use 319.Fn m_copyback 320on read-only mbufs. 321.It Fn m_copyback_cow "struct mbuf *m0" "int off" "int len" "void *cp" \ 322"int how" 323Copies 324.Fa len 325bytes data from buffer 326.Fa cp 327back into the mbuf chain 328.Fa m0 329as 330.Fn m_copyback 331does. 332Unlike 333.Fn m_copyback , 334it is safe to use 335.Fn m_copyback_cow 336on read-only mbufs. 337If needed, 338.Fn m_copyback_cow 339automatically allocates new mbufs and adjusts the chain. 340On success, it returns a pointer to the resulting mbuf chain, 341and frees the original mbuf 342.Fa m0 . 343Otherwise, it returns 344.Dv NULL . 345The 346.Fa how 347parameter is a choice of 348.Dv M_WAIT / M_DONTWAIT 349from the caller. 350Unlike 351.Fn m_copyback , 352extending the mbuf chain isn't supported. 353It is an error to attempt to extend the mbuf chain using 354.Fn m_copyback_cow . 355.It Fn m_makewritable "struct mbuf **mp" "int off" "int len" "int how" 356Rearranges an mbuf chain so that 357.Fa len 358bytes from offset 359.Fa off 360are writable. 361When it meets read-only mbufs, it allocates new mbufs, adjusts the chain as 362.Fn m_copyback_cow 363does, and copies the original content into them. 364.Fn m_makewritable 365does 366.Em not 367guarantee that all 368.Fa len 369bytes at 370.Fa off 371are consecutive. 372The 373.Fa how 374parameter is a choice of 375.Dv M_WAIT / M_DONTWAIT 376from the caller. 377.Fn m_makewritable 378preserves the contents of the mbuf chain even in the case of failure. 379It updates a pointer to the mbuf chain pointed to by 380.Fa mp . 381It returns 0 on success. 382Otherwise, it returns an error code, typically 383.Er ENOBUFS . 384.It Fn m_cat "struct mbuf *m" "struct mbuf *n" 385Concatenates mbuf chain 386.Fa n 387to 388.Fa m . 389Both chains must be of the same type; packet headers will 390.Em not 391be updated if present. 392.It Fn m_dup "struct mbuf *m" "int off" "int len" "int wait" 393Similarly to 394.Fn m_copym , 395the function creates a copy of an mbuf chain starting 396.Fa off 397bytes from the beginning, continuing for 398.Fa len 399bytes. 400While 401.Fn m_copym 402tries to share external storage for mbufs with 403.Dv M_EXT 404flag, 405.Fn m_dup 406will deep-copy the whole data content into new mbuf chain 407and avoids shared external storage. 408.It Fn m_pulldown "struct mbuf *m" "int off" "int len" "int *offp" 409Rearranges an mbuf chain so that 410.Fa len 411bytes from offset 412.Fa off 413are contiguous and in the data area of an mbuf. 414The return value points to an mbuf in the middle of the mbuf chain 415.Fa m . 416If we call the return value 417.Fa n , 418the contiguous data region is available at 419.Li "mtod(n, void *) + *offp" , 420or 421.Li "mtod(n, void *)" 422if 423.Fa offp 424is 425.Dv NULL . 426The top of the mbuf chain 427.Fa m , 428and mbufs up to 429.Fa off , 430will not be modified. 431On successful return, it is guaranteed that the mbuf pointed to by 432.Fa n 433does not have a shared external storage, 434therefore it is safe to update the contiguous region. 435Returns 436.Dv NULL 437and frees the mbuf chain on failure. 438.Fa len 439must be smaller than or equal to 440.Dv MCLBYTES . 441.It Fn m_pullup "struct mbuf *m" "int len" 442Rearranges an mbuf chain so that 443.Fa len 444bytes are contiguous 445and in the data area of an mbuf (so that 446.Fn mtod 447will work for a structure of size 448.Fa len ) . 449Returns the resulting 450mbuf chain on success, frees it and returns 451.Dv NULL 452on failure. 453If there is room, it will add up to 454.Dv max_protohdr 455- 456.Fa len 457extra bytes to the 458contiguous region to possibly avoid being called again. 459.Fa len 460must be smaller or equal than 461.Dv MHLEN . 462.It Fn m_copyup "struct mbuf *m" "int len" "int dstoff" 463Similar to 464.Fn m_pullup 465but copies 466.Fa len 467bytes of data into a new mbuf at 468.Fa dstoff 469bytes into the mbuf. 470The 471.Fa dstoff 472argument aligns the data and leaves room for a link layer header. 473Returns the new 474mbuf chain on success, and frees the mbuf chain and returns 475.Dv NULL 476on failure. 477Note that 478the function does not allocate mbuf clusters, so 479.Fa len + dstoff 480must be less than 481.Dv MHLEN . 482.It Fn m_split "struct mbuf *m0" "int len" "int wait" 483Partitions an mbuf chain in two pieces, returning the tail, 484which is all but the first 485.Fa len 486bytes. 487In case of failure, it returns 488.Dv NULL 489and restores the chain to its original state. 490.It Fn m_adj "struct mbuf *mp" "int req_len" 491Shaves off 492.Fa req_len 493bytes from head or tail of the (valid) data area. 494If 495.Fa req_len 496is greater than zero, front bytes are being shaved off, if it's smaller, 497from the back (and if it is zero, the mbuf will stay bearded). 498This function does not move data in any way, but is used to manipulate the 499data area pointer and data length variable of the mbuf in a non-clobbering 500way. 501.It Fn m_apply "struct mbuf *m" "int off" "int len" "int (*f)(void *, void *, unsigned int)" "void *arg" 502Apply function 503.Fa f 504to the data in an mbuf chain starting 505.Fa off 506bytes from the beginning, continuing for 507.Fa len 508bytes. 509Neither 510.Fa off 511nor 512.Fa len 513may be negative. 514.Fa arg 515will be supplied as first argument for 516.Fa f , 517the second argument will be the pointer to the data buffer of a 518packet (starting after 519.Fa off 520bytes in the stream), and the third argument is the amount 521of data in bytes in this call. 522If 523.Fa f 524returns something not equal to zero 525.Fn m_apply 526will bail out, returning the return code of 527.Fa f . 528Upon successful completion it will return zero. 529.It Fn m_free "struct mbuf *m" 530Frees mbuf 531.Fa m . 532.It Fn m_freem "struct mbuf *m" 533Frees the mbuf chain beginning with 534.Fa m . 535This function contains the elementary sanity check for a 536.Dv NULL 537pointer. 538.It Fn mtod "struct mbuf *m" "datatype" 539Returns a pointer to the data contained in the specified mbuf 540.Fa m , 541type-casted to the specified data type 542.Fa datatype . 543.It Fn MGET "struct mbuf *m" "int how" "int type" 544Allocates mbuf 545.Fa m 546and initializes it to contain internal data. 547See 548.Fn m_get . 549.It Fn MGETHDR "struct mbuf *m" "int how" "int type" 550Allocates mbuf 551.Fa m 552and initializes it to contain a packet header. 553See 554.Fn m_gethdr . 555.It Fn MEXTMALLOC "struct mbuf *m" "int len" "int how" 556Allocates external storage of size 557.Fa len 558for mbuf 559.Fa m . 560The 561.Fa how 562parameter is a choice of 563.Dv M_WAIT / M_DONTWAIT 564from caller. 565The flag 566.Dv M_EXT 567is set upon success. 568.It Fn MEXTADD "struct mbuf *m" "void *buf" "int size" "int type" "void (*free)(struct mbuf *, void *, size_t, void *)" "void *arg" 569Adds pre-allocated external storage 570.Fa buf 571to a normal mbuf 572.Fa m ; 573the parameters 574.Fa size , 575.Fa type , 576.Fa free 577and 578.Fa arg 579describe the external storage. 580.Fa size 581is the size of the storage, 582.Fa type 583describes its 584.Xr malloc 9 585type, 586.Fa free 587is a free routine (if not the usual one), and 588.Fa arg 589is a possible argument to the free routine. 590The flag 591.Dv M_EXT 592is set upon success. 593If a free routine is specified, it will be called when the mbuf is freed. 594In the case of former, the first argument for a free routine is the mbuf 595.Fa m 596and the routine is expected to free it in addition to the external storage 597pointed by second argument. 598In the case of latter, the first argument for the routine is NULL. 599.It Fn MCLGET "struct mbuf *m" "int how" 600Allocates and adds an mbuf cluster to a normal mbuf 601.Fa m . 602The 603.Fa how 604parameter is a choice of 605.Dv M_WAIT / M_DONTWAIT 606from caller. 607The flag 608.Dv M_EXT 609is set upon success. 610.It Fn M_COPY_PKTHDR "struct mbuf *to" "struct mbuf *from" 611Copies the mbuf pkthdr from mbuf 612.Fa from 613to mbuf 614.Fa to . 615.Fa from 616must have the type flag 617.Dv M_PKTHDR 618set, and 619.Fa to 620must be empty. 621.It Fn M_MOVE_PKTHDR "struct mbuf *to" "struct mbuf *from" 622Moves the mbuf pkthdr from mbuf 623.Fa from 624to mbuf 625.Fa to . 626.Fa from 627must have the type flag 628.Dv M_PKTHDR 629set, and 630.Fa to 631must be empty. 632The flag 633.Dv M_PKTHDR 634in mbuf 635.Fa from 636will be cleared. 637.It Fn m_remove_pkthdr "struct mbuf *m" 638Removes the mbuf pkthdr from mbuf 639.Fa m . 640.Fa m 641must have the flag 642.Dv M_PKTHDR 643set. 644This flag will be cleared. 645.It Fn M_ALIGN "struct mbuf *m" "int len" 646Sets the data pointer of a newly allocated mbuf 647.Fa m 648to 649.Fa len 650bytes from the end of the mbuf data area, so that 651.Fa len 652bytes of data written to the mbuf 653.Fa m , 654starting at the data pointer, will be aligned to the end of the data area. 655.It Fn MH_ALIGN "struct mbuf *m" "int len" 656Sets the data pointer of a newly allocated packetheader mbuf 657.Fa m 658to 659.Fa len 660bytes from the end of the mbuf data area, so that 661.Fa len 662bytes of data written to the mbuf 663.Fa m , 664starting at the data pointer, will be aligned to the end of the data area. 665.It Fn M_LEADINGSPACE "struct mbuf *m" 666Returns the amount of space available before the current start of valid 667data in mbuf 668.Fa m . 669Returns 0 if the mbuf data part is shared across multiple mbufs 670.Pq i.e. not writable . 671.It Fn M_TRAILINGSPACE "struct mbuf *m" 672Returns the amount of space available after the current end of valid 673data in mbuf 674.Fa m . 675Returns 0 if the mbuf data part is shared across multiple mbufs 676.Pq i.e. not writable . 677.It Fn M_PREPEND "struct mbuf *m" "int plen" "int how" 678Prepends space of size 679.Fa plen 680to mbuf 681.Fa m . 682If a new mbuf must be allocated, 683.Fa how 684specifies whether to wait. 685If 686.Fa how 687is 688.Dv M_DONTWAIT 689and allocation fails, the original mbuf chain is freed and 690.Fa m 691is set to 692.Dv NULL . 693It is illegal for the 694.Fa plen 695parameter to be greater than 696.Dv MHLEN . 697.It Fn MCHTYPE "struct mbuf *m" "int type" 698Change mbuf 699.Fa m 700to new type 701.Fa type . 702.El 703.Sh CODE REFERENCES 704The 705.Nm 706management functions are implemented within the file 707.Pa sys/kern/uipc_mbuf.c . 708Function prototypes, and the functions implemented as macros 709are located in 710.Pa sys/sys/mbuf.h . 711.Sh SEE ALSO 712.Pa /usr/share/doc/smm/18.net , 713.Xr netstat 1 , 714.Xr m_tag 9 , 715.Xr malloc 9 716.Rs 717.%A Jun-ichiro Hagino 718.%T "Mbuf issues in 4.4BSD IPv6/IPsec support (experiences from KAME IPv6/IPsec implementation)" 719.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference" 720.%D June 2000 721.Re 722.Sh AUTHORS 723.An -nosplit 724The original mbuf data structures were designed by Rob Gurwitz 725when he did the initial TCP/IP implementation at BBN. 726.Pp 727Further extensions and enhancements were made by Bill Joy, Sam Leffler, 728and Mike Karels at CSRG. 729.Pp 730Current implementation of external storage by 731.An Matt Thomas 732.Aq matt@3am-software.com 733and 734.An Jason R. Thorpe 735.Aq thorpej@NetBSD.org . 736