- Uniformly use .In for header file references.
[dragonfly.git] / share / man / man9 / mbuf.9
CommitLineData
984263bc
MD
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: src/share/man/man9/mbuf.9,v 1.27.2.1 2003/05/28 13:53:18 yar Exp $
44cb301e 26.\" $DragonFly: src/share/man/man9/mbuf.9,v 1.4 2006/05/26 19:39:40 swildner Exp $
984263bc
MD
27.\"
28.Dd October 17, 2000
29.Dt MBUF 9
30.Os
31.\"
32.Sh NAME
33.Nm mbuf
34.Nd "memory management in the kernel IPC subsystem"
35.\"
36.Sh SYNOPSIS
37.In sys/param.h
38.In sys/systm.h
39.In sys/mbuf.h
40.\"
41.Ss Mbuf allocation macros
42.Fn MGET "struct mbuf *mbuf" "int how" "short type"
43.Fn MGETHDR "struct mbuf *mbuf" "int how" "short type"
44.Fn MCLGET "struct mbuf *mbuf" "int how"
45.Fn MFREE "struct mbuf *mbuf" "struct mbuf *successor"
46.\"
47.Ss Mbuf utility macros
48.Ft void *
49.Fn mtod "struct mbuf *mbuf" "type"
50.Ft int
51.Fn M_COPY_PKTHDR "struct mbuf *to" "struct mbuf *from"
52.Fn M_ALIGN "struct mbuf *mbuf" "u_int len"
53.Fn MH_ALIGN "struct mbuf *mbuf" "u_int len"
54.Ft int
55.Fn M_LEADINGSPACE "struct mbuf *mbuf"
56.Ft int
57.Fn M_TRAILINGSPACE "struct mbuf *mbuf"
58.Fn M_PREPEND "struct mbuf *mbuf" "int len" "int how"
59.Fn MCHTYPE "struct mbuf *mbuf" "u_int type"
60.\"
61.Ss Mbuf allocation functions
62.Ft struct mbuf *
63.Fn m_get "int how" "int type"
64.Ft struct mbuf *
65.Fn m_getm "struct mbuf *orig" "int len" "int how" "int type"
66.Ft struct mbuf *
67.Fn m_getclr "int how" "int type"
68.Ft struct mbuf *
69.Fn m_gethdr "int how" "int type"
70.Ft struct mbuf *
71.Fn m_free "struct mbuf *mbuf"
72.Ft void
73.Fn m_freem "struct mbuf *mbuf"
74.\"
75.Ss Mbuf utility functions
76.Ft void
77.Fn m_adj "struct mbuf *mbuf" "int len"
78.Ft struct mbuf *
79.Fn m_prepend "struct mbuf *mbuf" "int len" "int how"
80.Ft struct mbuf *
81.Fn m_pullup "struct mbuf *mbuf" "int len"
82.Ft struct mbuf *
83.Fn m_copym "struct mbuf *mbuf" "int offset" "int len" "int how"
84.Ft struct mbuf *
85.Fn m_copypacket "struct mbuf *mbuf" "int how"
86.Ft struct mbuf *
87.Fn m_dup "struct mbuf *mbuf" "int how"
88.Ft void
89.Fn m_copydata "const struct mbuf *mbuf" "int offset" "int len" "caddr_t buf"
90.Ft void
91.Fn m_copyback "struct mbuf *mbuf" "int offset" "int len" "caddr_t buf"
92.Ft struct mbuf *
93.Fo m_devget
94.Fa "char *buf"
95.Fa "int len"
96.Fa "int offset"
97.Fa "struct ifnet *ifp"
98.Fa "void (*copy)(char *from, caddr_t to, u_int len)"
99.Fc
100.Ft void
101.Fn m_cat "struct mbuf *m" "struct mbuf *n"
102.Ft struct mbuf *
103.Fn m_split "struct mbuf *mbuf" "int len" "int how"
104.\"
105.Sh DESCRIPTION
106An mbuf is a basic unit of memory management in the kernel IPC subsystem.
107Network packets and socket buffers are stored in mbufs.
108A network packet may span multiple mbufs arranged into a chain
109(linked list),
110which allows adding or trimming
111network headers with little overhead.
112.Pp
113While a developer should not bother with mbuf internals without serious
114reason in order to avoid incompatibilities with future changes, it
115is useful to understand the mbuf's general structure.
116.Pp
117An mbuf consists of a variable-sized header and a small internal
118buffer for data.
119The mbuf's total size,
120.Dv MSIZE ,
121is a machine-dependent constant defined in
44cb301e 122.In machine/param.h .
984263bc
MD
123The mbuf header includes:
124.Pp
125.Bl -tag -width "m_nextpkt" -compact -offset indent
126.It Fa m_next
127a pointer to the next buffer in the chain
128.It Fa m_nextpkt
129a pointer to the next chain in the queue
130.It Fa m_data
131a pointer to the data
132.It Fa m_len
133the length of the data
134.It Fa m_type
135the type of data
136.It Fa m_flags
137the mbuf flags
138.El
139.Pp
140The mbuf flag bits are defined as follows:
141.Bd -literal
142/* mbuf flags */
143#define M_EXT 0x0001 /* has associated external storage */
144#define M_PKTHDR 0x0002 /* start of record */
145#define M_EOR 0x0004 /* end of record */
146#define M_PROTO1 0x0010 /* protocol-specific */
147#define M_PROTO2 0x0020 /* protocol-specific */
148#define M_PROTO3 0x0040 /* protocol-specific */
149#define M_PROTO4 0x0080 /* protocol-specific */
150#define M_PROTO5 0x0100 /* protocol-specific */
151
152/* mbuf pkthdr flags, also in m_flags */
153#define M_BCAST 0x0200 /* send/received as link-level broadcast */
154#define M_MCAST 0x0400 /* send/received as link-level multicast */
155#define M_FRAG 0x0800 /* packet is fragment of larger packet */
156#define M_FIRSTFRAG 0x1000 /* packet is first fragment */
157#define M_LASTFRAG 0x2000 /* packet is last fragment */
158.Ed
159.Pp
160The available mbuf types are defined as follows:
161.Bd -literal
162/* mbuf types */
163#define MT_FREE 0 /* should be on free list */
164#define MT_DATA 1 /* dynamic (data) allocation */
165#define MT_HEADER 2 /* packet header */
166#define MT_SONAME 8 /* socket name */
167#define MT_FTABLE 11 /* fragment reassembly header */
168#define MT_CONTROL 14 /* extra-data protocol message */
169#define MT_OOBDATA 15 /* expedited data */
170.Ed
171.Pp
172If the
173.Dv M_PKTHDR
174flag is set, a
175.Li struct pkthdr m_pkthdr
176is added to the mbuf header.
177It contains a pointer to the interface
178the packet has been received from
179.Pq Fa struct ifnet *rcvif ,
180and the total packet length
181.Pq Fa int len .
182.Pp
183If small enough, data is stored in the mbuf's internal data buffer.
184If the data is sufficiently large, another mbuf may be added to the chain,
185or external storage may be associated with the mbuf.
186.Dv MHLEN
187bytes of data can fit into an mbuf with the
188.Dv M_PKTHDR
189flag set,
190.Dv MLEN
191bytes can otherwise.
192.Pp
193If external storage is being associated with an mbuf, the
194.Dv m_ext
195header is added at the cost of losing the internal data buffer.
196It includes a pointer to external storage, the size of the storage,
197a pointer to a function used for freeing the storage,
198a pointer to an optional argument that can be passed to the function,
199and a pointer to a reference counter.
200An mbuf using external storage has the
201.Dv M_EXT
202flag set.
203.Pp
204The system supplies a default type of external storage buffer called an
205.Dq mbuf cluster .
206Mbuf clusters can be allocated and configured with the use of the
207.Dv MCLGET
208macro.
209Each cluster is
210.Dv MCLBYTES
211in size, where MCLBYTES is a machine-dependent constant.
212The system defines an advisory macro
213.Dv MINCLSIZE ,
214which is the smallest amount of data to put into a cluster.
215It's equal to the sum of
216.Dv MLEN
217and
218.Dv MHLEN .
219It is typically preferable to store data into an mbuf's data region, if size
220permits, as opposed to allocating a separate mbuf cluster to hold the same
221data.
222.\"
223.Ss Macros and Functions
224There are numerous predefined macros and functions that provide the
225developer with common utilities.
226.\"
227.Bl -ohang -offset indent
228.It Fn mtod mbuf type
229Convert an mbuf pointer to a data pointer.
230The macro expands to the data pointer cast to the pointer of the specified type.
231.Sy Note :
232It is advisable to ensure that there is enough contiguous data in the mbuf.
233See
234.Fn m_pullup
235for details.
236.It Fn MGET mbuf how type
237Allocate an mbuf and initialize it to contain internal data.
238.Fa mbuf
239will point to the allocated mbuf on success, or be set to
240.Dv NULL
241on failure.
242The
243.Fa how
244argument is to be set to
99947902 245.Dv MB_WAIT
984263bc 246or
99947902 247.Dv MB_DONTWAIT .
984263bc
MD
248It specifies whether the caller is willing to block if necessary.
249If
250.Fa how
251is set to
99947902 252.Dv MB_WAIT ,
984263bc
MD
253a failed allocation will result in the caller being put
254to sleep for a designated
255kern.ipc.mbuf_wait
256.Xr ( sysctl 8
257tunable)
258number of ticks.
259A number of other mbuf-related
260functions and macros have the same argument because they may
261at some point need to allocate new mbufs.
262.Pp
263Programmers should be careful not to confuse the mbuf allocation flag
99947902 264.Dv MB_DONTWAIT
984263bc
MD
265with the
266.Xr malloc 9
267allocation flag,
268.Dv M_NOWAIT .
269They are not the same.
270.It Fn MGETHDR mbuf how type
271Allocate an mbuf and initialize it to contain a packet header
272and internal data.
273See
274.Fn MGET
275for details.
276.It Fn MCLGET mbuf how
277Allocate and attach an mbuf cluster to an mbuf.
278If the macro fails, the
279.Dv M_EXT
280flag won't be set in the mbuf.
281.It Fn M_PREPEND mbuf len how
282This macro operates on an mbuf chain.
283It is an optimized wrapper for
284.Fn m_prepend
285that can make use of possible empty space before data
286(e.g. left after trimming of a link-layer header).
287The new chain pointer or
288.Dv NULL
289is in
290.Fa mbuf
291after the call.
292.El
293.Pp
294The functions are:
295.Bl -ohang -offset indent
296.It Fn m_get how type
297A function version of
298.Fn MGET
299for non-critical paths.
300.It Fn m_getm orig len how type
301Allocate
302.Fa len
303bytes worth of mbufs and mbuf clusters if necessary and append the resulting
304allocated chain to the
305.Fa orig
306mbuf chain, if it is
307.No non- Ns Dv NULL .
308If the allocation fails at any point,
309free whatever was allocated and return
310.Dv NULL .
311If
312.Fa orig
313is
314.No non- Ns Dv NULL ,
315it will not be freed.
316It is possible to use
317.Fn m_getm
318to either append
319.Fa len
320bytes to an existing mbuf or mbuf chain
321(for example, one which may be sitting in a pre-allocated ring)
322or to simply perform an all-or-nothing mbuf and mbuf cluster allocation.
323.It Fn m_gethdr how type
324A function version of
325.Fn MGETHDR
326for non-critical paths.
327.It Fn m_getclr how type
328Allocate an mbuf and zero out the data region.
329.El
330.Pp
331The functions below operate on mbuf chains.
332.Bl -ohang -offset indent
333.It Fn m_freem mbuf
334Free an entire mbuf chain, including any external
335storage.
336.\"
337.It Fn m_adj mbuf len
338Trim
339.Fa len
340bytes from the head of an mbuf chain if
341.Fa len
342is positive, from the tail otherwise.
343.\"
344.It Fn m_prepend mbuf len how
345Allocate a new mbuf and prepend it to the chain, handle
346.Dv M_PKTHDR
347properly.
348.Sy Note :
349It doesn't allocate any clusters, so
350.Fa len
351must be less than
352.Dv MLEN
353or
354.Dv MHLEN ,
355depending on the
356.Dv M_PKTHDR
357flag setting.
358.\"
359.It Fn m_pullup mbuf len
360Arrange that the first
361.Fa len
362bytes of an mbuf chain are contiguous and lay in the data area of
363.Fa mbuf ,
364so they are accessible with
365.Fn mtod mbuf type .
366Return the new chain on success,
367.Dv NULL
368on failure
369(the chain is freed in this case).
370.Sy Note :
371It doesn't allocate any clusters, so
372.Fa len
373must be less than
374.Dv MHLEN .
375.\"
376.It Fn m_copym mbuf offset len how
377Make a copy of an mbuf chain starting
378.Fa offset
379bytes from the beginning, continuing for
380.Fa len
381bytes.
382If
383.Fa len
384is
385.Dv M_COPYALL ,
386copy to the end of the mbuf chain.
387.Sy Note :
388The copy is read-only, because clusters are not
389copied, only their reference counts are incremented.
390.\"
391.It Fn m_copypacket mbuf how
392Copy an entire packet including header, which must be present.
393This is an optimized version of the common case
394.Fn m_copym mbuf 0 M_COPYALL how .
395.Sy Note :
396the copy is read-only, because clusters are not
397copied, only their reference counts are incremented.
398.\"
399.It Fn m_dup mbuf how
400Copy a packet header mbuf chain into a completely new chain, including
401copying any mbuf clusters.
402Use this instead of
403.Fn m_copypacket
404when you need a writable copy of an mbuf chain.
405.\"
406.It Fn m_copydata mbuf offset len buf
407Copy data from an mbuf chain starting
408.Fa off
409bytes from the beginning, continuing for
410.Fa len
411bytes, into the indicated buffer
412.Fa buf .
413.\"
414.It Fn m_copyback mbuf offset len buf
415Copy
416.Fa len
417bytes from the buffer
418.Fa buf
419back into the indicated mbuf chain,
420starting at
421.Fa offset
422bytes from the beginning of the chain, extending the mbuf chain if necessary.
423.Sy Note :
424It doesn't allocate any clusters, just adds mbufs to the chain.
425It's safe to set
426.Fa offset
427beyond the current chain end: zeroed mbufs will be allocated to fill the
428space.
429.\"
430.It Fn m_devget buf len offset ifp copy
431Copy data from a device local memory pointed to by
432.Fa buf
433to an mbuf chain.
434The copy is done using a specified copy routine
435.Fa copy ,
436or
437.Fn bcopy
438if
439.Fa copy
440is
441.Dv NULL .
442.\"
443.It Fn m_cat m n
444Concatenate
445.Fa n
446to
447.Fa m .
448Both chains must be of the same type.
449.Fa N
450is still valid after the function returned.
451.Sy Note :
452It does not handle
453.Dv M_PKTHDR
454and friends.
455.\"
456.It Fn m_split mbuf len how
457Partition an mbuf chain in two pieces, returning the tail:
458all but the first
459.Fa len
460bytes.
461In case of failure, it returns
462.Dv NULL
463and attempts to restore the chain to its original state.
464.El
465.Sh RETURN VALUES
466See above.
467.Sh HISTORY
468.\" Please correct me if I'm wrong
469Mbufs appeared in an early version of
470.Bx .
471Besides for being used for network packets, they were used
472to store various dynamic structures, such as routing table
473entries, interface addresses, protocol control blocks, etc.
474.Sh AUTHORS
475The original
476.Nm
477man page was written by Yar Tikhiy.