1.\" Copyright (c) 2000 FreeBSD Inc. 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL [your name] OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd April 8, 2021 28.Dt MBUF 9 29.Os 30.\" 31.Sh NAME 32.Nm mbuf 33.Nd "memory management in the kernel IPC subsystem" 34.\" 35.Sh SYNOPSIS 36.In sys/param.h 37.In sys/systm.h 38.In sys/mbuf.h 39.\" 40.Ss Mbuf allocation macros 41.Fn MGET "struct mbuf *mbuf" "int how" "short type" 42.Fn MGETHDR "struct mbuf *mbuf" "int how" "short type" 43.Ft int 44.Fn MCLGET "struct mbuf *mbuf" "int how" 45.Fo MEXTADD 46.Fa "struct mbuf *mbuf" 47.Fa "char *buf" 48.Fa "u_int size" 49.Fa "void (*free)(struct mbuf *)" 50.Fa "void *opt_arg1" 51.Fa "void *opt_arg2" 52.Fa "int flags" 53.Fa "int type" 54.Fc 55.\" 56.Ss Mbuf utility macros 57.Fn mtod "struct mbuf *mbuf" "type" 58.Fn M_ALIGN "struct mbuf *mbuf" "u_int len" 59.Fn MH_ALIGN "struct mbuf *mbuf" "u_int len" 60.Ft int 61.Fn M_LEADINGSPACE "struct mbuf *mbuf" 62.Ft int 63.Fn M_TRAILINGSPACE "struct mbuf *mbuf" 64.Fn M_MOVE_PKTHDR "struct mbuf *to" "struct mbuf *from" 65.Fn M_PREPEND "struct mbuf *mbuf" "int len" "int how" 66.Fn MCHTYPE "struct mbuf *mbuf" "short type" 67.Ft int 68.Fn M_WRITABLE "struct mbuf *mbuf" 69.\" 70.Ss Mbuf allocation functions 71.Ft struct mbuf * 72.Fn m_get "int how" "short type" 73.Ft struct mbuf * 74.Fn m_get2 "int size" "int how" "short type" "int flags" 75.Ft struct mbuf * 76.Fn m_getm "struct mbuf *orig" "int len" "int how" "short type" 77.Ft struct mbuf * 78.Fn m_getjcl "int how" "short type" "int flags" "int size" 79.Ft struct mbuf * 80.Fn m_getcl "int how" "short type" "int flags" 81.Ft struct mbuf * 82.Fn m_gethdr "int how" "short type" 83.Ft struct mbuf * 84.Fn m_free "struct mbuf *mbuf" 85.Ft void 86.Fn m_freem "struct mbuf *mbuf" 87.\" 88.Ss Mbuf utility functions 89.Ft void 90.Fn m_adj "struct mbuf *mbuf" "int len" 91.Ft void 92.Fn m_align "struct mbuf *mbuf" "int len" 93.Ft int 94.Fn m_append "struct mbuf *mbuf" "int len" "c_caddr_t cp" 95.Ft struct mbuf * 96.Fn m_prepend "struct mbuf *mbuf" "int len" "int how" 97.Ft struct mbuf * 98.Fn m_copyup "struct mbuf *mbuf" "int len" "int dstoff" 99.Ft struct mbuf * 100.Fn m_pullup "struct mbuf *mbuf" "int len" 101.Ft struct mbuf * 102.Fn m_pulldown "struct mbuf *mbuf" "int offset" "int len" "int *offsetp" 103.Ft struct mbuf * 104.Fn m_copym "struct mbuf *mbuf" "int offset" "int len" "int how" 105.Ft struct mbuf * 106.Fn m_copypacket "struct mbuf *mbuf" "int how" 107.Ft struct mbuf * 108.Fn m_dup "const struct mbuf *mbuf" "int how" 109.Ft void 110.Fn m_copydata "const struct mbuf *mbuf" "int offset" "int len" "caddr_t buf" 111.Ft void 112.Fn m_copyback "struct mbuf *mbuf" "int offset" "int len" "caddr_t buf" 113.Ft struct mbuf * 114.Fo m_devget 115.Fa "char *buf" 116.Fa "int len" 117.Fa "int offset" 118.Fa "struct ifnet *ifp" 119.Fa "void (*copy)(char *from, caddr_t to, u_int len)" 120.Fc 121.Ft void 122.Fn m_cat "struct mbuf *m" "struct mbuf *n" 123.Ft void 124.Fn m_catpkt "struct mbuf *m" "struct mbuf *n" 125.Ft u_int 126.Fn m_fixhdr "struct mbuf *mbuf" 127.Ft int 128.Fn m_dup_pkthdr "struct mbuf *to" "const struct mbuf *from" "int how" 129.Ft void 130.Fn m_move_pkthdr "struct mbuf *to" "struct mbuf *from" 131.Ft u_int 132.Fn m_length "struct mbuf *mbuf" "struct mbuf **last" 133.Ft struct mbuf * 134.Fn m_split "struct mbuf *mbuf" "int len" "int how" 135.Ft int 136.Fn m_apply "struct mbuf *mbuf" "int off" "int len" "int (*f)(void *arg, void *data, u_int len)" "void *arg" 137.Ft struct mbuf * 138.Fn m_getptr "struct mbuf *mbuf" "int loc" "int *off" 139.Ft struct mbuf * 140.Fn m_defrag "struct mbuf *m0" "int how" 141.Ft struct mbuf * 142.Fn m_collapse "struct mbuf *m0" "int how" "int maxfrags" 143.Ft struct mbuf * 144.Fn m_unshare "struct mbuf *m0" "int how" 145.\" 146.Sh DESCRIPTION 147An 148.Vt mbuf 149is a basic unit of memory management in the kernel IPC subsystem. 150Network packets and socket buffers are stored in 151.Vt mbufs . 152A network packet may span multiple 153.Vt mbufs 154arranged into a 155.Vt mbuf chain 156(linked list), 157which allows adding or trimming 158network headers with little overhead. 159.Pp 160While a developer should not bother with 161.Vt mbuf 162internals without serious 163reason in order to avoid incompatibilities with future changes, it 164is useful to understand the general structure of an 165.Vt mbuf . 166.Pp 167An 168.Vt mbuf 169consists of a variable-sized header and a small internal 170buffer for data. 171The total size of an 172.Vt mbuf , 173.Dv MSIZE , 174is a constant defined in 175.In sys/param.h . 176The 177.Vt mbuf 178header includes: 179.Bl -tag -width "m_nextpkt" -offset indent 180.It Va m_next 181.Pq Vt struct mbuf * 182A pointer to the next 183.Vt mbuf 184in the 185.Vt mbuf chain . 186.It Va m_nextpkt 187.Pq Vt struct mbuf * 188A pointer to the next 189.Vt mbuf chain 190in the queue. 191.It Va m_data 192.Pq Vt caddr_t 193A pointer to data attached to this 194.Vt mbuf . 195.It Va m_len 196.Pq Vt int 197The length of the data. 198.It Va m_type 199.Pq Vt short 200The type of the data. 201.It Va m_flags 202.Pq Vt int 203The 204.Vt mbuf 205flags. 206.El 207.Pp 208The 209.Vt mbuf 210flag bits are defined as follows: 211.Bd -literal 212#define M_EXT 0x00000001 /* has associated external storage */ 213#define M_PKTHDR 0x00000002 /* start of record */ 214#define M_EOR 0x00000004 /* end of record */ 215#define M_RDONLY 0x00000008 /* associated data marked read-only */ 216#define M_BCAST 0x00000010 /* send/received as link-level broadcast */ 217#define M_MCAST 0x00000020 /* send/received as link-level multicast */ 218#define M_PROMISC 0x00000040 /* packet was not for us */ 219#define M_VLANTAG 0x00000080 /* ether_vtag is valid */ 220#define M_EXTPG 0x00000100 /* has array of unmapped pages and TLS */ 221#define M_NOFREE 0x00000200 /* do not free mbuf, embedded in cluster */ 222#define M_TSTMP 0x00000400 /* rcv_tstmp field is valid */ 223#define M_TSTMP_HPREC 0x00000800 /* rcv_tstmp is high-prec, typically 224 hw-stamped on port (useful for IEEE 1588 225 and 802.1AS) */ 226 227#define M_PROTO1 0x00001000 /* protocol-specific */ 228#define M_PROTO2 0x00002000 /* protocol-specific */ 229#define M_PROTO3 0x00004000 /* protocol-specific */ 230#define M_PROTO4 0x00008000 /* protocol-specific */ 231#define M_PROTO5 0x00010000 /* protocol-specific */ 232#define M_PROTO6 0x00020000 /* protocol-specific */ 233#define M_PROTO7 0x00040000 /* protocol-specific */ 234#define M_PROTO8 0x00080000 /* protocol-specific */ 235#define M_PROTO9 0x00100000 /* protocol-specific */ 236#define M_PROTO10 0x00200000 /* protocol-specific */ 237#define M_PROTO11 0x00400000 /* protocol-specific */ 238#define M_PROTO12 0x00800000 /* protocol-specific */ 239.Ed 240.Pp 241The available 242.Vt mbuf 243types are defined as follows: 244.Bd -literal 245#define MT_DATA 1 /* dynamic (data) allocation */ 246#define MT_HEADER MT_DATA /* packet header */ 247 248#define MT_VENDOR1 4 /* for vendor-internal use */ 249#define MT_VENDOR2 5 /* for vendor-internal use */ 250#define MT_VENDOR3 6 /* for vendor-internal use */ 251#define MT_VENDOR4 7 /* for vendor-internal use */ 252 253#define MT_SONAME 8 /* socket name */ 254 255#define MT_EXP1 9 /* for experimental use */ 256#define MT_EXP2 10 /* for experimental use */ 257#define MT_EXP3 11 /* for experimental use */ 258#define MT_EXP4 12 /* for experimental use */ 259 260#define MT_CONTROL 14 /* extra-data protocol message */ 261#define MT_EXTCONTROL 15 /* control message with externalized contents */ 262#define MT_OOBDATA 16 /* expedited data */ 263.Ed 264.Pp 265The available external buffer types are defined as follows: 266.Bd -literal 267#define EXT_CLUSTER 1 /* mbuf cluster */ 268#define EXT_SFBUF 2 /* sendfile(2)'s sf_bufs */ 269#define EXT_JUMBOP 3 /* jumbo cluster 4096 bytes */ 270#define EXT_JUMBO9 4 /* jumbo cluster 9216 bytes */ 271#define EXT_JUMBO16 5 /* jumbo cluster 16184 bytes */ 272#define EXT_PACKET 6 /* mbuf+cluster from packet zone */ 273#define EXT_MBUF 7 /* external mbuf reference */ 274#define EXT_RXRING 8 /* data in NIC receive ring */ 275#define EXT_PGS 9 /* array of unmapped pages */ 276 277#define EXT_VENDOR1 224 /* for vendor-internal use */ 278#define EXT_VENDOR2 225 /* for vendor-internal use */ 279#define EXT_VENDOR3 226 /* for vendor-internal use */ 280#define EXT_VENDOR4 227 /* for vendor-internal use */ 281 282#define EXT_EXP1 244 /* for experimental use */ 283#define EXT_EXP2 245 /* for experimental use */ 284#define EXT_EXP3 246 /* for experimental use */ 285#define EXT_EXP4 247 /* for experimental use */ 286 287#define EXT_NET_DRV 252 /* custom ext_buf provided by net driver(s) */ 288#define EXT_MOD_TYPE 253 /* custom module's ext_buf type */ 289#define EXT_DISPOSABLE 254 /* can throw this buffer away w/page flipping */ 290#define EXT_EXTREF 255 /* has externally maintained ref_cnt ptr */ 291.Ed 292.Pp 293If the 294.Dv M_PKTHDR 295flag is set, a 296.Vt struct pkthdr Va m_pkthdr 297is added to the 298.Vt mbuf 299header. 300It contains a pointer to the interface 301the packet has been received from 302.Pq Vt struct ifnet Va *rcvif , 303and the total packet length 304.Pq Vt int Va len . 305Optionally, it may also contain an attached list of packet tags 306.Pq Vt "struct m_tag" . 307See 308.Xr mbuf_tags 9 309for details. 310Fields used in offloading checksum calculation to the hardware are kept in 311.Va m_pkthdr 312as well. 313See 314.Sx HARDWARE-ASSISTED CHECKSUM CALCULATION 315for details. 316.Pp 317If small enough, data is stored in the internal data buffer of an 318.Vt mbuf . 319If the data is sufficiently large, another 320.Vt mbuf 321may be added to the 322.Vt mbuf chain , 323or external storage may be associated with the 324.Vt mbuf . 325.Dv MHLEN 326bytes of data can fit into an 327.Vt mbuf 328with the 329.Dv M_PKTHDR 330flag set, 331.Dv MLEN 332bytes can otherwise. 333.Pp 334If external storage is being associated with an 335.Vt mbuf , 336the 337.Va m_ext 338header is added at the cost of losing the internal data buffer. 339It includes a pointer to external storage, the size of the storage, 340a pointer to a function used for freeing the storage, 341a pointer to an optional argument that can be passed to the function, 342and a pointer to a reference counter. 343An 344.Vt mbuf 345using external storage has the 346.Dv M_EXT 347flag set. 348.Pp 349The system supplies a macro for allocating the desired external storage 350buffer, 351.Dv MEXTADD . 352.Pp 353The allocation and management of the reference counter is handled by the 354subsystem. 355.Pp 356The system also supplies a default type of external storage buffer called an 357.Vt mbuf cluster . 358.Vt Mbuf clusters 359can be allocated and configured with the use of the 360.Dv MCLGET 361macro. 362Each 363.Vt mbuf cluster 364is 365.Dv MCLBYTES 366in size, where MCLBYTES is a machine-dependent constant. 367The system defines an advisory macro 368.Dv MINCLSIZE , 369which is the smallest amount of data to put into an 370.Vt mbuf cluster . 371It is equal to 372.Dv MHLEN 373plus one. 374It is typically preferable to store data into the data region of an 375.Vt mbuf , 376if size permits, as opposed to allocating a separate 377.Vt mbuf cluster 378to hold the same data. 379.\" 380.Ss Macros and Functions 381There are numerous predefined macros and functions that provide the 382developer with common utilities. 383.\" 384.Bl -ohang -offset indent 385.It Fn mtod mbuf type 386Convert an 387.Fa mbuf 388pointer to a data pointer. 389The macro expands to the data pointer cast to the specified 390.Fa type . 391.Sy Note : 392It is advisable to ensure that there is enough contiguous data in 393.Fa mbuf . 394See 395.Fn m_pullup 396for details. 397.It Fn MGET mbuf how type 398Allocate an 399.Vt mbuf 400and initialize it to contain internal data. 401.Fa mbuf 402will point to the allocated 403.Vt mbuf 404on success, or be set to 405.Dv NULL 406on failure. 407The 408.Fa how 409argument is to be set to 410.Dv M_WAITOK 411or 412.Dv M_NOWAIT . 413It specifies whether the caller is willing to block if necessary. 414A number of other functions and macros related to 415.Vt mbufs 416have the same argument because they may 417at some point need to allocate new 418.Vt mbufs . 419.It Fn MGETHDR mbuf how type 420Allocate an 421.Vt mbuf 422and initialize it to contain a packet header 423and internal data. 424See 425.Fn MGET 426for details. 427.It Fn MEXTADD mbuf buf size free opt_arg1 opt_arg2 flags type 428Associate externally managed data with 429.Fa mbuf . 430Any internal data contained in the mbuf will be discarded, and the 431.Dv M_EXT 432flag will be set. 433The 434.Fa buf 435and 436.Fa size 437arguments are the address and length, respectively, of the data. 438The 439.Fa free 440argument points to a function which will be called to free the data 441when the mbuf is freed; it is only used if 442.Fa type 443is 444.Dv EXT_EXTREF . 445The 446.Fa opt_arg1 447and 448.Fa opt_arg2 449arguments will be saved in 450.Va ext_arg1 451and 452.Va ext_arg2 453fields of the 454.Va struct m_ext 455of the mbuf. 456The 457.Fa flags 458argument specifies additional 459.Vt mbuf 460flags; it is not necessary to specify 461.Dv M_EXT . 462Finally, the 463.Fa type 464argument specifies the type of external data, which controls how it 465will be disposed of when the 466.Vt mbuf 467is freed. 468In most cases, the correct value is 469.Dv EXT_EXTREF . 470.It Fn MCLGET mbuf how 471Allocate and attach an 472.Vt mbuf cluster 473to 474.Fa mbuf . 475On success, a non-zero value returned; otherwise, 0. 476Historically, consumers would check for success by testing the 477.Dv M_EXT 478flag on the mbuf, but this is now discouraged to avoid unnecessary awareness 479of the implementation of external storage in protocol stacks and device 480drivers. 481.It Fn M_ALIGN mbuf len 482Set the pointer 483.Fa mbuf->m_data 484to place an object of the size 485.Fa len 486at the end of the internal data area of 487.Fa mbuf , 488long word aligned. 489Applicable only if 490.Fa mbuf 491is newly allocated with 492.Fn MGET 493or 494.Fn m_get . 495.It Fn MH_ALIGN mbuf len 496Serves the same purpose as 497.Fn M_ALIGN 498does, but only for 499.Fa mbuf 500newly allocated with 501.Fn MGETHDR 502or 503.Fn m_gethdr , 504or initialized by 505.Fn m_dup_pkthdr 506or 507.Fn m_move_pkthdr . 508.It Fn m_align mbuf len 509Services the same purpose as 510.Fn M_ALIGN 511but handles any type of mbuf. 512.It Fn M_LEADINGSPACE mbuf 513Returns the number of bytes available before the beginning 514of data in 515.Fa mbuf . 516.It Fn M_TRAILINGSPACE mbuf 517Returns the number of bytes available after the end of data in 518.Fa mbuf . 519.It Fn M_PREPEND mbuf len how 520This macro operates on an 521.Vt mbuf chain . 522It is an optimized wrapper for 523.Fn m_prepend 524that can make use of possible empty space before data 525(e.g.\& left after trimming of a link-layer header). 526The new 527.Vt mbuf chain 528pointer or 529.Dv NULL 530is in 531.Fa mbuf 532after the call. 533.It Fn M_MOVE_PKTHDR to from 534Using this macro is equivalent to calling 535.Fn m_move_pkthdr to from . 536.It Fn M_WRITABLE mbuf 537This macro will evaluate true if 538.Fa mbuf 539is not marked 540.Dv M_RDONLY 541and if either 542.Fa mbuf 543does not contain external storage or, 544if it does, 545then if the reference count of the storage is not greater than 1. 546The 547.Dv M_RDONLY 548flag can be set in 549.Fa mbuf->m_flags . 550This can be achieved during setup of the external storage, 551by passing the 552.Dv M_RDONLY 553bit as a 554.Fa flags 555argument to the 556.Fn MEXTADD 557macro, or can be directly set in individual 558.Vt mbufs . 559.It Fn MCHTYPE mbuf type 560Change the type of 561.Fa mbuf 562to 563.Fa type . 564This is a relatively expensive operation and should be avoided. 565.El 566.Pp 567The functions are: 568.Bl -ohang -offset indent 569.It Fn m_get how type 570A function version of 571.Fn MGET 572for non-critical paths. 573.It Fn m_get2 size how type flags 574Allocate an 575.Vt mbuf 576with enough space to hold specified amount of data. 577If the size is is larger than 578.Dv MJUMPAGESIZE , NULL 579will be returned. 580.It Fn m_getm orig len how type 581Allocate 582.Fa len 583bytes worth of 584.Vt mbufs 585and 586.Vt mbuf clusters 587if necessary and append the resulting allocated 588.Vt mbuf chain 589to the 590.Vt mbuf chain 591.Fa orig , 592if it is 593.No non- Ns Dv NULL . 594If the allocation fails at any point, 595free whatever was allocated and return 596.Dv NULL . 597If 598.Fa orig 599is 600.No non- Ns Dv NULL , 601it will not be freed. 602It is possible to use 603.Fn m_getm 604to either append 605.Fa len 606bytes to an existing 607.Vt mbuf 608or 609.Vt mbuf chain 610(for example, one which may be sitting in a pre-allocated ring) 611or to simply perform an all-or-nothing 612.Vt mbuf 613and 614.Vt mbuf cluster 615allocation. 616.It Fn m_gethdr how type 617A function version of 618.Fn MGETHDR 619for non-critical paths. 620.It Fn m_getcl how type flags 621Fetch an 622.Vt mbuf 623with a 624.Vt mbuf cluster 625attached to it. 626If one of the allocations fails, the entire allocation fails. 627This routine is the preferred way of fetching both the 628.Vt mbuf 629and 630.Vt mbuf cluster 631together, as it avoids having to unlock/relock between allocations. 632Returns 633.Dv NULL 634on failure. 635.It Fn m_getjcl how type flags size 636This is like 637.Fn m_getcl 638but the specified 639.Fa size 640of the cluster to be allocated must be one of 641.Dv MCLBYTES , MJUMPAGESIZE , MJUM9BYTES , 642or 643.Dv MJUM16BYTES . 644.It Fn m_free mbuf 645Frees 646.Vt mbuf . 647Returns 648.Va m_next 649of the freed 650.Vt mbuf . 651.El 652.Pp 653The functions below operate on 654.Vt mbuf chains . 655.Bl -ohang -offset indent 656.It Fn m_freem mbuf 657Free an entire 658.Vt mbuf chain , 659including any external storage. 660.\" 661.It Fn m_adj mbuf len 662Trim 663.Fa len 664bytes from the head of an 665.Vt mbuf chain 666if 667.Fa len 668is positive, from the tail otherwise. 669.\" 670.It Fn m_append mbuf len cp 671Append 672.Vt len 673bytes of data 674.Vt cp 675to the 676.Vt mbuf chain . 677Extend the mbuf chain if the new data does not fit in 678existing space. 679.\" 680.It Fn m_prepend mbuf len how 681Allocate a new 682.Vt mbuf 683and prepend it to the 684.Vt mbuf chain , 685handle 686.Dv M_PKTHDR 687properly. 688.Sy Note : 689It does not allocate any 690.Vt mbuf clusters , 691so 692.Fa len 693must be less than 694.Dv MLEN 695or 696.Dv MHLEN , 697depending on the 698.Dv M_PKTHDR 699flag setting. 700.\" 701.It Fn m_copyup mbuf len dstoff 702Similar to 703.Fn m_pullup 704but copies 705.Fa len 706bytes of data into a new mbuf at 707.Fa dstoff 708bytes into the mbuf. 709The 710.Fa dstoff 711argument aligns the data and leaves room for a link layer header. 712Returns the new 713.Vt mbuf chain 714on success, 715and frees the 716.Vt mbuf chain 717and returns 718.Dv NULL 719on failure. 720.Sy Note : 721The function does not allocate 722.Vt mbuf clusters , 723so 724.Fa len + dstoff 725must be less than 726.Dv MHLEN . 727.\" 728.It Fn m_pullup mbuf len 729Arrange that the first 730.Fa len 731bytes of an 732.Vt mbuf chain 733are contiguous and lay in the data area of 734.Fa mbuf , 735so they are accessible with 736.Fn mtod mbuf type . 737It is important to remember that this may involve 738reallocating some mbufs and moving data so all pointers 739referencing data within the old mbuf chain 740must be recalculated or made invalid. 741Return the new 742.Vt mbuf chain 743on success, 744.Dv NULL 745on failure 746(the 747.Vt mbuf chain 748is freed in this case). 749.Sy Note : 750It does not allocate any 751.Vt mbuf clusters , 752so 753.Fa len 754must be less than or equal to 755.Dv MHLEN . 756.\" 757.It Fn m_pulldown mbuf offset len offsetp 758Arrange that 759.Fa len 760bytes between 761.Fa offset 762and 763.Fa offset + len 764in the 765.Vt mbuf chain 766are contiguous and lay in the data area of 767.Fa mbuf , 768so they are accessible with 769.Fn mtod mbuf type . 770.Fa len 771must be smaller than, or equal to, the size of an 772.Vt mbuf cluster . 773Return a pointer to an intermediate 774.Vt mbuf 775in the chain containing the requested region; 776the offset in the data region of the 777.Vt mbuf chain 778to the data contained in the returned mbuf is stored in 779.Fa *offsetp . 780If 781.Fa offsetp 782is NULL, the region may be accessed using 783.Fn mtod mbuf type . 784If 785.Fa offsetp 786is non-NULL, the region may be accessed using 787.Fn mtod mbuf uint8_t 788+ *offsetp. 789The region of the mbuf chain between its beginning and 790.Fa offset 791is not modified, therefore it is safe to hold pointers to data within 792this region before calling 793.Fn m_pulldown . 794.\" 795.It Fn m_copym mbuf offset len how 796Make a copy of an 797.Vt mbuf chain 798starting 799.Fa offset 800bytes from the beginning, continuing for 801.Fa len 802bytes. 803If 804.Fa len 805is 806.Dv M_COPYALL , 807copy to the end of the 808.Vt mbuf chain . 809.Sy Note : 810The copy is read-only, because the 811.Vt mbuf clusters 812are not copied, only their reference counts are incremented. 813.\" 814.It Fn m_copypacket mbuf how 815Copy an entire packet including header, which must be present. 816This is an optimized version of the common case 817.Fn m_copym mbuf 0 M_COPYALL how . 818.Sy Note : 819the copy is read-only, because the 820.Vt mbuf clusters 821are not copied, only their reference counts are incremented. 822.\" 823.It Fn m_dup mbuf how 824Copy a packet header 825.Vt mbuf chain 826into a completely new 827.Vt mbuf chain , 828including copying any 829.Vt mbuf clusters . 830Use this instead of 831.Fn m_copypacket 832when you need a writable copy of an 833.Vt mbuf chain . 834.\" 835.It Fn m_copydata mbuf offset len buf 836Copy data from an 837.Vt mbuf chain 838starting 839.Fa off 840bytes from the beginning, continuing for 841.Fa len 842bytes, into the indicated buffer 843.Fa buf . 844.\" 845.It Fn m_copyback mbuf offset len buf 846Copy 847.Fa len 848bytes from the buffer 849.Fa buf 850back into the indicated 851.Vt mbuf chain , 852starting at 853.Fa offset 854bytes from the beginning of the 855.Vt mbuf chain , 856extending the 857.Vt mbuf chain 858if necessary. 859.Sy Note : 860It does not allocate any 861.Vt mbuf clusters , 862just adds 863.Vt mbufs 864to the 865.Vt mbuf chain . 866It is safe to set 867.Fa offset 868beyond the current 869.Vt mbuf chain 870end: zeroed 871.Vt mbufs 872will be allocated to fill the space. 873.\" 874.It Fn m_length mbuf last 875Return the length of the 876.Vt mbuf chain , 877and optionally a pointer to the last 878.Vt mbuf . 879.\" 880.It Fn m_dup_pkthdr to from how 881Upon the function's completion, the 882.Vt mbuf 883.Fa to 884will contain an identical copy of 885.Fa from->m_pkthdr 886and the per-packet attributes found in the 887.Vt mbuf chain 888.Fa from . 889The 890.Vt mbuf 891.Fa from 892must have the flag 893.Dv M_PKTHDR 894initially set, and 895.Fa to 896must be empty on entry. 897.\" 898.It Fn m_move_pkthdr to from 899Move 900.Va m_pkthdr 901and the per-packet attributes from the 902.Vt mbuf chain 903.Fa from 904to the 905.Vt mbuf 906.Fa to . 907The 908.Vt mbuf 909.Fa from 910must have the flag 911.Dv M_PKTHDR 912initially set, and 913.Fa to 914must be empty on entry. 915Upon the function's completion, 916.Fa from 917will have the flag 918.Dv M_PKTHDR 919and the per-packet attributes cleared. 920.\" 921.It Fn m_fixhdr mbuf 922Set the packet-header length to the length of the 923.Vt mbuf chain . 924.\" 925.It Fn m_devget buf len offset ifp copy 926Copy data from a device local memory pointed to by 927.Fa buf 928to an 929.Vt mbuf chain . 930The copy is done using a specified copy routine 931.Fa copy , 932or 933.Fn bcopy 934if 935.Fa copy 936is 937.Dv NULL . 938.\" 939.It Fn m_cat m n 940Concatenate 941.Fa n 942to 943.Fa m . 944Both 945.Vt mbuf chains 946must be of the same type. 947.Fa n 948is not guaranteed to be valid after 949.Fn m_cat 950returns. 951.Fn m_cat 952does not update any packet header fields or free mbuf tags. 953.\" 954.It Fn m_catpkt m n 955A variant of 956.Fn m_cat 957that operates on packets. 958Both 959.Fa m 960and 961.Fa n 962must contain packet headers. 963.Fa n 964is not guaranteed to be valid after 965.Fn m_catpkt 966returns. 967.\" 968.It Fn m_split mbuf len how 969Partition an 970.Vt mbuf chain 971in two pieces, returning the tail: 972all but the first 973.Fa len 974bytes. 975In case of failure, it returns 976.Dv NULL 977and attempts to restore the 978.Vt mbuf chain 979to its original state. 980.\" 981.It Fn m_apply mbuf off len f arg 982Apply a function to an 983.Vt mbuf chain , 984at offset 985.Fa off , 986for length 987.Fa len 988bytes. 989Typically used to avoid calls to 990.Fn m_pullup 991which would otherwise be unnecessary or undesirable. 992.Fa arg 993is a convenience argument which is passed to the callback function 994.Fa f . 995.Pp 996Each time 997.Fn f 998is called, it will be passed 999.Fa arg , 1000a pointer to the 1001.Fa data 1002in the current mbuf, and the length 1003.Fa len 1004of the data in this mbuf to which the function should be applied. 1005.Pp 1006The function should return zero to indicate success; 1007otherwise, if an error is indicated, then 1008.Fn m_apply 1009will return the error and stop iterating through the 1010.Vt mbuf chain . 1011.\" 1012.It Fn m_getptr mbuf loc off 1013Return a pointer to the mbuf containing the data located at 1014.Fa loc 1015bytes from the beginning of the 1016.Vt mbuf chain . 1017The corresponding offset into the mbuf will be stored in 1018.Fa *off . 1019.It Fn m_defrag m0 how 1020Defragment an mbuf chain, returning the shortest possible 1021chain of mbufs and clusters. 1022If allocation fails and this can not be completed, 1023.Dv NULL 1024will be returned and the original chain will be unchanged. 1025Upon success, the original chain will be freed and the new 1026chain will be returned. 1027.Fa how 1028should be either 1029.Dv M_WAITOK 1030or 1031.Dv M_NOWAIT , 1032depending on the caller's preference. 1033.Pp 1034This function is especially useful in network drivers, where 1035certain long mbuf chains must be shortened before being added 1036to TX descriptor lists. 1037.It Fn m_collapse m0 how maxfrags 1038Defragment an mbuf chain, returning a chain of at most 1039.Fa maxfrags 1040mbufs and clusters. 1041If allocation fails or the chain cannot be collapsed as requested, 1042.Dv NULL 1043will be returned, with the original chain possibly modified. 1044As with 1045.Fn m_defrag , 1046.Fa how 1047should be one of 1048.Dv M_WAITOK 1049or 1050.Dv M_NOWAIT . 1051.It Fn m_unshare m0 how 1052Create a version of the specified mbuf chain whose 1053contents can be safely modified without affecting other users. 1054If allocation fails and this operation can not be completed, 1055.Dv NULL 1056will be returned. 1057The original mbuf chain is always reclaimed and the reference 1058count of any shared mbuf clusters is decremented. 1059.Fa how 1060should be either 1061.Dv M_WAITOK 1062or 1063.Dv M_NOWAIT , 1064depending on the caller's preference. 1065As a side-effect of this process the returned 1066mbuf chain may be compacted. 1067.Pp 1068This function is especially useful in the transmit path of 1069network code, when data must be encrypted or otherwise 1070altered prior to transmission. 1071.El 1072.Sh HARDWARE-ASSISTED CHECKSUM CALCULATION 1073This section currently applies to TCP/IP only. 1074In order to save the host CPU resources, computing checksums is 1075offloaded to the network interface hardware if possible. 1076The 1077.Va m_pkthdr 1078member of the leading 1079.Vt mbuf 1080of a packet contains two fields used for that purpose, 1081.Vt int Va csum_flags 1082and 1083.Vt int Va csum_data . 1084The meaning of those fields depends on the direction a packet flows in, 1085and on whether the packet is fragmented. 1086Henceforth, 1087.Va csum_flags 1088or 1089.Va csum_data 1090of a packet 1091will denote the corresponding field of the 1092.Va m_pkthdr 1093member of the leading 1094.Vt mbuf 1095in the 1096.Vt mbuf chain 1097containing the packet. 1098.Pp 1099On output, checksum offloading is attempted after the outgoing 1100interface has been determined for a packet. 1101The interface-specific field 1102.Va ifnet.if_data.ifi_hwassist 1103(see 1104.Xr ifnet 9 ) 1105is consulted for the capabilities of the interface to assist in 1106computing checksums. 1107The 1108.Va csum_flags 1109field of the packet header is set to indicate which actions the interface 1110is supposed to perform on it. 1111The actions unsupported by the network interface are done in the 1112software prior to passing the packet down to the interface driver; 1113such actions will never be requested through 1114.Va csum_flags . 1115.Pp 1116The flags demanding a particular action from an interface are as follows: 1117.Bl -tag -width ".Dv CSUM_TCP" -offset indent 1118.It Dv CSUM_IP 1119The IP header checksum is to be computed and stored in the 1120corresponding field of the packet. 1121The hardware is expected to know the format of an IP header 1122to determine the offset of the IP checksum field. 1123.It Dv CSUM_TCP 1124The TCP checksum is to be computed. 1125(See below.) 1126.It Dv CSUM_UDP 1127The UDP checksum is to be computed. 1128(See below.) 1129.El 1130.Pp 1131Should a TCP or UDP checksum be offloaded to the hardware, 1132the field 1133.Va csum_data 1134will contain the byte offset of the checksum field relative to the 1135end of the IP header. 1136In this case, the checksum field will be initially 1137set by the TCP/IP module to the checksum of the pseudo header 1138defined by the TCP and UDP specifications. 1139.Pp 1140On input, an interface indicates the actions it has performed 1141on a packet by setting one or more of the following flags in 1142.Va csum_flags 1143associated with the packet: 1144.Bl -tag -width ".Dv CSUM_IP_CHECKED" -offset indent 1145.It Dv CSUM_IP_CHECKED 1146The IP header checksum has been computed. 1147.It Dv CSUM_IP_VALID 1148The IP header has a valid checksum. 1149This flag can appear only in combination with 1150.Dv CSUM_IP_CHECKED . 1151.It Dv CSUM_DATA_VALID 1152The checksum of the data portion of the IP packet has been computed 1153and stored in the field 1154.Va csum_data 1155in network byte order. 1156.It Dv CSUM_PSEUDO_HDR 1157Can be set only along with 1158.Dv CSUM_DATA_VALID 1159to indicate that the IP data checksum found in 1160.Va csum_data 1161allows for the pseudo header defined by the TCP and UDP specifications. 1162Otherwise the checksum of the pseudo header must be calculated by 1163the host CPU and added to 1164.Va csum_data 1165to obtain the final checksum to be used for TCP or UDP validation purposes. 1166.El 1167.Pp 1168If a particular network interface just indicates success or 1169failure of TCP or UDP checksum validation without returning 1170the exact value of the checksum to the host CPU, its driver can mark 1171.Dv CSUM_DATA_VALID 1172and 1173.Dv CSUM_PSEUDO_HDR 1174in 1175.Va csum_flags , 1176and set 1177.Va csum_data 1178to 1179.Li 0xFFFF 1180hexadecimal to indicate a valid checksum. 1181It is a peculiarity of the algorithm used that the Internet checksum 1182calculated over any valid packet will be 1183.Li 0xFFFF 1184as long as the original checksum field is included. 1185.Sh STRESS TESTING 1186When running a kernel compiled with the option 1187.Dv MBUF_STRESS_TEST , 1188the following 1189.Xr sysctl 8 Ns 1190-controlled options may be used to create 1191various failure/extreme cases for testing of network drivers 1192and other parts of the kernel that rely on 1193.Vt mbufs . 1194.Bl -tag -width ident 1195.It Va net.inet.ip.mbuf_frag_size 1196Causes 1197.Fn ip_output 1198to fragment outgoing 1199.Vt mbuf chains 1200into fragments of the specified size. 1201Setting this variable to 1 is an excellent way to 1202test the long 1203.Vt mbuf chain 1204handling ability of network drivers. 1205.It Va kern.ipc.m_defragrandomfailures 1206Causes the function 1207.Fn m_defrag 1208to randomly fail, returning 1209.Dv NULL . 1210Any piece of code which uses 1211.Fn m_defrag 1212should be tested with this feature. 1213.El 1214.Sh RETURN VALUES 1215See above. 1216.Sh SEE ALSO 1217.Xr ifnet 9 , 1218.Xr mbuf_tags 9 1219.Rs 1220.\" 4.4BSD SMM:18 1221.%A S. J. Leffler 1222.%A W. N. Joy 1223.%A R. S. Fabry 1224.%A M. J. Karels 1225.%T Networking Implementation Notes 1226.%B 4.4BSD System Manager's Manual (SMM) 1227.Re 1228.Sh HISTORY 1229.\" Please correct me if I'm wrong 1230.Vt Mbufs 1231appeared in an early version of 1232.Bx . 1233Besides being used for network packets, they were used 1234to store various dynamic structures, such as routing table 1235entries, interface addresses, protocol control blocks, etc. 1236In more recent 1237.Fx 1238use of 1239.Vt mbufs 1240is almost entirely limited to packet storage, with 1241.Xr uma 9 1242zones being used directly to store other network-related memory. 1243.Pp 1244Historically, the 1245.Vt mbuf 1246allocator has been a special-purpose memory allocator able to run in 1247interrupt contexts and allocating from a special kernel address space map. 1248As of 1249.Fx 5.3 , 1250the 1251.Vt mbuf 1252allocator is a wrapper around 1253.Xr uma 9 , 1254allowing caching of 1255.Vt mbufs , 1256clusters, and 1257.Vt mbuf 1258+ cluster pairs in per-CPU caches, as well as bringing other benefits of 1259slab allocation. 1260.Sh AUTHORS 1261The original 1262.Nm 1263manual page was written by 1264.An Yar Tikhiy . 1265The 1266.Xr uma 9 1267.Vt mbuf 1268allocator was written by 1269.An Bosko Milekic . 1270