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