freebsd-src/share/man/man9/mbuf.9

.\" Copyright (c) 2000 FreeBSD Inc.
.\" 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$
.\"
.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
.Pq linked list ,
which allows adding or trimming
network headers without overhead.
.Pp
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.
.Pp
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
.Pa machine/param.h .
The mbuf header includes:
.Pp
.Bl -tag -width "m_nextpkt" -compact -offset indent
.It Fa m_next
a pointer to the next buffer in the chain
.It Fa m_nextpkt
a pointer to the next chain in the queue
.It Fa m_data
a pointer to the data
.It Fa m_len
the length of the data
.It Fa m_type
the type of the data
.It Fa m_flags
the mbuf flags
.El
.Pp
The mbuf flag bits are defined as follows:
.Bd -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
.Pp
The possible mbuf types are defined as follows:
.Bd -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
.Pp
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
.Pq Fa struct ifnet *rcvif ,
and the total packet length
.Pq Fa int len .
.Pp
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.
.Pp
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.
.Pp
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:
.\"
.Bl -ohang -offset indent
.It 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.
.It 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.
.It Fn MGETHDR mbuf how type
Allocate a mbuf and initialize it to contain a packet header
and internal data. See
.Fn MGET
for details.
.It 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.
.It 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
.Pq "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
.Pp
The functions are:
.Bl -ohang -offset indent 
.It Fn m_get how type
A function version of
.Fn MGET .
.It Fn m_gethdr how type
A function version of
.Fn MGETHDR .
.It Fn m_getclr how type
.Fn MGET how type
first,
.Fn bzero
the internal data buffer then.
.El
.Pp
The functions below operate on mbuf chains.
.Bl -ohang -offset indent
.It Fn m_freem mbuf
Free an entire mbuf chain, including any external
storage.
.\"
.It 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.
.\"
.It 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.
.\"
.It 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
.Pq the chain is freed in this case .
.Sy Note :
It doesn't allocate any clusters, so
.Fa len
must be less than
.Dv MHLEN .
.\"
.It 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.
.\"
.It 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.
.\"
.It 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.
.\"
.It 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 .
.\"
.It 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.
.\"
.It 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 .
.\"
.It 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.
.\"
.It 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.