408 lines
11 KiB
Groff
408 lines
11 KiB
Groff
.\" 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.
|