mbuf.9 (ea26d587291046c59102b34124187e7f602ee07d) mbuf.9 (de06f907d1a4af71fded2aa9252c60fcd5d6995b)
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.

--- 10 unchanged lines hidden (view full) ---

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.\"
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.

--- 10 unchanged lines hidden (view full) ---

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