1.\" $NetBSD: mbuf.9,v 1.3 1997/11/27 06:18:01 mikel 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 Oct 3, 1997 38.Dt MBUF 9 39.Os NetBSD 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_prepend , 52.Nm m_pullup , 53.Nm m_split , 54.Nm m_adj , 55.Nm m_free , 56.Nm m_freem , 57.Nm mtod , 58.Nm mtocl , 59.Nm cltom , 60.Nm MGET , 61.Nm MGETHDR , 62.Nm MEXTMALLOC , 63.Nm MEXTADD , 64.Nm MCLGET , 65.Nm M_COPY_PKTHDR , 66.Nm M_ALIGN , 67.Nm MH_ALIGN , 68.Nm M_LEADINGSPACE , 69.Nm M_TRAILINGSPACE , 70.Nm M_PREPEND , 71.Nm MCHTYPE , 72.Nm MEXTREMOVE , 73.Nm MFREE , 74.Nd functions and macros for managing memory used by networking code 75.Sh SYNOPSIS 76.Fd #include <sys/mbuf.h> 77.Ft struct mbuf * 78.Fn m_get "int nowait" "int type" 79.Ft struct mbuf * 80.Fn m_getclr "int nowait" "int type" 81.Ft struct mbuf * 82.Fn m_gethdr "int nowait" "int type" 83.Ft struct mbuf * 84.Fn m_devget "char *buf" "int totlen" "int off0" "struct ifnet *ifp" "void (*copy) __P((const void *, void *, size_t))" 85.Ft struct mbuf * 86.Fn m_copym "struct mbuf *m" "int off0" "int len" "int wait" 87.Ft struct mbuf * 88.Fn m_copypacket "struct mbuf *m" "int how" 89.Ft void 90.Fn m_copydata "struct mbuf *m" "int off" "int len" "caddr_t cp" 91.Ft void 92.Fn m_copyback "struct mbuf *m0" "int off" "int len" "caddr_t cp" 93.Ft void 94.Fn m_cat "struct mbuf *m" "struct mbuf *n" 95.Ft struct mbuf * 96.Fn m_prepend "struct mbuf *m" "int len" "int how" 97.Ft struct mbuf * 98.Fn m_pullup "struct mbuf *n" "int len" 99.Ft struct mbuf * 100.Fn m_split "struct mbuf *m0" "int len0" "int wait" 101.Ft void 102.Fn m_adj "struct mbuf *mp" "int req_len" 103.Ft struct mbuf * 104.Fn m_free "struct mbuf *m" 105.Ft void 106.Fn m_freem "struct mbuf *m" 107.Ft int 108.Fn mtod "struct mbuf *m" "datatype" 109.Ft u_long 110.Fn mtocl "void *datapointer" 111.Ft caddr_t 112.Fn cltom "u_long clusternum" 113.Ft void 114.Fn MGET "struct mbuf *m" "int how" "int type" 115.Ft void 116.Fn MGETHDR "struct mbuf *m" "int how" "int type" 117.Ft void 118.Fn MEXTMALLOC "struct mbuf *m" "int len" "int how" 119.Ft void 120.Fn MEXTADD "struct mbuf *m" "caddr_t buf" "int type" "void (*free) __P((caddr_t, u_int, void *))" "void *arg" 121.Ft void 122.Fn MCLGET "struct mbuf *m" "int how" 123.Ft void 124.Fn M_COPY_PKTHDR "struct mbuf *to" "struct mbuf *from" 125.Ft void 126.Fn M_ALIGN "struct mbuf *m" "int len" 127.Ft void 128.Fn MH_ALIGN "struct mbuf *m" "int len" 129.Ft int 130.Fn M_LEADINGSPACE "struct mbuf *m" 131.Ft int 132.Fn M_TRAILINGSPACE "struct mbuf *m" 133.Ft void 134.Fn M_PREPEND "struct mbuf *m" "int plen" "int how" 135.Ft void 136.Fn MCHTYPE "struct mbuf *m" "int type" 137.Ft void 138.Fn MEXTREMOVE "struct mbuf *m" 139.Ft void 140.Fn MFREE "struct mbuf *m" "struct mbuf *n" 141.Sh DESCRIPTION 142The 143.Nm 144functions and macros provide an easy and consistent way to handle 145a networking stack's memory management needs. 146An 147.Nm mbuf 148consists of a header and a data area. 149It is of a fixed size, 150.Dv MSIZE 151.Pq defined in Aq Pa machine/param.h , 152which includes overhead. 153The header contains a pointer to the next 154.Nm mbuf 155in the 156.Nm mbuf chain , 157a pointer to the next 158.Nm mbuf chain , 159a pointer to the data area, the amount of data in this mbuf, its type 160and a 161.Dv flags 162field. 163.Pp 164The 165.Dv type 166variable can signify: 167.Bl -tag -compact -offset indent -width "XXXXXXXXXXX" 168.It Dv MT_FREE 169the mbuf should be on the ``free'' list 170.It Dv MT_DATA 171data was dynamically allocated 172.It Dv MT_HEADER 173data is a packet header 174.It Dv MT_SONAME 175data is a socket name 176.It Dv MT_SOOPTS 177data is socket options 178.It Dv MT_FTABLE 179data is the fragment reassembly header 180.It Dv MT_CONTROL 181mbuf contains ancillary \&(protocol control\&) data 182.It Dv MT_OOBDATA 183mbuf contains out-of-band data. 184.El 185.Pp 186The 187.Dv flags 188variable contains information describing the 189.Nm mbuf , 190notably: 191.Bl -tag -compact -offset indent -width "XXXXXXXXXXX" 192.It Dv M_EXT 193has external storage 194.It Dv M_PKTHDR 195is start of record 196.It Dv M_EOR 197is end of record 198.It Dv M_CLUSTER 199external storage is a cluster. 200.El 201.Pp 202If an 203.Nm mbuf 204designates the start of a record 205.Pq Dv M_PKTHDR , 206its 207.Dv flags 208field may contain additional information describing the content of 209the record: 210.Bl -tag -compact -offset indent -width "XXXXXXXXXXX" 211.It Dv M_BCAST 212sent/received as link-level broadcast 213.It Dv M_MCAST 214sent/received as link-level multicast 215.It Dv M_LINK0 , M_LINK1, MLINK2 216three link-level specific flags. 217.El 218.Pp 219An 220.Nm mbuf 221may add a single 222.Nm mbuf cluster 223of 224.Dv MCLBYTES 225bytes 226.Pq also defined in Aq Pa machine/param.h , 227which has no additional overhead 228and is used instead of the internal data area; this is done when at least 229.Dv MINCLSIZE 230bytes of data must be stored. 231.Bl -tag -width compact 232.It Fn m_get "int nowait" "int type" 233Allocates an mbuf and initializes it to contain internal data. The 234.Fa nowait 235parameter is a choice of 236.Dv M_WAIT / M_DONTWAIT 237from caller. 238.Dv M_WAIT 239means the call cannot fail, but may take forever. The 240.Fa type 241parameter is an mbuf type. 242.It Fn m_getclr "int nowait" "int type" 243Allocates an mbuf and initializes it to contain internal data, then 244zeros the data area. The 245.Fa nowait 246parameter is a choice of 247.Dv M_WAIT / M_DONTWAIT 248from caller. The 249.Fa type 250parameter is an mbuf type. 251.It Fn m_gethdr "int nowait" "int type" 252Allocates an mbuf and initializes it to contain a packet header and internal 253data. The 254.Fa nowait 255parameter is a choice of 256.Dv M_WAIT / M_DONTWAIT 257from caller. The 258.Fa type 259parameter is an mbuf type. 260.It Fn m_devget "char *buf" "int totlen" "int off0" "struct ifnet *ifp" "void (*copy) __P((const void *, void *, size_t))" 261Copies 262.Fa len 263bytes from device local memory into mbufs using copy routine 264.Fa copy . 265If parameter 266.Fa off 267is non-zero, the packet is supposed to be trailer-encapsulated and 268.Fa off 269bytes plus the type and length fields will be skipped before copying. 270Returns the top of the mbuf chain it created. 271.It Fn m_copym "struct mbuf *m" "int off0" "int len" "int wait" 272Creates a copy of an mbuf chain starting 273.Fa off0 274bytes from the beginning, continuing for 275.Fa len 276bytes. If the 277.Fa len 278requested is 279.Dv M_COPYALL , 280the complete mbuf chain will be copied. 281The 282.Fa wait 283parameter is a choice of 284.Dv M_WAIT / M_DONTWAIT 285from caller. 286.It Fn m_copypacket "struct mbuf *m" "int how" 287Copies an entire packet, including header (which must be present). 288This function is an optimization of the common case 289.Li m_copym(m, 0, Dv M_COPYALL, Fa how ) . 290.It Fn m_copydata "struct mbuf *m" "int off" "int len" "caddr_t cp" 291Copies 292.Fa len 293bytes data from mbuf chain 294.Fa m 295into the buffer 296.Fa cp , 297starting 298.Fa off 299bytes from the beginning. 300.It Fn m_copyback "struct mbuf *m0" "int off" "int len" "caddr_t cp" 301Copies 302.Fa len 303bytes data from buffer 304.Fa cp 305back into the mbuf chain 306.Fa m0 , 307starting 308.Fa off 309bytes from the beginning, extending the mbuf chain if necessary. 310.It Fn m_cat "struct mbuf *m" "struct mbuf *n" 311Concatenates mbuf chain 312.Fa n 313to 314.Fa m . 315Both chains must be of the same type; packet headers will 316.Em not 317be updated if present. 318.It Fn m_prepend "struct mbuf *m" "int len" "int how" 319Lesser-used path for 320.Fn M_PREPEND : 321allocates new mbuf 322.Fa m 323of size 324.Fa len 325to prepend to the chain, copying junk along. The 326.Fa how 327parameter is a choice of 328.Dv M_WAIT / M_DONTWAIT 329from caller. 330.It Fn m_pullup "struct mbuf *m" "int len" 331Rearranges an mbuf chain so that 332.Fa len 333bytes are contiguous 334and in the data area of an mbuf (so that 335.Fn mtod 336will work for a structure of size 337.Fa len ) . 338Returns the resulting 339mbuf chain on success, frees it and returns 340.Dv NULL 341on failure. 342If there is room, it will add up to 343.Dv max_protohdr 344- 345.Fa len 346extra bytes to the 347contiguous region to possibly avoid being called again. 348.It Fn m_split "struct mbuf *m0" "int len0" "int wait" 349Partitions an mbuf chain in two pieces, returning the tail, 350which is all but the first 351.Fa len0 352bytes. In case of failure, it returns 353.Dv NULL 354and attempts to 355restore the chain to its original state. 356.It Fn m_adj "struct mbuf *mp" "int req_len" 357Shaves off 358.Fa req_len 359bytes from head or tail of the (valid) data area. If 360.Fa req_len 361is greater than zero, front bytes are being shaved off, if it's smaller, 362from the back (and if it is zero, the mbuf will stay bearded). 363This function does not move data in any way, but is used to manipulate the 364data area pointer and data length variable of the mbuf in a non-clobbering 365way. 366.It Fn m_free "struct mbuf *m" 367Frees mbuf 368.Fa m . 369.It Fn m_freem "struct mbuf *m" 370Frees the mbuf chain beginning with 371.Fa m . 372This function contains the elementary sanity check for a 373.Dv NULL 374pointer. 375.It Fn mtod "struct mbuf *m" "datatype" 376Returns a pointer to the data contained in the specified mbuf 377.Fa m , 378type-casted to the specified data type 379.Fa datatype . 380Implemented as a macro. 381.It Fn mtocl "void *datapointer" 382Takes a 383.Fa datapointer 384within an mbuf cluster and returns the cluster index number of the mbuf 385owning the data. 386Avoid this; it may be deprecated in the future. 387Implemented as a macro. 388.It Fn cltom "u_long clusternum" 389Takes an mbuf cluster index number 390.Fa clusternum 391and returns a pointer to the beginning of the cluster. 392Avoid this; it may be deprecated in the future. 393Implemented as a macro. 394.It Fn MGET "struct mbuf *m" "int how" "int type" 395Allocates mbuf 396.Fa m 397and initializes it to contain internal data. See 398.Fn m_get . 399Implemented as a macro. 400.It Fn MGETHDR "struct mbuf *m" "int how" "int type" 401Allocates mbuf 402.Fa m 403and initializes it to contain a packet header. See 404.Fn m_gethdr . 405Implemented as a macro. 406.It Fn MEXTMALLOC "struct mbuf *m" "int len" "int how" 407Allocates external storage of size 408.Fa len 409for mbuf 410.Fa m . 411The 412.Fa how 413parameter is a choice of 414.Dv M_WAIT / M_DONTWAIT 415from caller. 416The flag 417.Dv M_EXT 418is set upon success. 419Implemented as a macro. 420.It Fn MEXTADD "struct mbuf *m" "caddr_t buf" "int type" "void (*free) __P((caddr_t, u_int, void *))" "void *arg" 421Adds pre-allocated external storage 422.Fa buf 423to a normal mbuf 424.Fa m ; 425the parameters 426.Fa type , 427.Fa free 428and 429.Fa arg 430describe the external storage. 431.Fa type 432describes the 433.Xr malloc 9 434type of the storage, 435.Fa free 436is a free routine (if not the usual one), and 437.Fa arg 438is a possible argument to the free routine. 439The flag 440.Dv M_EXT 441is set upon success. 442Implemented as a macro. 443.It Fn MCLGET "struct mbuf *m" "int how" 444Allocates and adds an mbuf cluster to a normal mbuf 445.Fa m . 446The 447.Fa how 448parameter is a choice of 449.Dv M_WAIT / M_DONTWAIT 450from caller. 451The flag 452.Dv M_EXT 453is set upon success. 454Implemented as a macro. 455.It Fn M_COPY_PKTHDR "struct mbuf *to" "struct mbuf *from" 456Copies the mbuf pkthdr from mbuf 457.Fa from 458to mbuf 459.Fa to . 460.Fa from 461must have the type flag 462.Dv M_PKTHDR 463set, and 464.Fa to 465must be empty. 466Implemented as a macro. 467.It Fn M_ALIGN "struct mbuf *m" "int len" 468Sets the data pointer of a newly allocated mbuf 469.Fa m 470to 471.Fa len 472bytes from the end of the mbuf data area, so that 473.Fa len 474bytes of data written to the mbuf 475.Fa m , 476starting at the data pointer, will be aligned to the end of the data area. 477Implemented as a macro. 478.It Fn MH_ALIGN "struct mbuf *m" "int len" 479Sets the data pointer of a newly allocated packetheader mbuf 480.Fa m 481to 482.Fa len 483bytes from the end of the mbuf data area, so that 484.Fa len 485bytes of data written to the mbuf 486.Fa m , 487starting at the data pointer, will be aligned to the end of the data area. 488Implemented as a macro. 489.It Fn M_LEADINGSPACE "struct mbuf *m" 490Returns the amount of space available before the current start of valid 491data in mbuf 492.Fa m . 493Implemented as a macro. 494.It Fn M_TRAILINGSPACE "struct mbuf *m" 495Returns the amount of space available after the current end of valid 496data in mbuf 497.Fa m . 498Implemented as a macro. 499.It Fn M_PREPEND "struct mbuf *m" "int plen" "int how" 500Prepends space of size 501.Fa plen 502to mbuf 503.Fa m . 504If a new mbuf must be allocated, 505.Fa how 506specifies whether to wait. If 507.Fa how 508is 509.Dv M_DONTWAIT 510and allocation fails, the original mbuf chain is freed and 511.Fa m 512is set to 513.Dv NULL . 514Implemented as a macro. 515.It Fn MCHTYPE "struct mbuf *m" "int type" 516Change mbuf 517.Fa m 518to new type 519.Fa type . 520Implemented as a macro. 521.It Fn MEXTREMOVE "struct mbuf *m" 522Removes external storage from mbuf 523.Fa m . 524The flag 525.Dv M_EXT 526is removed. 527Implemented as a macro. 528.It Fn MFREE "struct mbuf *m" "struct mbuf *n" 529Frees a single mbuf 530.Fa m 531and places the successor, if any, in mbuf 532.Fa n . 533Implemented as a macro. 534.El 535.\" .Sh ERRORS 536.Sh SEE ALSO 537.Xr /usr/share/doc/smm/18.net , 538.Xr netstat 1 , 539.Xr malloc 9 . 540.Sh AUTHORS 541The original mbuf data structures were designed by Rob Gurwitz 542when he did the initial TCP/IP implementation at BBN. 543.br 544Further extensions and enhancements were made by Bill Joy, Sam Leffler, 545and Mike Karels at CSRG. 546.br 547Current implementation of external storage by Matt Thomas 548.br 549<matt@3am-software.com> and Jason R. Thorpe <thorpej@NetBSD.ORG>. 550.Sh FILES 551The 552.Nm mbuf 553management functions are implemented within the file 554.Pa sys/kern/uipc_mbuf.c . 555Function prototypes, and the functions implemented as macros 556are located in 557.Pa sys/sys/mbuf.h . 558Both pathnames are relative to the root of the 559.Nx 560source tree, 561.Pa /usr/src . 562.\" .Sh HISTORY 563