1.\" $NetBSD: mbuf.9,v 1.8 1999/11/19 01:12:42 enami Exp $ 2.\" 3.\" Copyright (c) 1997 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This documentation is derived from text contributed to The NetBSD Foundation 7.\" by S.P.Zeidler (aka stargazer). 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd October 3, 1997 38.Dt MBUF 9 39.Os 40.Sh NAME 41.Nm mbuf , 42.Nm m_get , 43.Nm m_getclr , 44.Nm m_gethdr , 45.Nm m_devget , 46.Nm m_copym , 47.Nm m_copypacket , 48.Nm m_copydata , 49.Nm m_copyback , 50.Nm m_cat , 51.Nm m_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. 234The 235.Fa nowait 236parameter is a choice of 237.Dv M_WAIT / M_DONTWAIT 238from caller. 239.Dv M_WAIT 240means the call cannot fail, but may take forever. 241The 242.Fa type 243parameter is an mbuf type. 244.It Fn m_getclr "int nowait" "int type" 245Allocates an mbuf and initializes it to contain internal data, then 246zeros the data area. 247The 248.Fa nowait 249parameter is a choice of 250.Dv M_WAIT / M_DONTWAIT 251from caller. 252The 253.Fa type 254parameter is an mbuf type. 255.It Fn m_gethdr "int nowait" "int type" 256Allocates an mbuf and initializes it to contain a packet header and internal 257data. 258The 259.Fa nowait 260parameter is a choice of 261.Dv M_WAIT / M_DONTWAIT 262from caller. 263The 264.Fa type 265parameter is an mbuf type. 266.It Fn m_devget "char *buf" "int totlen" "int off0" "struct ifnet *ifp" "void (*copy) __P((const void *, void *, size_t))" 267Copies 268.Fa len 269bytes from device local memory into mbufs using copy routine 270.Fa copy . 271If parameter 272.Fa off 273is non-zero, the packet is supposed to be trailer-encapsulated and 274.Fa off 275bytes plus the type and length fields will be skipped before copying. 276Returns the top of the mbuf chain it created. 277.It Fn m_copym "struct mbuf *m" "int off0" "int len" "int wait" 278Creates a copy of an mbuf chain starting 279.Fa off0 280bytes from the beginning, continuing for 281.Fa len 282bytes. If the 283.Fa len 284requested is 285.Dv M_COPYALL , 286the complete mbuf chain will be copied. 287The 288.Fa wait 289parameter is a choice of 290.Dv M_WAIT / M_DONTWAIT 291from caller. 292.It Fn m_copypacket "struct mbuf *m" "int how" 293Copies an entire packet, including header (which must be present). 294This function is an optimization of the common case 295.Li m_copym(m, 0, Dv M_COPYALL, Fa how ) . 296.It Fn m_copydata "struct mbuf *m" "int off" "int len" "caddr_t cp" 297Copies 298.Fa len 299bytes data from mbuf chain 300.Fa m 301into the buffer 302.Fa cp , 303starting 304.Fa off 305bytes from the beginning. 306.It Fn m_copyback "struct mbuf *m0" "int off" "int len" "caddr_t cp" 307Copies 308.Fa len 309bytes data from buffer 310.Fa cp 311back into the mbuf chain 312.Fa m0 , 313starting 314.Fa off 315bytes from the beginning, extending the mbuf chain if necessary. 316.It Fn m_cat "struct mbuf *m" "struct mbuf *n" 317Concatenates mbuf chain 318.Fa n 319to 320.Fa m . 321Both chains must be of the same type; packet headers will 322.Em not 323be updated if present. 324.It Fn m_prepend "struct mbuf *m" "int len" "int how" 325Lesser-used path for 326.Fn M_PREPEND : 327allocates new mbuf 328.Fa m 329of size 330.Fa len 331to prepend to the chain, copying junk along. 332The 333.Fa how 334parameter is a choice of 335.Dv M_WAIT / M_DONTWAIT 336from caller. 337.It Fn m_pullup "struct mbuf *m" "int len" 338Rearranges an mbuf chain so that 339.Fa len 340bytes are contiguous 341and in the data area of an mbuf (so that 342.Fn mtod 343will work for a structure of size 344.Fa len ) . 345Returns the resulting 346mbuf chain on success, frees it and returns 347.Dv NULL 348on failure. 349If there is room, it will add up to 350.Dv max_protohdr 351- 352.Fa len 353extra bytes to the 354contiguous region to possibly avoid being called again. 355.It Fn m_split "struct mbuf *m0" "int len0" "int wait" 356Partitions an mbuf chain in two pieces, returning the tail, 357which is all but the first 358.Fa len0 359bytes. In case of failure, it returns 360.Dv NULL 361and attempts to 362restore the chain to its original state. 363.It Fn m_adj "struct mbuf *mp" "int req_len" 364Shaves off 365.Fa req_len 366bytes from head or tail of the (valid) data area. 367If 368.Fa req_len 369is greater than zero, front bytes are being shaved off, if it's smaller, 370from the back (and if it is zero, the mbuf will stay bearded). 371This function does not move data in any way, but is used to manipulate the 372data area pointer and data length variable of the mbuf in a non-clobbering 373way. 374.It Fn m_free "struct mbuf *m" 375Frees mbuf 376.Fa m . 377.It Fn m_freem "struct mbuf *m" 378Frees the mbuf chain beginning with 379.Fa m . 380This function contains the elementary sanity check for a 381.Dv NULL 382pointer. 383.It Fn mtod "struct mbuf *m" "datatype" 384Returns a pointer to the data contained in the specified mbuf 385.Fa m , 386type-casted to the specified data type 387.Fa datatype . 388Implemented as a macro. 389.It Fn mtocl "void *datapointer" 390Takes a 391.Fa datapointer 392within an mbuf cluster and returns the cluster index number of the mbuf 393owning the data. 394Avoid this; it may be deprecated in the future. 395Implemented as a macro. 396.It Fn cltom "u_long clusternum" 397Takes an mbuf cluster index number 398.Fa clusternum 399and returns a pointer to the beginning of the cluster. 400Avoid this; it may be deprecated in the future. 401Implemented as a macro. 402.It Fn MGET "struct mbuf *m" "int how" "int type" 403Allocates mbuf 404.Fa m 405and initializes it to contain internal data. 406See 407.Fn m_get . 408Implemented as a macro. 409.It Fn MGETHDR "struct mbuf *m" "int how" "int type" 410Allocates mbuf 411.Fa m 412and initializes it to contain a packet header. 413See 414.Fn m_gethdr . 415Implemented as a macro. 416.It Fn MEXTMALLOC "struct mbuf *m" "int len" "int how" 417Allocates external storage of size 418.Fa len 419for mbuf 420.Fa m . 421The 422.Fa how 423parameter is a choice of 424.Dv M_WAIT / M_DONTWAIT 425from caller. 426The flag 427.Dv M_EXT 428is set upon success. 429Implemented as a macro. 430.It Fn MEXTADD "struct mbuf *m" "caddr_t buf" "int type" "void (*free) __P((caddr_t, u_int, void *))" "void *arg" 431Adds pre-allocated external storage 432.Fa buf 433to a normal mbuf 434.Fa m ; 435the parameters 436.Fa type , 437.Fa free 438and 439.Fa arg 440describe the external storage. 441.Fa type 442describes the 443.Xr malloc 9 444type of the storage, 445.Fa free 446is a free routine (if not the usual one), and 447.Fa arg 448is a possible argument to the free routine. 449The flag 450.Dv M_EXT 451is set upon success. 452Implemented as a macro. 453.It Fn MCLGET "struct mbuf *m" "int how" 454Allocates and adds an mbuf cluster to a normal mbuf 455.Fa m . 456The 457.Fa how 458parameter is a choice of 459.Dv M_WAIT / M_DONTWAIT 460from caller. 461The flag 462.Dv M_EXT 463is set upon success. 464Implemented as a macro. 465.It Fn M_COPY_PKTHDR "struct mbuf *to" "struct mbuf *from" 466Copies the mbuf pkthdr from mbuf 467.Fa from 468to mbuf 469.Fa to . 470.Fa from 471must have the type flag 472.Dv M_PKTHDR 473set, and 474.Fa to 475must be empty. 476Implemented as a macro. 477.It Fn M_ALIGN "struct mbuf *m" "int len" 478Sets the data pointer of a newly allocated mbuf 479.Fa m 480to 481.Fa len 482bytes from the end of the mbuf data area, so that 483.Fa len 484bytes of data written to the mbuf 485.Fa m , 486starting at the data pointer, will be aligned to the end of the data area. 487Implemented as a macro. 488.It Fn MH_ALIGN "struct mbuf *m" "int len" 489Sets the data pointer of a newly allocated packetheader mbuf 490.Fa m 491to 492.Fa len 493bytes from the end of the mbuf data area, so that 494.Fa len 495bytes of data written to the mbuf 496.Fa m , 497starting at the data pointer, will be aligned to the end of the data area. 498Implemented as a macro. 499.It Fn M_LEADINGSPACE "struct mbuf *m" 500Returns the amount of space available before the current start of valid 501data in mbuf 502.Fa m . 503Implemented as a macro. 504.It Fn M_TRAILINGSPACE "struct mbuf *m" 505Returns the amount of space available after the current end of valid 506data in mbuf 507.Fa m . 508Implemented as a macro. 509.It Fn M_PREPEND "struct mbuf *m" "int plen" "int how" 510Prepends space of size 511.Fa plen 512to mbuf 513.Fa m . 514If a new mbuf must be allocated, 515.Fa how 516specifies whether to wait. 517If 518.Fa how 519is 520.Dv M_DONTWAIT 521and allocation fails, the original mbuf chain is freed and 522.Fa m 523is set to 524.Dv NULL . 525Implemented as a macro. 526.It Fn MCHTYPE "struct mbuf *m" "int type" 527Change mbuf 528.Fa m 529to new type 530.Fa type . 531Implemented as a macro. 532.It Fn MEXTREMOVE "struct mbuf *m" 533Removes external storage from mbuf 534.Fa m . 535The flag 536.Dv M_EXT 537is removed. 538Implemented as a macro. 539.It Fn MFREE "struct mbuf *m" "struct mbuf *n" 540Frees a single mbuf 541.Fa m 542and places the successor, if any, in mbuf 543.Fa n . 544Implemented as a macro. 545.El 546.\" .Sh ERRORS 547.Sh SEE ALSO 548.Xr /usr/share/doc/smm/18.net , 549.Xr netstat 1 , 550.Xr malloc 9 551.Sh AUTHORS 552The original mbuf data structures were designed by Rob Gurwitz 553when he did the initial TCP/IP implementation at BBN. 554.br 555Further extensions and enhancements were made by Bill Joy, Sam Leffler, 556and Mike Karels at CSRG. 557.br 558Current implementation of external storage by Matt Thomas 559.br 560<matt@3am-software.com> and Jason R. Thorpe <thorpej@NetBSD.ORG>. 561.Sh FILES 562The 563.Nm mbuf 564management functions are implemented within the file 565.Pa sys/kern/uipc_mbuf.c . 566Function prototypes, and the functions implemented as macros 567are located in 568.Pa sys/sys/mbuf.h . 569Both pathnames are relative to the root of the 570.Nx 571source tree, 572.Pa /usr/src . 573.\" .Sh HISTORY 574