MBUF(9) | Kernel Developer's Manual | MBUF(9) |
mbuf
, m_get
,
m_gethdr
, m_devget
,
m_copym
, m_copypacket
,
m_copydata
, m_copyback
,
m_copyback_cow
, m_cat
,
m_dup
, m_makewritable
,
m_pulldown
, m_pullup
,
m_copyup
, m_split
,
m_adj
, m_apply
,
m_free
, m_freem
,
mtod
, MGET
,
MGETHDR
, MEXTMALLOC
,
MEXTADD
, MCLGET
,
m_copy_pkthdr
, m_move_pkthdr
,
m_remove_pkthdr
, m_align
,
M_LEADINGSPACE
,
M_TRAILINGSPACE
, M_PREPEND
,
MCHTYPE
—
#include <sys/mbuf.h>
struct mbuf *
m_get
(int
how, int type);
struct mbuf *
m_gethdr
(int
how, int type);
struct mbuf *
m_devget
(char
*buf, int totlen,
int off,
struct ifnet *ifp);
struct mbuf *
m_copym
(struct
mbuf *m, int off,
int len,
int wait);
struct mbuf *
m_copypacket
(struct
mbuf *m, int
how);
void
m_copydata
(struct
mbuf *m, int off,
int len,
void *cp);
void
m_copyback
(struct
mbuf *m0, int off,
int len,
void *cp);
struct mbuf *
m_copyback_cow
(struct
mbuf *m0, int off,
int len,
void *cp,
int how);
int
m_makewritable
(struct
mbuf **mp, int off,
int len,
int how);
void
m_cat
(struct
mbuf *m, struct mbuf
*n);
struct mbuf *
m_dup
(struct
mbuf *m, int off,
int len,
int wait);
struct mbuf *
m_pulldown
(struct
mbuf *m, int off,
int len,
int *offp);
struct mbuf *
m_pullup
(struct
mbuf *n, int
len);
struct mbuf *
m_copyup
(struct
mbuf *m, int len,
int dstoff);
struct mbuf *
m_split
(struct
mbuf *m0, int len,
int wait);
void
m_adj
(struct
mbuf *mp, int
req_len);
int
m_apply
(struct
mbuf *m, int off,
int len,
int *f(void *, void *, unsigned
int), void
*arg);
struct mbuf *
m_free
(struct
mbuf *m);
void
m_freem
(struct
mbuf *m);
datatype
mtod
(struct
mbuf *m,
datatype);
void
MGET
(struct
mbuf *m, int how,
int type);
void
MGETHDR
(struct
mbuf *m, int how,
int type);
void
MEXTMALLOC
(struct
mbuf *m, int len,
int how);
void
MEXTADD
(struct
mbuf *m, void *buf,
int size,
int type,
void (*free)(struct mbuf *,
void *, size_t, void *),
void *arg);
void
MCLGET
(struct
mbuf *m, int
how);
void
m_copy_pkthdr
(struct
mbuf *to, struct mbuf
*from);
void
m_move_pkthdr
(struct
mbuf *to, struct mbuf
*from);
void
m_remove_pkthdr
(struct
mbuf *m);
void
m_align
(struct
mbuf *m, int
len);
int
M_LEADINGSPACE
(struct
mbuf *m);
int
M_TRAILINGSPACE
(struct
mbuf *m);
void
M_PREPEND
(struct
mbuf *m, int plen,
int how);
void
MCHTYPE
(struct
mbuf *m, int
type);
mbuf
functions and macros provide an easy and
consistent way to handle a networking stack's memory management needs. An
mbuf
consists of a header and a data area. It is of a
fixed size, MSIZE
(defined in
⟨machine/param.h⟩), which includes the
size of the header. The header contains a pointer to the next
mbuf
in the ‘mbuf chain’, a pointer to
the next ‘mbuf chain’, a pointer to the data area, the amount of
data in this mbuf, its type and a flags
field.
The type
variable can signify:
MT_FREE
MT_DATA
MT_HEADER
MT_SONAME
MT_SOOPTS
MT_FTABLE
MT_CONTROL
MT_OOBDATA
The flags
variable contains information
describing the mbuf
, notably:
If an mbuf
designates the start of a
record (M_PKTHDR
), its flags
field may contain additional information describing the content of the
record:
An mbuf
may add a single ‘mbuf
cluster’ of MCLBYTES
bytes (defined in
⟨machine/param.h⟩), which has no
additional overhead and is used instead of the internal data area; this is
done when at least MINCLSIZE
bytes of data must be
stored.
When the M_EXT
flag is set on an mbuf, the
external storage area could be shared among multiple mbufs. Therefore, care
must be taken when overwriting the data content of an mbuf, because its
external storage could be considered as read-only.
m_get
(int how,
int type)M_WAIT
/ M_DONTWAIT
from caller. M_WAIT
means the
call cannot fail, but may take forever. The type
parameter is an mbuf type.m_gethdr
(int how,
int type)M_WAIT / M_DONTWAIT
from caller. The
type parameter is an mbuf type.m_devget
(char *buf,
int totlen, int off,
struct ifnet *ifp)m_copym
(struct mbuf *m,
int off, int len,
int wait)M_COPYALL
,
the complete mbuf chain will be copied. The wait
parameter is a choice of M_WAIT / M_DONTWAIT
from
caller.m_copypacket
(struct mbuf *m,
int how)m_copym
(m
, 0
,
M_COPYALL
, how). However,
contrary to m_copym
(), a header must be present.
It is incorrect to use m_copypacket
() with an mbuf
that does not have a header.m_copydata
(struct mbuf *m,
int off, int len,
void *cp)m_copyback
(struct mbuf *m0,
int off, int len,
void *cp)m_copyback
() can only fail when extending the
chain. The caller should check for this kind of failure by checking the
resulting length of the chain in that case. It is an error to use
m_copyback
() on read-only mbufs.m_copyback_cow
(struct mbuf
*m0, int off, int len,
void *cp, int how)m_copyback
() does. Unlike
m_copyback
(), it is safe to use
m_copyback_cow
() on read-only mbufs. If needed,
m_copyback_cow
() automatically allocates new mbufs
and adjusts the chain. On success, it returns a pointer to the resulting
mbuf chain, and frees the original mbuf m0.
Otherwise, it returns NULL
. The
how parameter is a choice of M_WAIT
/ M_DONTWAIT
from the caller. Unlike
m_copyback
(), extending the mbuf chain isn't
supported. It is an error to attempt to extend the mbuf chain using
m_copyback_cow
().m_makewritable
(struct mbuf
**mp, int off, int len,
int how)m_copyback_cow
() does, and copies the original
content into them. m_makewritable
() does
not guarantee that all len bytes
at off are consecutive. The
how parameter is a choice of M_WAIT
/ M_DONTWAIT
from the caller.
m_makewritable
() preserves the contents of the
mbuf chain even in the case of failure. It updates a pointer to the mbuf
chain pointed to by mp. It returns 0 on success.
Otherwise, it returns an error code, typically
ENOBUFS
.m_cat
(struct mbuf *m,
struct mbuf *n)m_dup
(struct mbuf *m,
int off, int len,
int wait)m_copym
(), the function creates a
copy of an mbuf chain starting off bytes from the
beginning, continuing for len bytes. While
m_copym
() tries to share external storage for
mbufs with M_EXT
flag,
m_dup
() will deep-copy the whole data content into
new mbuf chain and avoids shared external storage.m_pulldown
(struct mbuf *m,
int off, int len,
int *offp)mtod(n, void *) + *offp
, or
mtod(n, void *)
if offp is
NULL
. The top of the mbuf chain
m, and mbufs up to off, will
not be modified. On successful return, it is guaranteed that the mbuf
pointed to by n does not have a shared external
storage, therefore it is safe to update the contiguous region. Returns
NULL
and frees the mbuf chain on failure.
len must be smaller than or equal to
MCLBYTES
.m_pullup
(struct mbuf *m,
int len)mtod
() will work for a structure of size
len). Returns the resulting mbuf chain on success,
frees it and returns NULL
on failure. If there is
room, it will add up to max_protohdr
-
len extra bytes to the contiguous region to possibly
avoid being called again. len must be smaller or
equal than MHLEN
.m_copyup
(struct mbuf *m,
int len, int dstoff)m_pullup
() but copies
len bytes of data into a new mbuf at
dstoff bytes into the mbuf. The
dstoff argument aligns the data and leaves room for
a link layer header. Returns the new mbuf chain on success, and frees the
mbuf chain and returns NULL
on failure. Note that
the function does not allocate mbuf clusters, so len +
dstoff must be less than MHLEN
.m_split
(struct mbuf *m0,
int len, int wait)NULL
and restores the chain to its
original state.m_adj
(struct mbuf *mp,
int req_len)m_apply
(struct mbuf *m,
int off, int len,
int (*f)(void *, void *, unsigned int),
void *arg)m_apply
() will bail out, returning the return code
of f. Upon successful completion it will return
zero.m_free
(struct mbuf *m)m_freem
(struct mbuf *m)NULL
pointer.mtod
(struct mbuf *m,
datatype)MGET
(struct mbuf *m,
int how, int type)m_get
().MGETHDR
(struct mbuf *m,
int how, int type)m_gethdr
().MEXTMALLOC
(struct mbuf *m,
int len, int how)M_WAIT / M_DONTWAIT
from caller. The
flag M_EXT
is set upon success.MEXTADD
(struct mbuf *m,
void *buf, int size,
int type, void (*free)(struct mbuf *,
void *, size_t, void *), void *arg)M_EXT
is set upon success. If a free routine
is specified, it will be called when the mbuf is freed. In the case of
former, the first argument for a free routine is the mbuf
m and the routine is expected to free it in addition
to the external storage pointed by second argument. In the case of latter,
the first argument for the routine is NULL.MCLGET
(struct mbuf *m,
int how)M_WAIT / M_DONTWAIT
from caller. The
flag M_EXT
is set upon success.m_copy_pkthdr
(struct mbuf
*to, struct mbuf *from)M_PKTHDR
set, and to
must be empty.m_move_pkthdr
(struct mbuf
*to, struct mbuf *from)M_PKTHDR
set, and to
must be empty. The flag M_PKTHDR
in mbuf
from will be cleared.m_remove_pkthdr
(struct mbuf
*m)M_PKTHDR
set. This flag will be cleared.m_align
(struct mbuf *m,
int len)M_LEADINGSPACE
(struct mbuf
*m)M_TRAILINGSPACE
(struct mbuf
*m)M_PREPEND
(struct mbuf *m,
int plen, int how)M_DONTWAIT
and
allocation fails, the original mbuf chain is freed and
m is set to NULL
. It is
illegal for the plen parameter to be greater than
MHLEN
.MCHTYPE
(struct mbuf *m,
int type)mbuf
management functions are implemented within the
file sys/kern/uipc_mbuf.c. Function prototypes, and
the functions implemented as macros are located in
sys/sys/mbuf.h.
Jun-ichiro Hagino, Mbuf issues in 4.4BSD IPv6/IPsec support (experiences from KAME IPv6/IPsec implementation), Proceedings of the freenix track: 2000 USENIX annual technical conference, June 2000.
Further extensions and enhancements were made by Bill Joy, Sam Leffler, and Mike Karels at CSRG.
Current implementation of external storage by Matt Thomas ⟨matt@3am-software.com⟩ and Jason R. Thorpe ⟨thorpej@NetBSD.org⟩.
December 22, 2018 | NetBSD 9.2 |