summaryrefslogtreecommitdiff
path: root/static/freebsd/man9/mbuf.9 4.html
diff options
context:
space:
mode:
Diffstat (limited to 'static/freebsd/man9/mbuf.9 4.html')
-rw-r--r--static/freebsd/man9/mbuf.9 4.html1032
1 files changed, 0 insertions, 1032 deletions
diff --git a/static/freebsd/man9/mbuf.9 4.html b/static/freebsd/man9/mbuf.9 4.html
deleted file mode 100644
index de9adb99..00000000
--- a/static/freebsd/man9/mbuf.9 4.html
+++ /dev/null
@@ -1,1032 +0,0 @@
-<table class="head">
- <tr>
- <td class="head-ltitle">MBUF(9)</td>
- <td class="head-vol">Kernel Developer's Manual</td>
- <td class="head-rtitle">MBUF(9)</td>
- </tr>
-</table>
-<div class="manual-text">
-<section class="Sh">
-<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
-<p class="Pp"><code class="Nm">mbuf</code> &#x2014; <span class="Nd">memory
- management in the kernel IPC subsystem</span></p>
-</section>
-<section class="Sh">
-<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
-<p class="Pp"><code class="In">#include
- &lt;<a class="In">sys/param.h</a>&gt;</code>
- <br/>
- <code class="In">#include &lt;<a class="In">sys/systm.h</a>&gt;</code>
- <br/>
- <code class="In">#include &lt;<a class="In">sys/mbuf.h</a>&gt;</code></p>
-<section class="Ss">
-<h2 class="Ss" id="Mbuf_allocation_macros"><a class="permalink" href="#Mbuf_allocation_macros">Mbuf
- allocation macros</a></h2>
-<p class="Pp"><code class="Fn">MGET</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *mbuf</var>, <var class="Fa" style="white-space: nowrap;">int
- how</var>, <var class="Fa" style="white-space: nowrap;">short
- type</var>);</p>
-<p class="Pp"><code class="Fn">MGETHDR</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *mbuf</var>, <var class="Fa" style="white-space: nowrap;">int
- how</var>, <var class="Fa" style="white-space: nowrap;">short
- type</var>);</p>
-<p class="Pp"><var class="Ft">int</var>
- <br/>
- <code class="Fn">MCLGET</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *mbuf</var>, <var class="Fa" style="white-space: nowrap;">int
- how</var>);</p>
-<p class="Pp"><code class="Fn">MEXTADD</code>(<var class="Fa">struct mbuf
- *mbuf</var>, <var class="Fa">char *buf</var>, <var class="Fa">u_int
- size</var>, <var class="Fa">void (*free)(struct mbuf *)</var>,
- <var class="Fa">void *opt_arg1</var>, <var class="Fa">void *opt_arg2</var>,
- <var class="Fa">int flags</var>, <var class="Fa">int type</var>);</p>
-</section>
-<section class="Ss">
-<h2 class="Ss" id="Mbuf_utility_macros"><a class="permalink" href="#Mbuf_utility_macros">Mbuf
- utility macros</a></h2>
-<p class="Pp"><var class="Ft">type</var>
- <br/>
- <code class="Fn">mtod</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *mbuf</var>,
- <var class="Fa" style="white-space: nowrap;">type</var>);</p>
-<p class="Pp"><var class="Ft">void *</var>
- <br/>
- <code class="Fn">mtodo</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *mbuf</var>,
- <var class="Fa" style="white-space: nowrap;">offset</var>);</p>
-<p class="Pp"><code class="Fn">M_ALIGN</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *mbuf</var>, <var class="Fa" style="white-space: nowrap;">u_int
- len</var>);</p>
-<p class="Pp"><code class="Fn">MH_ALIGN</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *mbuf</var>, <var class="Fa" style="white-space: nowrap;">u_int
- len</var>);</p>
-<p class="Pp"><var class="Ft">int</var>
- <br/>
- <code class="Fn">M_LEADINGSPACE</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *mbuf</var>);</p>
-<p class="Pp"><var class="Ft">int</var>
- <br/>
- <code class="Fn">M_TRAILINGSPACE</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *mbuf</var>);</p>
-<p class="Pp"><code class="Fn">M_MOVE_PKTHDR</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *to</var>, <var class="Fa" style="white-space: nowrap;">struct mbuf
- *from</var>);</p>
-<p class="Pp"><code class="Fn">M_PREPEND</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *mbuf</var>, <var class="Fa" style="white-space: nowrap;">int
- len</var>, <var class="Fa" style="white-space: nowrap;">int how</var>);</p>
-<p class="Pp"><code class="Fn">MCHTYPE</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *mbuf</var>, <var class="Fa" style="white-space: nowrap;">short
- type</var>);</p>
-<p class="Pp"><var class="Ft">int</var>
- <br/>
- <code class="Fn">M_WRITABLE</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *mbuf</var>);</p>
-</section>
-<section class="Ss">
-<h2 class="Ss" id="Mbuf_allocation_functions"><a class="permalink" href="#Mbuf_allocation_functions">Mbuf
- allocation functions</a></h2>
-<p class="Pp"><var class="Ft">struct mbuf *</var>
- <br/>
- <code class="Fn">m_get</code>(<var class="Fa" style="white-space: nowrap;">int
- how</var>, <var class="Fa" style="white-space: nowrap;">short
- type</var>);</p>
-<p class="Pp"><var class="Ft">struct mbuf *</var>
- <br/>
- <code class="Fn">m_get2</code>(<var class="Fa" style="white-space: nowrap;">int
- size</var>, <var class="Fa" style="white-space: nowrap;">int how</var>,
- <var class="Fa" style="white-space: nowrap;">short type</var>,
- <var class="Fa" style="white-space: nowrap;">int flags</var>);</p>
-<p class="Pp"><var class="Ft">struct mbuf *</var>
- <br/>
- <code class="Fn">m_get3</code>(<var class="Fa" style="white-space: nowrap;">int
- size</var>, <var class="Fa" style="white-space: nowrap;">int how</var>,
- <var class="Fa" style="white-space: nowrap;">short type</var>,
- <var class="Fa" style="white-space: nowrap;">int flags</var>);</p>
-<p class="Pp"><var class="Ft">struct mbuf *</var>
- <br/>
- <code class="Fn">m_getm</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *orig</var>, <var class="Fa" style="white-space: nowrap;">int
- len</var>, <var class="Fa" style="white-space: nowrap;">int how</var>,
- <var class="Fa" style="white-space: nowrap;">short type</var>);</p>
-<p class="Pp"><var class="Ft">struct mbuf *</var>
- <br/>
- <code class="Fn">m_getjcl</code>(<var class="Fa" style="white-space: nowrap;">int
- how</var>, <var class="Fa" style="white-space: nowrap;">short type</var>,
- <var class="Fa" style="white-space: nowrap;">int flags</var>,
- <var class="Fa" style="white-space: nowrap;">int size</var>);</p>
-<p class="Pp"><var class="Ft">struct mbuf *</var>
- <br/>
- <code class="Fn">m_getcl</code>(<var class="Fa" style="white-space: nowrap;">int
- how</var>, <var class="Fa" style="white-space: nowrap;">short type</var>,
- <var class="Fa" style="white-space: nowrap;">int flags</var>);</p>
-<p class="Pp"><var class="Ft">struct mbuf *</var>
- <br/>
- <code class="Fn">m_gethdr</code>(<var class="Fa" style="white-space: nowrap;">int
- how</var>, <var class="Fa" style="white-space: nowrap;">short
- type</var>);</p>
-<p class="Pp"><var class="Ft">struct mbuf *</var>
- <br/>
- <code class="Fn">m_free</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *mbuf</var>);</p>
-<p class="Pp"><var class="Ft">void</var>
- <br/>
- <code class="Fn">m_freem</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *mbuf</var>);</p>
-</section>
-<section class="Ss">
-<h2 class="Ss" id="Mbuf_utility_functions"><a class="permalink" href="#Mbuf_utility_functions">Mbuf
- utility functions</a></h2>
-<p class="Pp"><var class="Ft">void</var>
- <br/>
- <code class="Fn">m_adj</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *mbuf</var>, <var class="Fa" style="white-space: nowrap;">int
- len</var>);</p>
-<p class="Pp"><var class="Ft">void</var>
- <br/>
- <code class="Fn">m_align</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *mbuf</var>, <var class="Fa" style="white-space: nowrap;">int
- len</var>);</p>
-<p class="Pp"><var class="Ft">int</var>
- <br/>
- <code class="Fn">m_append</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *mbuf</var>, <var class="Fa" style="white-space: nowrap;">int
- len</var>, <var class="Fa" style="white-space: nowrap;">c_caddr_t
- cp</var>);</p>
-<p class="Pp"><var class="Ft">struct mbuf *</var>
- <br/>
- <code class="Fn">m_prepend</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *mbuf</var>, <var class="Fa" style="white-space: nowrap;">int
- len</var>, <var class="Fa" style="white-space: nowrap;">int how</var>);</p>
-<p class="Pp"><var class="Ft">struct mbuf *</var>
- <br/>
- <code class="Fn">m_copyup</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *mbuf</var>, <var class="Fa" style="white-space: nowrap;">int
- len</var>, <var class="Fa" style="white-space: nowrap;">int
- dstoff</var>);</p>
-<p class="Pp"><var class="Ft">struct mbuf *</var>
- <br/>
- <code class="Fn">m_pullup</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *mbuf</var>, <var class="Fa" style="white-space: nowrap;">int
- len</var>);</p>
-<p class="Pp"><var class="Ft">struct mbuf *</var>
- <br/>
- <code class="Fn">m_pulldown</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *mbuf</var>, <var class="Fa" style="white-space: nowrap;">int
- offset</var>, <var class="Fa" style="white-space: nowrap;">int len</var>,
- <var class="Fa" style="white-space: nowrap;">int *offsetp</var>);</p>
-<p class="Pp"><var class="Ft">struct mbuf *</var>
- <br/>
- <code class="Fn">m_copym</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *mbuf</var>, <var class="Fa" style="white-space: nowrap;">int
- offset</var>, <var class="Fa" style="white-space: nowrap;">int len</var>,
- <var class="Fa" style="white-space: nowrap;">int how</var>);</p>
-<p class="Pp"><var class="Ft">struct mbuf *</var>
- <br/>
- <code class="Fn">m_copypacket</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *mbuf</var>, <var class="Fa" style="white-space: nowrap;">int
- how</var>);</p>
-<p class="Pp"><var class="Ft">struct mbuf *</var>
- <br/>
- <code class="Fn">m_dup</code>(<var class="Fa" style="white-space: nowrap;">const
- struct mbuf *mbuf</var>, <var class="Fa" style="white-space: nowrap;">int
- how</var>);</p>
-<p class="Pp"><var class="Ft">void</var>
- <br/>
- <code class="Fn">m_copydata</code>(<var class="Fa" style="white-space: nowrap;">const
- struct mbuf *mbuf</var>, <var class="Fa" style="white-space: nowrap;">int
- offset</var>, <var class="Fa" style="white-space: nowrap;">int len</var>,
- <var class="Fa" style="white-space: nowrap;">caddr_t buf</var>);</p>
-<p class="Pp"><var class="Ft">void</var>
- <br/>
- <code class="Fn">m_copyback</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *mbuf</var>, <var class="Fa" style="white-space: nowrap;">int
- offset</var>, <var class="Fa" style="white-space: nowrap;">int len</var>,
- <var class="Fa" style="white-space: nowrap;">caddr_t buf</var>);</p>
-<p class="Pp"><var class="Ft">struct mbuf *</var>
- <br/>
- <code class="Fn">m_devget</code>(<var class="Fa">char *buf</var>,
- <var class="Fa">int len</var>, <var class="Fa">int offset</var>,
- <var class="Fa">struct ifnet *ifp</var>, <var class="Fa">void (*copy)(char
- *from, caddr_t to, u_int len)</var>);</p>
-<p class="Pp"><var class="Ft">void</var>
- <br/>
- <code class="Fn">m_cat</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *m</var>, <var class="Fa" style="white-space: nowrap;">struct mbuf
- *n</var>);</p>
-<p class="Pp"><var class="Ft">void</var>
- <br/>
- <code class="Fn">m_catpkt</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *m</var>, <var class="Fa" style="white-space: nowrap;">struct mbuf
- *n</var>);</p>
-<p class="Pp"><var class="Ft">u_int</var>
- <br/>
- <code class="Fn">m_fixhdr</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *mbuf</var>);</p>
-<p class="Pp"><var class="Ft">int</var>
- <br/>
- <code class="Fn">m_dup_pkthdr</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *to</var>, <var class="Fa" style="white-space: nowrap;">const struct
- mbuf *from</var>, <var class="Fa" style="white-space: nowrap;">int
- how</var>);</p>
-<p class="Pp"><var class="Ft">void</var>
- <br/>
- <code class="Fn">m_move_pkthdr</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *to</var>, <var class="Fa" style="white-space: nowrap;">struct mbuf
- *from</var>);</p>
-<p class="Pp"><var class="Ft">u_int</var>
- <br/>
- <code class="Fn">m_length</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *mbuf</var>, <var class="Fa" style="white-space: nowrap;">struct mbuf
- **last</var>);</p>
-<p class="Pp"><var class="Ft">struct mbuf *</var>
- <br/>
- <code class="Fn">m_split</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *mbuf</var>, <var class="Fa" style="white-space: nowrap;">int
- len</var>, <var class="Fa" style="white-space: nowrap;">int how</var>);</p>
-<p class="Pp"><var class="Ft">int</var>
- <br/>
- <code class="Fn">m_apply</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *mbuf</var>, <var class="Fa" style="white-space: nowrap;">int
- off</var>, <var class="Fa" style="white-space: nowrap;">int len</var>,
- <var class="Fa" style="white-space: nowrap;">int (*f)(void *arg, void *data,
- u_int len)</var>, <var class="Fa" style="white-space: nowrap;">void
- *arg</var>);</p>
-<p class="Pp"><var class="Ft">struct mbuf *</var>
- <br/>
- <code class="Fn">m_getptr</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *mbuf</var>, <var class="Fa" style="white-space: nowrap;">int
- loc</var>, <var class="Fa" style="white-space: nowrap;">int *off</var>);</p>
-<p class="Pp"><var class="Ft">struct mbuf *</var>
- <br/>
- <code class="Fn">m_defrag</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *m0</var>, <var class="Fa" style="white-space: nowrap;">int
- how</var>);</p>
-<p class="Pp"><var class="Ft">struct mbuf *</var>
- <br/>
- <code class="Fn">m_collapse</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *m0</var>, <var class="Fa" style="white-space: nowrap;">int how</var>,
- <var class="Fa" style="white-space: nowrap;">int maxfrags</var>);</p>
-<p class="Pp"><var class="Ft">struct mbuf *</var>
- <br/>
- <code class="Fn">m_unshare</code>(<var class="Fa" style="white-space: nowrap;">struct
- mbuf *m0</var>, <var class="Fa" style="white-space: nowrap;">int
- how</var>);</p>
-</section>
-</section>
-<section class="Sh">
-<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
-<p class="Pp">An <var class="Vt">mbuf</var> is a basic unit of memory management
- in the kernel IPC subsystem. Network packets and socket buffers are stored
- in <var class="Vt">mbufs</var>. A network packet may span multiple
- <var class="Vt">mbufs</var> arranged into a <var class="Vt">mbuf chain</var>
- (linked list), which allows adding or trimming network headers with little
- overhead.</p>
-<p class="Pp">While a developer should not bother with
- <var class="Vt">mbuf</var> internals without serious reason in order to
- avoid incompatibilities with future changes, it is useful to understand the
- general structure of an <var class="Vt">mbuf</var>.</p>
-<p class="Pp">An <var class="Vt">mbuf</var> consists of a variable-sized header
- and a small internal buffer for data. The total size of an
- <var class="Vt">mbuf</var>, <code class="Dv">MSIZE</code>, is a constant
- defined in <code class="In">&lt;<a class="In">sys/param.h</a>&gt;</code>.
- The <var class="Vt">mbuf</var> header includes:</p>
-<div class="Bd-indent">
-<dl class="Bl-tag">
- <dt id="m_next"><var class="Va">m_next</var></dt>
- <dd>(<var class="Vt">struct mbuf *</var>) A pointer to the next
- <var class="Vt">mbuf</var> in the <var class="Vt">mbuf chain</var>.</dd>
- <dt id="m_nextpkt"><var class="Va">m_nextpkt</var></dt>
- <dd>(<var class="Vt">struct mbuf *</var>) A pointer to the next
- <var class="Vt">mbuf chain</var> in the queue.</dd>
- <dt id="m_data"><var class="Va">m_data</var></dt>
- <dd>(<var class="Vt">caddr_t</var>) A pointer to data attached to this
- <var class="Vt">mbuf</var>.</dd>
- <dt id="m_len"><var class="Va">m_len</var></dt>
- <dd>(<var class="Vt">int</var>) The length of the data.</dd>
- <dt id="m_type"><var class="Va">m_type</var></dt>
- <dd>(<var class="Vt">short</var>) The type of the data.</dd>
- <dt id="m_flags"><var class="Va">m_flags</var></dt>
- <dd>(<var class="Vt">int</var>) The <var class="Vt">mbuf</var> flags.</dd>
-</dl>
-</div>
-<p class="Pp">The <var class="Vt">mbuf</var> flag bits are defined as
- follows:</p>
-<div class="Bd Pp Li">
-<pre>#define M_EXT 0x00000001 /* has associated external storage */
-#define M_PKTHDR 0x00000002 /* start of record */
-#define M_EOR 0x00000004 /* end of record */
-#define M_RDONLY 0x00000008 /* associated data marked read-only */
-#define M_BCAST 0x00000010 /* send/received as link-level broadcast */
-#define M_MCAST 0x00000020 /* send/received as link-level multicast */
-#define M_PROMISC 0x00000040 /* packet was not for us */
-#define M_VLANTAG 0x00000080 /* ether_vtag is valid */
-#define M_EXTPG 0x00000100 /* has array of unmapped pages and TLS */
-#define M_NOFREE 0x00000200 /* do not free mbuf, embedded in cluster */
-#define M_TSTMP 0x00000400 /* rcv_tstmp field is valid */
-#define M_TSTMP_HPREC 0x00000800 /* rcv_tstmp is high-prec, typically
- hw-stamped on port (useful for IEEE 1588
- and 802.1AS) */
-
-#define M_PROTO1 0x00001000 /* protocol-specific */
-#define M_PROTO2 0x00002000 /* protocol-specific */
-#define M_PROTO3 0x00004000 /* protocol-specific */
-#define M_PROTO4 0x00008000 /* protocol-specific */
-#define M_PROTO5 0x00010000 /* protocol-specific */
-#define M_PROTO6 0x00020000 /* protocol-specific */
-#define M_PROTO7 0x00040000 /* protocol-specific */
-#define M_PROTO8 0x00080000 /* protocol-specific */
-#define M_PROTO9 0x00100000 /* protocol-specific */
-#define M_PROTO10 0x00200000 /* protocol-specific */
-#define M_PROTO11 0x00400000 /* protocol-specific */
-#define M_PROTO12 0x00800000 /* protocol-specific */</pre>
-</div>
-<p class="Pp">The available <var class="Vt">mbuf</var> types are defined as
- follows:</p>
-<div class="Bd Pp Li">
-<pre>#define MT_DATA 1 /* dynamic (data) allocation */
-#define MT_HEADER MT_DATA /* packet header */
-
-#define MT_VENDOR1 4 /* for vendor-internal use */
-#define MT_VENDOR2 5 /* for vendor-internal use */
-#define MT_VENDOR3 6 /* for vendor-internal use */
-#define MT_VENDOR4 7 /* for vendor-internal use */
-
-#define MT_SONAME 8 /* socket name */
-
-#define MT_EXP1 9 /* for experimental use */
-#define MT_EXP2 10 /* for experimental use */
-#define MT_EXP3 11 /* for experimental use */
-#define MT_EXP4 12 /* for experimental use */
-
-#define MT_CONTROL 14 /* extra-data protocol message */
-#define MT_EXTCONTROL 15 /* control message with externalized contents */
-#define MT_OOBDATA 16 /* expedited data */</pre>
-</div>
-<p class="Pp">The available external buffer types are defined as follows:</p>
-<div class="Bd Pp Li">
-<pre>#define EXT_CLUSTER 1 /* mbuf cluster */
-#define EXT_SFBUF 2 /* sendfile(2)'s sf_bufs */
-#define EXT_JUMBOP 3 /* jumbo cluster 4096 bytes */
-#define EXT_JUMBO9 4 /* jumbo cluster 9216 bytes */
-#define EXT_JUMBO16 5 /* jumbo cluster 16184 bytes */
-#define EXT_PACKET 6 /* mbuf+cluster from packet zone */
-#define EXT_MBUF 7 /* external mbuf reference */
-#define EXT_RXRING 8 /* data in NIC receive ring */
-#define EXT_PGS 9 /* array of unmapped pages */
-
-#define EXT_VENDOR1 224 /* for vendor-internal use */
-#define EXT_VENDOR2 225 /* for vendor-internal use */
-#define EXT_VENDOR3 226 /* for vendor-internal use */
-#define EXT_VENDOR4 227 /* for vendor-internal use */
-
-#define EXT_EXP1 244 /* for experimental use */
-#define EXT_EXP2 245 /* for experimental use */
-#define EXT_EXP3 246 /* for experimental use */
-#define EXT_EXP4 247 /* for experimental use */
-
-#define EXT_NET_DRV 252 /* custom ext_buf provided by net driver(s) */
-#define EXT_MOD_TYPE 253 /* custom module's ext_buf type */
-#define EXT_DISPOSABLE 254 /* can throw this buffer away w/page flipping */
-#define EXT_EXTREF 255 /* has externally maintained ref_cnt ptr */</pre>
-</div>
-<p class="Pp">If the <code class="Dv">M_PKTHDR</code> flag is set, a
- <var class="Vt">struct pkthdr</var> <var class="Va">m_pkthdr</var> is added
- to the <var class="Vt">mbuf</var> header. It contains a pointer to the
- interface the packet has been received from (<var class="Vt">struct
- ifnet</var> <var class="Va">*rcvif</var>), and the total packet length
- (<var class="Vt">int</var> <var class="Va">len</var>). Optionally, it may
- also contain an attached list of packet tags (<var class="Vt">struct
- m_tag</var>). See <a class="Xr">mbuf_tags(9)</a> for details. Fields used in
- offloading checksum calculation to the hardware are kept in
- <var class="Va">m_pkthdr</var> as well. See
- <a class="Sx" href="#HARDWARE_ASSISTED_CHECKSUM_CALCULATION">HARDWARE-ASSISTED
- CHECKSUM CALCULATION</a> for details.</p>
-<p class="Pp">If small enough, data is stored in the internal data buffer of an
- <var class="Vt">mbuf</var>. If the data is sufficiently large, another
- <var class="Vt">mbuf</var> may be added to the <var class="Vt">mbuf
- chain</var>, or external storage may be associated with the
- <var class="Vt">mbuf</var>. <code class="Dv">MHLEN</code> bytes of data can
- fit into an <var class="Vt">mbuf</var> with the
- <code class="Dv">M_PKTHDR</code> flag set, <code class="Dv">MLEN</code>
- bytes can otherwise.</p>
-<p class="Pp">If external storage is being associated with an
- <var class="Vt">mbuf</var>, the <var class="Va">m_ext</var> header is added
- at the cost of losing the internal data buffer. It includes a pointer to
- external storage, the size of the storage, a pointer to a function used for
- freeing the storage, a pointer to an optional argument that can be passed to
- the function, and a pointer to a reference counter. An
- <var class="Vt">mbuf</var> using external storage has the
- <code class="Dv">M_EXT</code> flag set.</p>
-<p class="Pp">The system supplies a macro for allocating the desired external
- storage buffer, <code class="Dv">MEXTADD</code>.</p>
-<p class="Pp">The allocation and management of the reference counter is handled
- by the subsystem.</p>
-<p class="Pp">The system also supplies a default type of external storage buffer
- called an <var class="Vt">mbuf cluster</var>. <var class="Vt">Mbuf
- clusters</var> can be allocated and configured with the use of the
- <code class="Dv">MCLGET</code> macro. Each <var class="Vt">mbuf
- cluster</var> is <code class="Dv">MCLBYTES</code> in size, where MCLBYTES is
- a machine-dependent constant. The system defines an advisory macro
- <code class="Dv">MINCLSIZE</code>, which is the smallest amount of data to
- put into an <var class="Vt">mbuf cluster</var>. It is equal to
- <code class="Dv">MHLEN</code> plus one. It is typically preferable to store
- data into the data region of an <var class="Vt">mbuf</var>, if size permits,
- as opposed to allocating a separate <var class="Vt">mbuf cluster</var> to
- hold the same data.</p>
-<section class="Ss">
-<h2 class="Ss" id="Macros_and_Functions"><a class="permalink" href="#Macros_and_Functions">Macros
- and Functions</a></h2>
-<p class="Pp">There are numerous predefined macros and functions that provide
- the developer with common utilities.</p>
-<dl class="Bl-ohang Bd-indent">
- <dt id="mtod"><a class="permalink" href="#mtod"><code class="Fn">mtod</code></a>(<var class="Fa">mbuf</var>,
- <var class="Fa">type</var>)</dt>
- <dd>Convert an <var class="Fa">mbuf</var> pointer to a data pointer. The macro
- expands to the data pointer cast to the specified
- <var class="Fa">type</var>. <b class="Sy">Note</b>: It is advisable to
- ensure that there is enough contiguous data in <var class="Fa">mbuf</var>.
- See
- <a class="permalink" href="#m_pullup"><code class="Fn" id="m_pullup">m_pullup</code></a>()
- for details.</dd>
- <dt id="mtodo"><a class="permalink" href="#mtodo"><code class="Fn">mtodo</code></a>(<var class="Fa">mbuf</var>,
- <var class="Fa">offset</var>)</dt>
- <dd>Return a data pointer at an offset (in bytes) into the data attached to
- <var class="Fa">mbuf</var>. Returns a <var class="Ft">void *</var> pointer
- . <b class="Sy">Note</b>: The caller must ensure that the offset is in
- bounds of the attached data.</dd>
- <dt><code class="Fn">MGET</code>(<var class="Fa">mbuf</var>,
- <var class="Fa">how</var>, <var class="Fa">type</var>)</dt>
- <dd>Allocate an <var class="Vt">mbuf</var> and initialize it to contain
- internal data. <var class="Fa">mbuf</var> will point to the allocated
- <var class="Vt">mbuf</var> on success, or be set to
- <code class="Dv">NULL</code> on failure. The <var class="Fa">how</var>
- argument is to be set to <code class="Dv">M_WAITOK</code> or
- <code class="Dv">M_NOWAIT</code>. It specifies whether the caller is
- willing to block if necessary. A number of other functions and macros
- related to <var class="Vt">mbufs</var> have the same argument because they
- may at some point need to allocate new <var class="Vt">mbufs</var>.</dd>
- <dt id="MGETHDR"><a class="permalink" href="#MGETHDR"><code class="Fn">MGETHDR</code></a>(<var class="Fa">mbuf</var>,
- <var class="Fa">how</var>, <var class="Fa">type</var>)</dt>
- <dd>Allocate an <var class="Vt">mbuf</var> and initialize it to contain a
- packet header and internal data. See <code class="Fn">MGET</code>() for
- details.</dd>
- <dt id="MEXTADD"><a class="permalink" href="#MEXTADD"><code class="Fn">MEXTADD</code></a>(<var class="Fa">mbuf</var>,
- <var class="Fa">buf</var>, <var class="Fa">size</var>,
- <var class="Fa">free</var>, <var class="Fa">opt_arg1</var>,
- <var class="Fa">opt_arg2</var>, <var class="Fa">flags</var>,
- <var class="Fa">type</var>)</dt>
- <dd>Associate externally managed data with <var class="Fa">mbuf</var>. Any
- internal data contained in the mbuf will be discarded, and the
- <code class="Dv">M_EXT</code> flag will be set. The
- <var class="Fa">buf</var> and <var class="Fa">size</var> arguments are the
- address and length, respectively, of the data. The
- <var class="Fa">free</var> argument points to a function which will be
- called to free the data when the mbuf is freed; it is only used if
- <var class="Fa">type</var> is <code class="Dv">EXT_EXTREF</code>. The
- <var class="Fa">opt_arg1</var> and <var class="Fa">opt_arg2</var>
- arguments will be saved in <var class="Va">ext_arg1</var> and
- <var class="Va">ext_arg2</var> fields of the <var class="Va">struct
- m_ext</var> of the mbuf. The <var class="Fa">flags</var> argument
- specifies additional <var class="Vt">mbuf</var> flags; it is not necessary
- to specify <code class="Dv">M_EXT</code>. Finally, the
- <var class="Fa">type</var> argument specifies the type of external data,
- which controls how it will be disposed of when the
- <var class="Vt">mbuf</var> is freed. In most cases, the correct value is
- <code class="Dv">EXT_EXTREF</code>.</dd>
- <dt id="MCLGET"><a class="permalink" href="#MCLGET"><code class="Fn">MCLGET</code></a>(<var class="Fa">mbuf</var>,
- <var class="Fa">how</var>)</dt>
- <dd>Allocate and attach an <var class="Vt">mbuf cluster</var> to
- <var class="Fa">mbuf</var>. On success, a non-zero value returned;
- otherwise, 0. Historically, consumers would check for success by testing
- the <code class="Dv">M_EXT</code> flag on the mbuf, but this is now
- discouraged to avoid unnecessary awareness of the implementation of
- external storage in protocol stacks and device drivers.</dd>
- <dt id="M_ALIGN"><a class="permalink" href="#M_ALIGN"><code class="Fn">M_ALIGN</code></a>(<var class="Fa">mbuf</var>,
- <var class="Fa">len</var>)</dt>
- <dd>Set the pointer <var class="Fa">mbuf-&gt;m_data</var> to place an object
- of the size <var class="Fa">len</var> at the end of the internal data area
- of <var class="Fa">mbuf</var>, long word aligned. Applicable only if
- <var class="Fa">mbuf</var> is newly allocated with
- <code class="Fn">MGET</code>() or <code class="Fn">m_get</code>().</dd>
- <dt id="MH_ALIGN"><a class="permalink" href="#MH_ALIGN"><code class="Fn">MH_ALIGN</code></a>(<var class="Fa">mbuf</var>,
- <var class="Fa">len</var>)</dt>
- <dd>Serves the same purpose as <code class="Fn">M_ALIGN</code>() does, but
- only for <var class="Fa">mbuf</var> newly allocated with
- <code class="Fn">MGETHDR</code>() or <code class="Fn">m_gethdr</code>(),
- or initialized by
- <a class="permalink" href="#m_dup_pkthdr"><code class="Fn" id="m_dup_pkthdr">m_dup_pkthdr</code></a>()
- or
- <a class="permalink" href="#m_move_pkthdr"><code class="Fn" id="m_move_pkthdr">m_move_pkthdr</code></a>().</dd>
- <dt id="m_align"><a class="permalink" href="#m_align"><code class="Fn">m_align</code></a>(<var class="Fa">mbuf</var>,
- <var class="Fa">len</var>)</dt>
- <dd>Services the same purpose as <code class="Fn">M_ALIGN</code>() but handles
- any type of mbuf.</dd>
- <dt id="M_LEADINGSPACE"><a class="permalink" href="#M_LEADINGSPACE"><code class="Fn">M_LEADINGSPACE</code></a>(<var class="Fa">mbuf</var>)</dt>
- <dd>Returns the number of bytes available before the beginning of data in
- <var class="Fa">mbuf</var>.</dd>
- <dt id="M_TRAILINGSPACE"><a class="permalink" href="#M_TRAILINGSPACE"><code class="Fn">M_TRAILINGSPACE</code></a>(<var class="Fa">mbuf</var>)</dt>
- <dd>Returns the number of bytes available after the end of data in
- <var class="Fa">mbuf</var>.</dd>
- <dt id="M_PREPEND"><a class="permalink" href="#M_PREPEND"><code class="Fn">M_PREPEND</code></a>(<var class="Fa">mbuf</var>,
- <var class="Fa">len</var>, <var class="Fa">how</var>)</dt>
- <dd>This macro operates on an <var class="Vt">mbuf chain</var>. It is an
- optimized wrapper for <code class="Fn">m_prepend</code>() that can make
- use of possible empty space before data (e.g. left after trimming of a
- link-layer header). The new <var class="Vt">mbuf chain</var> pointer or
- <code class="Dv">NULL</code> is in <var class="Fa">mbuf</var> after the
- call.</dd>
- <dt id="M_MOVE_PKTHDR"><a class="permalink" href="#M_MOVE_PKTHDR"><code class="Fn">M_MOVE_PKTHDR</code></a>(<var class="Fa">to</var>,
- <var class="Fa">from</var>)</dt>
- <dd>Using this macro is equivalent to calling
- <code class="Fn">m_move_pkthdr</code>(<var class="Fa">to</var>,
- <var class="Fa">from</var>).</dd>
- <dt id="M_WRITABLE"><a class="permalink" href="#M_WRITABLE"><code class="Fn">M_WRITABLE</code></a>(<var class="Fa">mbuf</var>)</dt>
- <dd>This macro will evaluate true if <var class="Fa">mbuf</var> is not marked
- <code class="Dv">M_RDONLY</code> and if either <var class="Fa">mbuf</var>
- does not contain external storage or, if it does, then if the reference
- count of the storage is not greater than 1. The
- <code class="Dv">M_RDONLY</code> flag can be set in
- <var class="Fa">mbuf-&gt;m_flags</var>. This can be achieved during setup
- of the external storage, by passing the <code class="Dv">M_RDONLY</code>
- bit as a <var class="Fa">flags</var> argument to the
- <code class="Fn">MEXTADD</code>() macro, or can be directly set in
- individual <var class="Vt">mbufs</var>.</dd>
- <dt id="MCHTYPE"><a class="permalink" href="#MCHTYPE"><code class="Fn">MCHTYPE</code></a>(<var class="Fa">mbuf</var>,
- <var class="Fa">type</var>)</dt>
- <dd>Change the type of <var class="Fa">mbuf</var> to
- <var class="Fa">type</var>. This is a relatively expensive operation and
- should be avoided.</dd>
-</dl>
-<p class="Pp">The functions are:</p>
-<dl class="Bl-ohang Bd-indent">
- <dt id="m_get"><a class="permalink" href="#m_get"><code class="Fn">m_get</code></a>(<var class="Fa">how</var>,
- <var class="Fa">type</var>)</dt>
- <dd>A function version of
- <a class="permalink" href="#MGET"><code class="Fn" id="MGET">MGET</code></a>()
- for non-critical paths.</dd>
- <dt id="m_get2"><a class="permalink" href="#m_get2"><code class="Fn">m_get2</code></a>(<var class="Fa">size</var>,
- <var class="Fa">how</var>, <var class="Fa">type</var>,
- <var class="Fa">flags</var>)</dt>
- <dd>Allocate an <var class="Vt">mbuf</var> with enough space to hold specified
- amount of data. If the size is larger than
- <code class="Dv">MJUMPAGESIZE</code>, <code class="Dv">NULL</code> will be
- returned.</dd>
- <dt id="m_get3"><a class="permalink" href="#m_get3"><code class="Fn">m_get3</code></a>(<var class="Fa">size</var>,
- <var class="Fa">how</var>, <var class="Fa">type</var>,
- <var class="Fa">flags</var>)</dt>
- <dd>Allocate an <var class="Vt">mbuf</var> with enough space to hold specified
- amount of data. If the size is larger than <code class="Dv">MJUM16BYTES,
- NULL</code> will be returned.</dd>
- <dt id="m_getm"><a class="permalink" href="#m_getm"><code class="Fn">m_getm</code></a>(<var class="Fa">orig</var>,
- <var class="Fa">len</var>, <var class="Fa">how</var>,
- <var class="Fa">type</var>)</dt>
- <dd>Allocate <var class="Fa">len</var> bytes worth of
- <var class="Vt">mbufs</var> and <var class="Vt">mbuf clusters</var> if
- necessary and append the resulting allocated <var class="Vt">mbuf
- chain</var> to the <var class="Vt">mbuf chain</var>
- <var class="Fa">orig</var>, if it is
- <span class="No">non-</span><code class="Dv">NULL</code>. If the
- allocation fails at any point, free whatever was allocated and return
- <code class="Dv">NULL</code>. If <var class="Fa">orig</var> is
- <span class="No">non-</span><code class="Dv">NULL</code>, it will not be
- freed. It is possible to use <code class="Fn">m_getm</code>() to either
- append <var class="Fa">len</var> bytes to an existing
- <var class="Vt">mbuf</var> or <var class="Vt">mbuf chain</var> (for
- example, one which may be sitting in a pre-allocated ring) or to simply
- perform an all-or-nothing <var class="Vt">mbuf</var> and
- <var class="Vt">mbuf cluster</var> allocation.</dd>
- <dt id="m_gethdr"><a class="permalink" href="#m_gethdr"><code class="Fn">m_gethdr</code></a>(<var class="Fa">how</var>,
- <var class="Fa">type</var>)</dt>
- <dd>A function version of <code class="Fn">MGETHDR</code>() for non-critical
- paths.</dd>
- <dt id="m_getcl"><a class="permalink" href="#m_getcl"><code class="Fn">m_getcl</code></a>(<var class="Fa">how</var>,
- <var class="Fa">type</var>, <var class="Fa">flags</var>)</dt>
- <dd>Fetch an <var class="Vt">mbuf</var> with a <var class="Vt">mbuf
- cluster</var> attached to it. If one of the allocations fails, the entire
- allocation fails. This routine is the preferred way of fetching both the
- <var class="Vt">mbuf</var> and <var class="Vt">mbuf cluster</var>
- together, as it avoids having to unlock/relock between allocations.
- Returns <code class="Dv">NULL</code> on failure.</dd>
- <dt id="m_getjcl"><a class="permalink" href="#m_getjcl"><code class="Fn">m_getjcl</code></a>(<var class="Fa">how</var>,
- <var class="Fa">type</var>, <var class="Fa">flags</var>,
- <var class="Fa">size</var>)</dt>
- <dd>This is like <code class="Fn">m_getcl</code>() but the specified
- <var class="Fa">size</var> of the cluster to be allocated must be one of
- <code class="Dv">MCLBYTES</code>, <code class="Dv">MJUMPAGESIZE</code>,
- <code class="Dv">MJUM9BYTES</code>, or
- <code class="Dv">MJUM16BYTES</code>.</dd>
- <dt id="m_free"><a class="permalink" href="#m_free"><code class="Fn">m_free</code></a>(<var class="Fa">mbuf</var>)</dt>
- <dd>Frees <var class="Vt">mbuf</var>. Returns <var class="Va">m_next</var> of
- the freed <var class="Vt">mbuf</var>.</dd>
-</dl>
-<p class="Pp">The functions below operate on <var class="Vt">mbuf
- chains</var>.</p>
-<dl class="Bl-ohang Bd-indent">
- <dt id="m_freem"><a class="permalink" href="#m_freem"><code class="Fn">m_freem</code></a>(<var class="Fa">mbuf</var>)</dt>
- <dd>Free an entire <var class="Vt">mbuf chain</var>, including any external
- storage.</dd>
- <dt id="m_adj"><a class="permalink" href="#m_adj"><code class="Fn">m_adj</code></a>(<var class="Fa">mbuf</var>,
- <var class="Fa">len</var>)</dt>
- <dd>Trim <var class="Fa">len</var> bytes from the head of an
- <var class="Vt">mbuf chain</var> if <var class="Fa">len</var> is positive,
- from the tail otherwise.</dd>
- <dt id="m_append"><a class="permalink" href="#m_append"><code class="Fn">m_append</code></a>(<var class="Fa">mbuf</var>,
- <var class="Fa">len</var>, <var class="Fa">cp</var>)</dt>
- <dd>Append <var class="Vt">len</var> bytes of data <var class="Vt">cp</var> to
- the <var class="Vt">mbuf chain</var>. Extend the mbuf chain if the new
- data does not fit in existing space.</dd>
- <dt id="m_prepend"><a class="permalink" href="#m_prepend"><code class="Fn">m_prepend</code></a>(<var class="Fa">mbuf</var>,
- <var class="Fa">len</var>, <var class="Fa">how</var>)</dt>
- <dd>Allocate a new <var class="Vt">mbuf</var> and prepend it to the
- <var class="Vt">mbuf chain</var>, handle <code class="Dv">M_PKTHDR</code>
- properly. <b class="Sy">Note</b>: It does not allocate any
- <var class="Vt">mbuf clusters</var>, so <var class="Fa">len</var> must be
- less than <code class="Dv">MLEN</code> or <code class="Dv">MHLEN</code>,
- depending on the <code class="Dv">M_PKTHDR</code> flag setting.</dd>
- <dt id="m_copyup"><a class="permalink" href="#m_copyup"><code class="Fn">m_copyup</code></a>(<var class="Fa">mbuf</var>,
- <var class="Fa">len</var>, <var class="Fa">dstoff</var>)</dt>
- <dd>Similar to <code class="Fn">m_pullup</code>() but copies
- <var class="Fa">len</var> bytes of data into a new mbuf at
- <var class="Fa">dstoff</var> bytes into the mbuf. The
- <var class="Fa">dstoff</var> argument aligns the data and leaves room for
- a link layer header. Returns the new <var class="Vt">mbuf chain</var> on
- success, and frees the <var class="Vt">mbuf chain</var> and returns
- <code class="Dv">NULL</code> on failure. <b class="Sy">Note</b>: The
- function does not allocate <var class="Vt">mbuf clusters</var>, so
- <var class="Fa">len + dstoff</var> must be less than
- <code class="Dv">MHLEN</code>.</dd>
- <dt><code class="Fn">m_pullup</code>(<var class="Fa">mbuf</var>,
- <var class="Fa">len</var>)</dt>
- <dd>Arrange that the first <var class="Fa">len</var> bytes of an
- <var class="Vt">mbuf chain</var> are contiguous and lay in the data area
- of <var class="Fa">mbuf</var>, so they are accessible with
- <code class="Fn">mtod</code>(<var class="Fa">mbuf</var>,
- <var class="Fa">type</var>). It is important to remember that this may
- involve reallocating some mbufs and moving data so all pointers
- referencing data within the old mbuf chain must be recalculated or made
- invalid. Return the new <var class="Vt">mbuf chain</var> on success,
- <code class="Dv">NULL</code> on failure (the <var class="Vt">mbuf
- chain</var> is freed in this case). <b class="Sy">Note</b>: It does not
- allocate any <var class="Vt">mbuf clusters</var>, so
- <var class="Fa">len</var> must be less than or equal to
- <code class="Dv">MHLEN</code>.</dd>
- <dt id="m_pulldown"><a class="permalink" href="#m_pulldown"><code class="Fn">m_pulldown</code></a>(<var class="Fa">mbuf</var>,
- <var class="Fa">offset</var>, <var class="Fa">len</var>,
- <var class="Fa">offsetp</var>)</dt>
- <dd>Arrange that <var class="Fa">len</var> bytes between
- <var class="Fa">offset</var> and <var class="Fa">offset + len</var> in the
- <var class="Vt">mbuf chain</var> are contiguous and lay in the data area
- of <var class="Fa">mbuf</var>, so they are accessible with
- <code class="Fn">mtod</code>() or <code class="Fn">mtodo</code>().
- <var class="Fa">len</var> must be smaller than, or equal to, the size of
- an <var class="Vt">mbuf cluster</var>. Return a pointer to an intermediate
- <var class="Vt">mbuf</var> in the chain containing the requested region;
- the offset in the data region of the <var class="Vt">mbuf chain</var> to
- the data contained in the returned mbuf is stored in
- <var class="Fa">*offsetp</var>. If <var class="Fa">offsetp</var> is NULL,
- the region may be accessed using
- <code class="Fn">mtod</code>(<var class="Fa">mbuf</var>,
- <var class="Fa">type</var>) or
- <code class="Fn">mtodo</code>(<var class="Fa">mbuf</var>,
- <var class="Fa">0</var>). If <var class="Fa">offsetp</var> is non-NULL,
- the region may be accessed using
- <code class="Fn">mtodo</code>(<var class="Fa">mbuf</var>,
- <var class="Fa">*offsetp</var>). The region of the mbuf chain between its
- beginning and <var class="Fa">offset</var> is not modified, therefore it
- is safe to hold pointers to data within this region before calling
- <code class="Fn">m_pulldown</code>().</dd>
- <dt id="m_copym"><a class="permalink" href="#m_copym"><code class="Fn">m_copym</code></a>(<var class="Fa">mbuf</var>,
- <var class="Fa">offset</var>, <var class="Fa">len</var>,
- <var class="Fa">how</var>)</dt>
- <dd>Make a copy of an <var class="Vt">mbuf chain</var> starting
- <var class="Fa">offset</var> bytes from the beginning, continuing for
- <var class="Fa">len</var> bytes. If <var class="Fa">len</var> is
- <code class="Dv">M_COPYALL</code>, copy to the end of the
- <var class="Vt">mbuf chain</var>. <b class="Sy">Note</b>: The copy is
- read-only, because the <var class="Vt">mbuf clusters</var> are not copied,
- only their reference counts are incremented.</dd>
- <dt id="m_copypacket"><a class="permalink" href="#m_copypacket"><code class="Fn">m_copypacket</code></a>(<var class="Fa">mbuf</var>,
- <var class="Fa">how</var>)</dt>
- <dd>Copy an entire packet including header, which must be present. This is an
- optimized version of the common case
- <code class="Fn">m_copym</code>(<var class="Fa">mbuf</var>,
- <var class="Fa">0</var>, <var class="Fa">M_COPYALL</var>,
- <var class="Fa">how</var>). <b class="Sy">Note</b>: the copy is read-only,
- because the <var class="Vt">mbuf clusters</var> are not copied, only their
- reference counts are incremented.</dd>
- <dt id="m_dup"><a class="permalink" href="#m_dup"><code class="Fn">m_dup</code></a>(<var class="Fa">mbuf</var>,
- <var class="Fa">how</var>)</dt>
- <dd>Copy a packet header <var class="Vt">mbuf chain</var> into a completely
- new <var class="Vt">mbuf chain</var>, including copying any
- <var class="Vt">mbuf clusters</var>. Use this instead of
- <code class="Fn">m_copypacket</code>() when you need a writable copy of an
- <var class="Vt">mbuf chain</var>.</dd>
- <dt id="m_copydata"><a class="permalink" href="#m_copydata"><code class="Fn">m_copydata</code></a>(<var class="Fa">mbuf</var>,
- <var class="Fa">offset</var>, <var class="Fa">len</var>,
- <var class="Fa">buf</var>)</dt>
- <dd>Copy data from an <var class="Vt">mbuf chain</var> starting
- <var class="Fa">off</var> bytes from the beginning, continuing for
- <var class="Fa">len</var> bytes, into the indicated buffer
- <var class="Fa">buf</var>.</dd>
- <dt id="m_copyback"><a class="permalink" href="#m_copyback"><code class="Fn">m_copyback</code></a>(<var class="Fa">mbuf</var>,
- <var class="Fa">offset</var>, <var class="Fa">len</var>,
- <var class="Fa">buf</var>)</dt>
- <dd>Copy <var class="Fa">len</var> bytes from the buffer
- <var class="Fa">buf</var> back into the indicated <var class="Vt">mbuf
- chain</var>, starting at <var class="Fa">offset</var> bytes from the
- beginning of the <var class="Vt">mbuf chain</var>, extending the
- <var class="Vt">mbuf chain</var> if necessary. <b class="Sy">Note</b>: It
- does not allocate any <var class="Vt">mbuf clusters</var>, just adds
- <var class="Vt">mbufs</var> to the <var class="Vt">mbuf chain</var>. It is
- safe to set <var class="Fa">offset</var> beyond the current
- <var class="Vt">mbuf chain</var> end: zeroed <var class="Vt">mbufs</var>
- will be allocated to fill the space.</dd>
- <dt id="m_length"><a class="permalink" href="#m_length"><code class="Fn">m_length</code></a>(<var class="Fa">mbuf</var>,
- <var class="Fa">last</var>)</dt>
- <dd>Return the length of the <var class="Vt">mbuf chain</var>, and optionally
- a pointer to the last <var class="Vt">mbuf</var>.</dd>
- <dt><code class="Fn">m_dup_pkthdr</code>(<var class="Fa">to</var>,
- <var class="Fa">from</var>, <var class="Fa">how</var>)</dt>
- <dd>Upon the function's completion, the <var class="Vt">mbuf</var>
- <var class="Fa">to</var> will contain an identical copy of
- <var class="Fa">from-&gt;m_pkthdr</var> and the per-packet attributes
- found in the <var class="Vt">mbuf chain</var> <var class="Fa">from</var>.
- The <var class="Vt">mbuf</var> <var class="Fa">from</var> must have the
- flag <code class="Dv">M_PKTHDR</code> initially set, and
- <var class="Fa">to</var> must be empty on entry.</dd>
- <dt><code class="Fn">m_move_pkthdr</code>(<var class="Fa">to</var>,
- <var class="Fa">from</var>)</dt>
- <dd>Move <var class="Va">m_pkthdr</var> and the per-packet attributes from the
- <var class="Vt">mbuf chain</var> <var class="Fa">from</var> to the
- <var class="Vt">mbuf</var> <var class="Fa">to</var>. The
- <var class="Vt">mbuf</var> <var class="Fa">from</var> must have the flag
- <code class="Dv">M_PKTHDR</code> initially set, and
- <var class="Fa">to</var> must be empty on entry. Upon the function's
- completion, <var class="Fa">from</var> will have the flag
- <code class="Dv">M_PKTHDR</code> and the per-packet attributes
- cleared.</dd>
- <dt id="m_fixhdr"><a class="permalink" href="#m_fixhdr"><code class="Fn">m_fixhdr</code></a>(<var class="Fa">mbuf</var>)</dt>
- <dd>Set the packet-header length to the length of the <var class="Vt">mbuf
- chain</var>.</dd>
- <dt id="m_devget"><a class="permalink" href="#m_devget"><code class="Fn">m_devget</code></a>(<var class="Fa">buf</var>,
- <var class="Fa">len</var>, <var class="Fa">offset</var>,
- <var class="Fa">ifp</var>, <var class="Fa">copy</var>)</dt>
- <dd>Copy data from a device local memory pointed to by
- <var class="Fa">buf</var> to an <var class="Vt">mbuf chain</var>. The copy
- is done using a specified copy routine <var class="Fa">copy</var>, or
- <a class="permalink" href="#bcopy"><code class="Fn" id="bcopy">bcopy</code></a>()
- if <var class="Fa">copy</var> is <code class="Dv">NULL</code>.</dd>
- <dt id="m_cat"><a class="permalink" href="#m_cat"><code class="Fn">m_cat</code></a>(<var class="Fa">m</var>,
- <var class="Fa">n</var>)</dt>
- <dd>Concatenate <var class="Fa">n</var> to <var class="Fa">m</var>. Both
- <var class="Vt">mbuf chains</var> must be of the same type.
- <var class="Fa">n</var> is not guaranteed to be valid after
- <code class="Fn">m_cat</code>() returns. <code class="Fn">m_cat</code>()
- does not update any packet header fields or free mbuf tags.</dd>
- <dt id="m_catpkt"><a class="permalink" href="#m_catpkt"><code class="Fn">m_catpkt</code></a>(<var class="Fa">m</var>,
- <var class="Fa">n</var>)</dt>
- <dd>A variant of <code class="Fn">m_cat</code>() that operates on packets.
- Both <var class="Fa">m</var> and <var class="Fa">n</var> must contain
- packet headers. <var class="Fa">n</var> is not guaranteed to be valid
- after <code class="Fn">m_catpkt</code>() returns.</dd>
- <dt id="m_split"><a class="permalink" href="#m_split"><code class="Fn">m_split</code></a>(<var class="Fa">mbuf</var>,
- <var class="Fa">len</var>, <var class="Fa">how</var>)</dt>
- <dd>Partition an <var class="Vt">mbuf chain</var> in two pieces, returning the
- tail: all but the first <var class="Fa">len</var> bytes. In case of
- failure, it returns <code class="Dv">NULL</code> and attempts to restore
- the <var class="Vt">mbuf chain</var> to its original state.</dd>
- <dt><code class="Fn">m_apply</code>(<var class="Fa">mbuf</var>,
- <var class="Fa">off</var>, <var class="Fa">len</var>,
- <var class="Fa">f</var>, <var class="Fa">arg</var>)</dt>
- <dd>Apply a function to an <var class="Vt">mbuf chain</var>, at offset
- <var class="Fa">off</var>, for length <var class="Fa">len</var> bytes.
- Typically used to avoid calls to <code class="Fn">m_pullup</code>() which
- would otherwise be unnecessary or undesirable. <var class="Fa">arg</var>
- is a convenience argument which is passed to the callback function
- <var class="Fa">f</var>.
- <p class="Pp" id="f">Each time
- <a class="permalink" href="#f"><code class="Fn">f</code></a>() is
- called, it will be passed <var class="Fa">arg</var>, a pointer to the
- <var class="Fa">data</var> in the current mbuf, and the length
- <var class="Fa">len</var> of the data in this mbuf to which the function
- should be applied.</p>
- <p class="Pp" id="m_apply">The function should return zero to indicate
- success; otherwise, if an error is indicated, then
- <a class="permalink" href="#m_apply"><code class="Fn">m_apply</code></a>()
- will return the error and stop iterating through the
- <var class="Vt">mbuf chain</var>.</p>
- </dd>
- <dt id="m_getptr"><a class="permalink" href="#m_getptr"><code class="Fn">m_getptr</code></a>(<var class="Fa">mbuf</var>,
- <var class="Fa">loc</var>, <var class="Fa">off</var>)</dt>
- <dd>Return a pointer to the mbuf containing the data located at
- <var class="Fa">loc</var> bytes from the beginning of the
- <var class="Vt">mbuf chain</var>. The corresponding offset into the mbuf
- will be stored in <var class="Fa">*off</var>.</dd>
- <dt><code class="Fn">m_defrag</code>(<var class="Fa">m0</var>,
- <var class="Fa">how</var>)</dt>
- <dd>Defragment an mbuf chain, returning the shortest possible chain of mbufs
- and clusters. If allocation fails and this can not be completed,
- <code class="Dv">NULL</code> will be returned and the original chain will
- be unchanged. Upon success, the original chain will be freed and the new
- chain will be returned. <var class="Fa">how</var> should be either
- <code class="Dv">M_WAITOK</code> or <code class="Dv">M_NOWAIT</code>,
- depending on the caller's preference.
- <p class="Pp">This function is especially useful in network drivers, where
- certain long mbuf chains must be shortened before being added to TX
- descriptor lists.</p>
- </dd>
- <dt id="m_collapse"><a class="permalink" href="#m_collapse"><code class="Fn">m_collapse</code></a>(<var class="Fa">m0</var>,
- <var class="Fa">how</var>, <var class="Fa">maxfrags</var>)</dt>
- <dd>Defragment an mbuf chain, returning a chain of at most
- <var class="Fa">maxfrags</var> mbufs and clusters. If allocation fails or
- the chain cannot be collapsed as requested, <code class="Dv">NULL</code>
- will be returned, with the original chain possibly modified. As with
- <a class="permalink" href="#m_defrag"><code class="Fn" id="m_defrag">m_defrag</code></a>(),
- <var class="Fa">how</var> should be one of
- <code class="Dv">M_WAITOK</code> or <code class="Dv">M_NOWAIT</code>.</dd>
- <dt id="m_unshare"><a class="permalink" href="#m_unshare"><code class="Fn">m_unshare</code></a>(<var class="Fa">m0</var>,
- <var class="Fa">how</var>)</dt>
- <dd>Create a version of the specified mbuf chain whose contents can be safely
- modified without affecting other users. If allocation fails and this
- operation can not be completed, <code class="Dv">NULL</code> will be
- returned. The original mbuf chain is always reclaimed and the reference
- count of any shared mbuf clusters is decremented.
- <var class="Fa">how</var> should be either
- <code class="Dv">M_WAITOK</code> or <code class="Dv">M_NOWAIT</code>,
- depending on the caller's preference. As a side-effect of this process the
- returned mbuf chain may be compacted.
- <p class="Pp">This function is especially useful in the transmit path of
- network code, when data must be encrypted or otherwise altered prior to
- transmission.</p>
- </dd>
-</dl>
-</section>
-</section>
-<section class="Sh">
-<h1 class="Sh" id="HARDWARE-ASSISTED_CHECKSUM_CALCULATION"><a class="permalink" href="#HARDWARE-ASSISTED_CHECKSUM_CALCULATION">HARDWARE-ASSISTED
- CHECKSUM CALCULATION</a></h1>
-<p class="Pp">This section currently applies to SCTP, TCP, and UDP over IP only.
- In order to save the host CPU resources, computing checksums is offloaded to
- the network interface hardware if possible. The
- <var class="Va">m_pkthdr</var> member of the leading
- <var class="Vt">mbuf</var> of a packet contains two fields used for that
- purpose, <var class="Vt">int</var> <var class="Va">csum_flags</var> and
- <var class="Vt">int</var> <var class="Va">csum_data</var>. The meaning of
- those fields depends on whether the packet is fragmented. Henceforth,
- <var class="Va">csum_flags</var> or <var class="Va">csum_data</var> of a
- packet will denote the corresponding field of the
- <var class="Va">m_pkthdr</var> member of the leading
- <var class="Vt">mbuf</var> in the <var class="Vt">mbuf chain</var>
- containing the packet.</p>
-<p class="Pp">When a packet is sent by SCTP, TCP, or UDP, the computation of the
- checksum is delayed until the outgoing interface has been determined for a
- packet. The interface-specific field
- <var class="Va">ifnet.if_data.ifi_hwassist</var> (see
- <a class="Xr">ifnet(9)</a>) is consulted by IP for the capabilities of the
- network interface selected for output to assist in computing checksums. The
- <var class="Va">csum_flags</var> field of the packet header is set to
- indicate which actions the interface is supposed to perform on it. The
- actions unsupported by the network interface are done in the software prior
- to passing the packet down to the interface driver; such actions will never
- be requested through <var class="Va">csum_flags</var>.</p>
-<p class="Pp">The flags demanding a particular action from an interface are as
- follows:</p>
-<div class="Bd-indent">
-<dl class="Bl-tag">
- <dt id="CSUM_IP"><a class="permalink" href="#CSUM_IP"><code class="Dv">CSUM_IP</code></a></dt>
- <dd>The IP header checksum is to be computed and stored in the corresponding
- field of the packet. The hardware is expected to know the format of an IP
- header to determine the offset of the IP checksum field.</dd>
- <dt id="CSUM_SCTP"><a class="permalink" href="#CSUM_SCTP"><code class="Dv">CSUM_SCTP</code></a></dt>
- <dd>The SCTP checksum is to be computed. (See below.)</dd>
- <dt id="CSUM_TCP"><a class="permalink" href="#CSUM_TCP"><code class="Dv">CSUM_TCP</code></a></dt>
- <dd>The TCP checksum is to be computed. (See below.)</dd>
- <dt id="CSUM_UDP"><a class="permalink" href="#CSUM_UDP"><code class="Dv">CSUM_UDP</code></a></dt>
- <dd>The UDP checksum is to be computed. (See below.)</dd>
-</dl>
-</div>
-<p class="Pp">Should a SCTP, TCP, or UDP checksum be offloaded to the hardware,
- the field <var class="Va">csum_data</var> will contain the byte offset of
- the checksum field relative to the end of the IP header. In the case of TCP
- or UDP, the checksum field will be initially set by the TCP or UDP
- implementation to the checksum of the pseudo header defined by the TCP and
- UDP specifications. In the case of SCTP, the checksum field will be
- initially set by the SCTP implementation to 0.</p>
-<p class="Pp">When a packet is received by an interface, it indicates the
- actions it has performed on a packet by setting one or more of the following
- flags in <var class="Va">csum_flags</var> associated with the packet:</p>
-<div class="Bd-indent">
-<dl class="Bl-tag">
- <dt id="CSUM_IP_CHECKED"><a class="permalink" href="#CSUM_IP_CHECKED"><code class="Dv">CSUM_IP_CHECKED</code></a></dt>
- <dd>The IP header checksum has been computed.</dd>
- <dt id="CSUM_IP_VALID"><a class="permalink" href="#CSUM_IP_VALID"><code class="Dv">CSUM_IP_VALID</code></a></dt>
- <dd>The IP header has a valid checksum. This flag can appear only in
- combination with <code class="Dv">CSUM_IP_CHECKED</code>.</dd>
- <dt id="CSUM_DATA_VALID"><a class="permalink" href="#CSUM_DATA_VALID"><code class="Dv">CSUM_DATA_VALID</code></a></dt>
- <dd>The checksum of the data portion of the IP packet has been computed and
- stored in the field <var class="Va">csum_data</var> in network byte
- order.</dd>
- <dt id="CSUM_PSEUDO_HDR"><a class="permalink" href="#CSUM_PSEUDO_HDR"><code class="Dv">CSUM_PSEUDO_HDR</code></a></dt>
- <dd>Can be set only along with <code class="Dv">CSUM_DATA_VALID</code> to
- indicate that the IP data checksum found in
- <var class="Va">csum_data</var> allows for the pseudo header defined by
- the TCP and UDP specifications. Otherwise the checksum of the pseudo
- header must be calculated by the host CPU and added to
- <var class="Va">csum_data</var> to obtain the final checksum to be used
- for TCP or UDP validation purposes.</dd>
-</dl>
-</div>
-<p class="Pp">If a particular network interface just indicates success or
- failure of SCTP, TCP, or UDP checksum validation without returning the exact
- value of the checksum to the host CPU, its driver can mark
- <code class="Dv">CSUM_DATA_VALID</code> in <var class="Va">csum_flags</var>
- as well as, for TCP and UDP, <code class="Dv">CSUM_PSEUDO_HDR</code> and set
- <var class="Va">csum_data</var> to <code class="Li">0xFFFF</code>
- hexadecimal to indicate a valid checksum. It is a peculiarity of the
- algorithm used that the Internet checksum calculated over any valid packet
- will be <code class="Li">0xFFFF</code> as long as the original checksum
- field is included. Note that for SCTP the value of
- <var class="Va">csum_data</var> is not relevant and
- <code class="Dv">CSUM_PSEUDO_HDR</code> in <var class="Va">csum_flags</var>
- is not set, since SCTP does not use a pseudo header checksum.</p>
-<p class="Pp">If IP delivers a packet with the flags
- <code class="Dv">CSUM_IP</code>, <code class="Dv">CSUM_SCTP</code>,
- <code class="Dv">CSUM_TCP</code>, or <code class="Dv">CSUM_UDP</code> set in
- <var class="Va">csum_flags</var> to a local IP, SCTP, TCP, or UDP stack, the
- packet will be processed without computing or validating the checksum, since
- the packet has not been on the wire. This can happen if the packet was
- handled by a virtual interface such as <a class="Xr">tap(4)</a> or
- <a class="Xr">epair(4)</a>.</p>
-</section>
-<section class="Sh">
-<h1 class="Sh" id="STRESS_TESTING"><a class="permalink" href="#STRESS_TESTING">STRESS
- TESTING</a></h1>
-<p class="Pp">When running a kernel compiled with the option
- <code class="Dv">MBUF_STRESS_TEST</code>, the following
- <a class="Xr">sysctl(8)</a>-controlled options may be used to create various
- failure/extreme cases for testing of network drivers and other parts of the
- kernel that rely on <var class="Vt">mbufs</var>.</p>
-<dl class="Bl-tag">
- <dt id="net.inet.ip.mbuf_frag_size"><var class="Va">net.inet.ip.mbuf_frag_size</var></dt>
- <dd>Causes
- <a class="permalink" href="#ip_output"><code class="Fn" id="ip_output">ip_output</code></a>()
- to fragment outgoing <var class="Vt">mbuf chains</var> into fragments of
- the specified size. Setting this variable to 1 is an excellent way to test
- the long <var class="Vt">mbuf chain</var> handling ability of network
- drivers.</dd>
- <dt id="kern.ipc.m_defragrandomfailures"><var class="Va">kern.ipc.m_defragrandomfailures</var></dt>
- <dd>Causes the function
- <a class="permalink" href="#m_defrag~2"><code class="Fn" id="m_defrag~2">m_defrag</code></a>()
- to randomly fail, returning <code class="Dv">NULL</code>. Any piece of
- code which uses <code class="Fn">m_defrag</code>() should be tested with
- this feature.</dd>
-</dl>
-</section>
-<section class="Sh">
-<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN
- VALUES</a></h1>
-<p class="Pp">See above.</p>
-</section>
-<section class="Sh">
-<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
- ALSO</a></h1>
-<p class="Pp"><a class="Xr">ifnet(9)</a>, <a class="Xr">mbuf_tags(9)</a></p>
-<p class="Pp"><cite class="Rs"><span class="RsA">S. J. Leffler</span>,
- <span class="RsA">W. N. Joy</span>, <span class="RsA">R. S. Fabry</span>,
- and <span class="RsA">M. J. Karels</span>, <span class="RsT">Networking
- Implementation Notes</span>, <i class="RsB">4.4BSD System Manager's Manual
- (SMM)</i>.</cite></p>
-</section>
-<section class="Sh">
-<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
-<p class="Pp"><var class="Vt">Mbufs</var> appeared in an early version of
- <span class="Ux">BSD</span>. Besides being used for network packets, they
- were used to store various dynamic structures, such as routing table
- entries, interface addresses, protocol control blocks, etc. In more recent
- <span class="Ux">FreeBSD</span> use of <var class="Vt">mbufs</var> is almost
- entirely limited to packet storage, with <a class="Xr">uma(9)</a> zones
- being used directly to store other network-related memory.</p>
-<p class="Pp">Historically, the <var class="Vt">mbuf</var> allocator has been a
- special-purpose memory allocator able to run in interrupt contexts and
- allocating from a special kernel address space map. As of
- <span class="Ux">FreeBSD 5.3</span>, the <var class="Vt">mbuf</var>
- allocator is a wrapper around <a class="Xr">uma(9)</a>, allowing caching of
- <var class="Vt">mbufs</var>, clusters, and <var class="Vt">mbuf</var> +
- cluster pairs in per-CPU caches, as well as bringing other benefits of slab
- allocation.</p>
-</section>
-<section class="Sh">
-<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
-<p class="Pp">The original <code class="Nm">mbuf</code> manual page was written
- by <span class="An">Yar Tikhiy</span>. The <a class="Xr">uma(9)</a>
- <var class="Vt">mbuf</var> allocator was written by
- <br/>
- <span class="An">Bosko Milekic</span>.</p>
-</section>
-</div>
-<table class="foot">
- <tr>
- <td class="foot-date">January 20, 2026</td>
- <td class="foot-os">FreeBSD 15.0</td>
- </tr>
-</table>
generated by cgit v1.2.3 (git 2.46.0) at 2026-05-15 12:51:24 +0000