All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL [your name] OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
$FreeBSD: head/share/man/man9/mbuf.9 67664 2000-10-26 23:15:47Z nik $
.Dd October 17, 2000 .Dt MBUF 9 .Os
.Sh NAME .Nm mbuf .Nd "memory management in the kernel IPC subsystem"
.Sh SYNOPSIS .Fd #include <sys/param.h> .Fd #include <sys/mbuf.h>
.Ss Mbuf manipulation macros .Fn mtod "struct mbuf *mbuf" "any type" .Fn MGET "struct mbuf *mbuf" "int how" "short type" .Fn MGETHDR "struct mbuf *mbuf" "int how" "short type" .Fn MCLGET "struct mbuf *mbuf" "int how" .Fn M_PREPEND "struct mbuf *mbuf" "int len" "int how"
.Ss Mbuf manipulation functions .Ft struct mbuf * .Fn m_get "int how" "int type" .Ft struct mbuf * .Fn m_getclr "int how" "int type" .Ft struct mbuf * .Fn m_gethdr "int how" "int type" .Ss Mbuf chain manipulation functions .Ft void .Fn m_freem "struct mbuf *mbuf" .Ft void .Fn m_adj "struct mbuf *mbuf" "int len" .Ft struct mbuf * .Fn m_prepend "struct mbuf *mbuf" "int len" "int how" .Ft struct mbuf * .Fn m_pullup "struct mbuf *mbuf" "int len" .Ft struct mbuf * .Fn m_copym "struct mbuf *mbuf" "int offset" "int len" "int how" .Ft struct mbuf * .Fn m_copypacket "struct mbuf *mbuf" "int how" .Ft struct mbuf * .Fn m_dup "struct mbuf *mbuf" "int how" .Ft void .Fn m_copydata "struct mbuf *mbuf" "int offset" "int len" "caddr_t buf" .Ft void .Fn m_copyback "struct mbuf *mbuf" "int offset" "int len" "caddr_t buf" .Ft struct mbuf * .Fo m_devget .Fa "char *buf" .Fa "int len" .Fa "int offset" .Fa "struct ifnet *ifp" .Fa "void (*copy)(char *from, caddr_t to, u_int len)" .Fc .Ft void .Fn m_cat "struct mbuf *m" "struct mbuf *n" .Ft struct mbuf * .Fn m_split "struct mbuf *mbuf" "int len" "int how"
.Sh DESCRIPTION Mbuf is a basic unit of memory management in the kernel IPC subsystem. Network packets and socket buffers are stored in mbufs. A network packet may span multiple mbufs arranged into a chain
q linked list , which allows adding or trimming network headers without overhead.
p While a developer should not bother mbuf internals without serious reason in order to avoid incompatibilities with future changes, it would be useful to know the mbuf general structure.
p Mbuf consists of a variable-length header and a small internal buffer for data. Mbuf total size .Dv MSIZE is a machine-dependent constant defined in
a machine/param.h . The mbuf header includes:
p l -tag -width "m_nextpkt" -compact -offset indent t Fa m_next a pointer to the next buffer in the chain t Fa m_nextpkt a pointer to the next chain in the queue t Fa m_data a pointer to the data t Fa m_len the length of the data t Fa m_type the type of the data t Fa m_flags the mbuf flags .El
p The mbuf flag bits are defined as follows: d -literal /* mbuf flags */ #define M_EXT 0x0001 /* has associated external storage */ #define M_PKTHDR 0x0002 /* start of record */ #define M_EOR 0x0004 /* end of record */ #define M_PROTO1 0x0008 /* protocol-specific */ #define M_PROTO2 0x0010 /* protocol-specific */ #define M_PROTO3 0x0020 /* protocol-specific */ #define M_PROTO4 0x0040 /* protocol-specific */ #define M_PROTO5 0x0080 /* protocol-specific */ /* mbuf pkthdr flags, also in m_flags */ #define M_BCAST 0x0100 /* send/received as link-level broadcast */ #define M_MCAST 0x0200 /* send/received as link-level multicast */ #define M_FRAG 0x0400 /* packet is a fragment of a larger packet */ #define M_FIRSTFRAG 0x0800 /* packet is first fragment */ #define M_LASTFRAG 0x1000 /* packet is last fragment */ .Ed
p The possible mbuf types are defined as follows: d -literal /* mbuf types */ #define MT_FREE 0 /* should be on free list */ #define MT_DATA 1 /* dynamic (data) allocation */ #define MT_HEADER 2 /* packet header */ #define MT_SONAME 8 /* socket name */ #define MT_FTABLE 11 /* fragment reassembly header */ #define MT_CONTROL 14 /* extra-data protocol message */ #define MT_OOBDATA 15 /* expedited data */ .Ed
p If the .Dv M_PKTHDR flag is set, a .Fa struct pkthdr m_pkthdr is added to the mbuf header. It contains a pointer to the interface the packet has been received from
q Fa struct ifnet *rcvif , and the total packet length
q Fa int len .
p Data is placed into the mbuf internal buffer if small enough. If it is not, another mbuf may be added to the chain, or external storage may be associated with the mbuf. .Dv MHLEN bytes of data can fit into a mbuf with the .Dv M_PKTHDR flag set, .Dv MLEN bytes can otherwise.
p If external storage is being associated with a mbuf, yet another header is added at the cost of loosing the internal buffer. It includes a pointer to an external buffer, its size, and two pointers to storage-specific management routines: one for freeing the buffer, and another for accounting references to it. A mbuf using external storage has the .Dv M_EXT flag set.
p
The system supplies a macro for allocating
the external storage in a system-wide pool of fixed-size
buffers called
.Dq mbuf clusters ,
each
.Dv MCLBYTES
long.
.Dv MCLBYTES
is a
machine-dependent constant. The system defines an advisory macro
.Dv MINCLSIZE ,
which is the smallest amount of data to put into a cluster.
It's equal to the sum of
.Dv MLEN
and
.Dv MHLEN .
The idea is that one should rather add a mbuf to the chain than
allocate a mbuf cluster, if possible.
.Ss Macros and Functions
There is plenty of predefined macros and functions that help a
developer not to worry about mbuf internals. The macros are:
l -ohang -offset indent t Fn mtod mbuf type Convert a mbuf pointer to a data pointer.
The macro expands to the data pointer cast to the pointer to the specified type.
.Sy Note :
You must usually ensure that there is enough contiguous data in the mbuf.
See
.Fn m_pullup
for details.
t Fn MGET mbuf how type Allocate a mbuf and initialize it to contain internal data.
.Fa Mbuf
will point to the allocated mbuf on success, or be
.Dv NULL
on failure. The
.Fa how
argument is to be set to
.Dv M_WAIT
or
.Dv M_DONTWAIT .
It specifies if the macro can block. If
.Fa how
is set to M_WAIT, the macro should never fail, but can block
forever. A number of other mbuf-related
functions and macros have the same argument because they may
need to allocate new mbufs.
.Sy Caution :
Never use
.Dv M_WAIT
if running at the interrupt level.
t Fn MGETHDR mbuf how type Allocate a mbuf and initialize it to contain a packet header
and internal data. See
.Fn MGET
for details.
t Fn MCLGET mbuf how Attach a mbuf cluster to a mbuf. If the macro fails, the
.Dv M_EXT
flag won't be set in the mbuf.
t Fn M_PREPEND mbuf len how This macro operates on a mbuf chain.
It is an optimized wrapper for
.Fn m_prepend
that can make use of possible empty space before data
q "e.g. left after trimming of a link-layer header" . The new chain pointer or .Dv NULL is in .Fa mbuf after the call. .El
p The functions are: l -ohang -offset indent t Fn m_get how type A function version of .Fn MGET . t Fn m_gethdr how type A function version of .Fn MGETHDR . t Fn m_getclr how type .Fn MGET how type first, .Fn bzero the internal data buffer then. .El
p
The functions below operate on mbuf chains.
l -ohang -offset indent t Fn m_freem mbuf Free an entire mbuf chain, including any external
storage.
t Fn m_adj mbuf len Trim
.Fa len
bytes from the head of a mbuf chain if
.Fa len
is positive, from the tail otherwise.
t Fn m_prepend mbuf len how Allocate a new mbuf and prepend it to the chain, handle
.Dv M_PKTHDR
properly.
.Sy Note :
It doesn't allocate any clusters, so
.Fa len
must be less than
.Dv MLEN
or
.Dv MHLEN ,
depending on the
.Dv M_PKTHDR flag setting.
t Fn m_pullup mbuf len Arrange that the first
.Fa len
bytes of a mbuf chain are contiguous and lay in the data area of
.Fa mbuf ,
so they are accessible with
.Fn mtod mbuf type .
Return the new chain on success,
.Dv NULL
on failure
q the chain is freed in this case .
.Sy Note :
It doesn't allocate any clusters, so
.Fa len
must be less than
.Dv MHLEN .
t Fn m_copym mbuf offset len how Make a copy of an mbuf chain starting
.Fa offset
bytes from the beginning, continuing for
.Fa len
bytes. If
.Fa len
is
.Dv M_COPYALL ,
copy to the end of the mbuf chain.
.Sy Note :
The copy is read-only, because clusters are not
copied, only their reference counts are incremented.
t Fn m_copypacket mbuf how Copy an entire packet including header, which must be present.
This is an optimized version of the common case
.Fn m_copym mbuf 0 M_COPYALL how .
.Sy Note :
the copy is read-only, because clusters are not
copied, only their reference counts are incremented.
t Fn m_dup mbuf how Copy a packet header mbuf chain into a completely new chain, including
copying any mbuf clusters. Use this instead of
.Fn m_copypacket
when you need a writable copy of an mbuf chain.
t Fn m_copydata mbuf offset len buf Copy data from a mbuf chain starting
.Fa off
bytes from the beginning, continuing for
.Fa len
bytes, into the indicated buffer
.Fa buf .
t Fn m_copyback mbuf offset len buf Copy
.Fa len
bytes from the buffer
.Fa buf
back into the indicated mbuf chain,
starting at
.Fa offset
bytes from the beginning of the chain, extending the mbuf chain if necessary.
.Sy Note :
It doesn't allocate any clusters, just adds mbufs to the chain. It's safe
to set
.Fa offset
beyond the current chain end: zeroed mbufs will be allocated to fill the
space.
t Fn m_devget buf len offset ifp copy Copy data from a device local memory pointed to by
.Fa buf
to a mbuf chain. The copy is done using a specified copy routine
.Fa copy ,
or
.Fn bcopy
if
.Fa copy
is
.Dv NULL .
t Fn m_cat m n Concatenate
.Fa n
to
.Fa m .
Both chains must be of the same type.
.Fa N
is still valid after the function returned.
.Sy Note :
It does not handle
.Dv M_PKTHDR
and friends.
t Fn m_split mbuf len how Partition an mbuf chain in two pieces, returning the tail:
all but the first
.Fa len
bytes. In case of failure, it returns
.Dv NULL
and attempts to restore the chain to its original state.
.Sh RETURN VALUES
See above.
.Sh HISTORY
Please correct me if I'm wrong
Mbufs appeared in an early version of BSD. They were used
to keep various dynamic structures, such as routing table
entries, interface addresses, protocol control blocks etc
besides network packets.
.Sh AUTHORS
This man page was written by Yar Tikhiy.