Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MGET(9)		       FreeBSD Kernel Developer's Manual	       MGET(9)

NAME
     m_copym, m_free, m_get, MGET, m_getclr, m_gethdr, m_removehdr,
     m_resethdr, m_calchdrlen, MGETHDR,	m_prepend, M_PREPEND, m_pulldown,
     m_pullup, m_split,	m_makespace, m_getptr, m_adj, m_copyback, m_defrag,
     m_freem, m_freemp,	m_purge, m_reclaim, m_copydata,	m_cat, m_devget,
     m_apply, MCLGET, MCLGETL, MEXTADD,	m_align, M_READONLY, m_leadingspace,
     m_trailingspace, mtod, m_dup_pkt, m_dup_pkthdr -- kernel memory manage-
     ment for networking protocols

SYNOPSIS
     #include <sys/mbuf.h>

     struct mbuf *
     m_copym(struct mbuf *m, int off, int len, int wait);

     struct mbuf *
     m_free(struct mbuf	*m);

     struct mbuf *
     m_get(int how, int	type);

     MGET(struct mbuf *m, int how, int type);

     struct mbuf *
     m_getclr(int how, int type);

     void
     m_removehdr(struct	mbuf *m);

     void
     m_resethdr(struct mbuf *m);

     void
     m_calchdrlen(struct mbuf *m);

     struct mbuf *
     m_gethdr(int how, int type);

     MGETHDR(struct mbuf *m, int how, int type);

     struct mbuf *
     m_prepend(struct mbuf *m, int len,	int how);

     M_PREPEND(struct mbuf *m, int plen, int how);

     struct mbuf *
     m_pulldown(struct mbuf *m,	int off, int len, int *offp);

     struct mbuf *
     m_pullup(struct mbuf *n, int len);

     struct mbuf *
     m_split(struct mbuf *m0, int len0,	int wait);

     struct mbuf *
     m_makespace(struct	mbuf *m0, int skip, int	hlen, int *off);

     struct mbuf *
     m_getptr(struct mbuf *m, int loc, int *off);

     void
     m_adj(struct mbuf *mp, int	req_len);

     int
     m_copyback(struct mbuf *m0, int off, int len, const void *cp, int wait);

     int
     m_defrag(struct mbuf *m, int wait);

     struct mbuf *
     m_freem(struct mbuf *m);

     struct mbuf *
     m_freemp(struct mbuf **mp);

     void
     m_purge(struct mbuf *m);

     void
     m_reclaim(void);

     void
     m_copydata(struct mbuf *m,	int off, int len, void *cp);

     void
     m_cat(struct mbuf *m, struct mbuf *n);

     struct mbuf *
     m_devget(char *buf, int totlen, int off);

     int
     m_apply(struct mbuf *m, int off, int len,
	 int (*func)(caddr_t, caddr_t, unsigned	int), caddr_t fstate);

     MCLGET(struct mbuf	*m, int	how);

     struct mbuf *
     MCLGETL(struct mbuf *m, int how, int len);

     MEXTADD(struct mbuf *m, caddr_t buf, u_int	size, int flags,
	 void (*free)(caddr_t, u_int, void *), void *arg);

     void
     m_align(struct mbuf *m, int len);

     M_READONLY(struct mbuf *m);

     int
     m_leadingspace(struct mbuf	*m);

     int
     m_trailingspace(struct mbuf *m);

     struct mbuf *
     m_dup_pkt(struct mbuf *m, u_int adj, int how);

     int
     m_dup_pkthdr(struct mbuf *to, struct mbuf *from, int how);

     #define MSIZE	     256

     #define MLEN	     (MSIZE - sizeof(struct m_hdr))
     #define MHLEN	     (MLEN - sizeof(struct pkthdr))

     #define MAXMCLBYTES     (64 * 1024)
     #define MINCLSIZE	     (MHLEN + MLEN + 1)
     #define M_MAXCOMPRESS   (MHLEN / 2)

     #define MCLSHIFT	     11

     #define MCLBYTES	     (1	<< MCLSHIFT)
     #define MCLOFSET	     (MCLBYTES - 1)

     #define mtod(m,t)	     ((t)((m)->m_data))

     struct m_hdr {
	     struct  mbuf *mh_next;
	     struct  mbuf *mh_nextpkt;
	     caddr_t mh_data;
	     u_int   mh_len;
	     short   mh_type;
	     u_short mh_flags;
     #ifndef __LP64__
	     u_int   mh_pad;
     #endif
     };

     struct pkthdr {
	     void		     *ph_cookie;
	     SLIST_HEAD(, m_tag)      ph_tags;
	     int64_t		      ph_timestamp;
	     int		      len;
	     u_int16_t		      ph_tagsset;
	     u_int16_t		      ph_flowid;
	     u_int16_t		      csum_flags;
	     u_int16_t		      ether_vtag;
	     u_int		      ph_rtableid;
	     u_int		      ph_ifidx;
	     u_int8_t		      ph_loopcnt;
	     struct pkthdr_pf	      pf;
     };

     struct pkthdr_pf {
	     struct pf_state_key *statekey;
	     struct inpcb *inp;
	     u_int32_t qid;
	     u_int16_t tag;
	     u_int8_t  flags;
	     u_int8_t  routed;
	     u_int8_t  prio;
	     u_int8_t  pad[3];
     };

     struct mbuf_ext {
	     caddr_t ext_buf;
	     void    *ext_arg;
	     u_int   ext_free_fn;
	     u_int   ext_size;
	     struct mbuf *ext_nextref;
	     struct mbuf *ext_prevref;
     };

     struct mbuf {
	     struct  m_hdr m_hdr;
	     union {
		     struct {
			     struct  pkthdr MH_pkthdr;
			     union {
				     struct  mbuf_ext MH_ext;
				     char    MH_databuf[MHLEN];
			     } MH_dat;
		     } MH;
		     char    M_databuf[MLEN];
	     } M_dat;
     };

     #define m_next	     m_hdr.mh_next
     #define m_len	     m_hdr.mh_len
     #define m_data	     m_hdr.mh_data
     #define m_type	     m_hdr.mh_type
     #define m_flags	     m_hdr.mh_flags
     #define m_nextpkt	     m_hdr.mh_nextpkt
     #define m_pkthdr	     M_dat.MH.MH_pkthdr
     #define m_ext	     M_dat.MH.MH_dat.MH_ext
     #define m_pktdat	     M_dat.MH.MH_dat.MH_databuf
     #define m_dat	     M_dat.M_databuf

DESCRIPTION
     The mbuf functions	provide	a way to manage	the memory buffers used	by the
     kernel's networking subsystem.  Several functions and macros are used to
     allocate and deallocate mbufs, but	also to	get, inject, remove, copy,
     modify, prepend or	append data inside these mbufs.	 The size of an	mbuf
     is	defined	by MSIZE.

     An	mbuf structure is defined as an	m_hdr structure	followed by a union.
     The header	contains the following elements:

     mh_next	   A pointer to	the next mbuf in the mbuf chain.

     mh_nextpkt	   A pointer to	the next mbuf chain (i.e., packet) in the
		   queue.

     mh_data	   Indicates the address of the	beginning of data in the mbuf.

     mh_len	   Indicates the amount	of data	in the mbuf.

     mh_type	   Indicates the type of data contained	in the mbuf (see be-
		   low).

     mh_flags	   Flags (see below).

     The mh_type variable can take the following values:

	   MT_FREE	       the mbuf	should be on the free list.
	   MT_DATA	       the data	in the mbuf was	dynamically allocated.
	   MT_HEADER	       the data	contains a packet header.
	   MT_SONAME	       the data	is a socket name.
	   MT_SOOPTS	       the data	are socket options.
	   MT_FTABLE	       the data	is a fragment reassembly header.
	   MT_CONTROL	       the mbuf	contains extra-data protocol message.
	   MT_OOBDATA	       the data	consists of out-of-band	data.

     The mh_flags variable can take the	following values:

	   M_EXT	       mbuf has	associated external storage.
	   M_PKTHDR	       the mbuf	is the first that forms	a packet.
	   M_EOR	       end of record.
	   M_EXTWR	       external	storage	is writable.
	   M_PROTO1	       protocol-specific.
	   M_VLANTAG	       m_pkthdr.ether_vtag variable is valid.
	   M_LOOP	       packet has been sent from local machine.
	   M_BCAST	       packet sent/received as link-level broadcast.
	   M_MCAST	       packet sent/received as link-level multicast.
	   M_CONF	       packet was encrypted (ESP-transport).
	   M_AUTH	       packet was authenticated	(AH or ESP).
	   M_TUNNEL	       header was IP-in-IP encapsulated	by tunnel mode
			       IPsec.
	   M_ZEROIZE	       Zero the	data part of the mbufs in the mbuf
			       chain pointed to	by m_free.
	   M_COMP	       header was decompressed.
	   M_LINK0	       link layer specific flag.

     An	external cluster is used when the data to hold in the mbuf is large.
     The size of an external cluster is	between	MCLBYTES and MAXMCLBYTES.  A
     cluster should be used when the size of the data reach MINCLSIZE (the
     minimum size to be	held by	an external cluster).

     The combination of	the M_EXT and M_PKTHDR flags give four types of	mbuf.
     When none of these	constants are in use, the mbuf is a "normal" one,
     where the data part of the	mbuf has the following elements:

     m_dat	   buffer holding the data (size MLEN).

     When only M_PKTHDR	is set,	the data contained in the mbuf is a packet
     header.  The data itself is contained in the mbuf (just like the previous
     case), but	part of	the mbuf is used to store a packet header.  The	data
     part has then the following elements:

     m_pkthdr	   packet header, containing the length	of the data, a pointer
		   to the interface on which the data was received, checksum
		   information and list	of mbuf_tags(9).

     m_pktdat	   buffer holding the data (size MHLEN).

     The m_pkthdr.csum_flags variable can take the following values:

	   M_IPV4_CSUM_OUT     IPv4 checksum needed.
	   M_TCP_CSUM_OUT      TCP checksum needed.
	   M_UDP_CSUM_OUT      UDP checksum needed.
	   M_ICMP_CSUM_OUT     ICMP/ICMPv6 checksum needed.
	   M_IPV4_CSUM_IN_OK   IPv4 checksum verified.
	   M_IPV4_CSUM_IN_BAD  IPv4 checksum bad.
	   M_TCP_CSUM_IN_OK    TCP checksum verified.
	   M_TCP_CSUM_IN_BAD   TCP checksum bad.
	   M_UDP_CSUM_IN_OK    UDP checksum verified.
	   M_UDP_CSUM_IN_BAD   UDP checksum bad.
	   M_ICMP_CSUM_IN_OK   ICMP/ICMPv6 checksum verified.
	   M_ICMP_CSUM_IN_BAD  ICMP/ICMPv6 checksum bad.
	   M_IPV6_DF_OUT       Do not fragment IPv6 on output.

     The m_pkthdr.flowid variable can contain a	low resolution (15-bit)	clas-
     sification	of a flow or connection	that the current mbuf is part of.  If
     the flowid	is valid, it may be used as an alternative to hashing the
     packets content to	pick between different paths for the traffic.  The
     following masks can be ORed with the flowid:

	   M_FLOWID_VALID      The flow	ID has been set.
	   M_FLOWID_MASK       The flow	ID.

     When only M_EXT flag is set, an external storage buffer is	being used to
     hold the data, which is no	longer stored in the mbuf.  The	data part of
     the mbuf has now the following elements:

     m_pkthdr	   a packet header, just like the previous case, but it	is
		   empty.  No information is stored here.

     m_ext	   a structure containing information about the	external stor-
		   age buffer.	The information	consists of the	address	of the
		   external buffer, a pointer to the function used to free the
		   buffer, a pointer to	the arguments of the function, the
		   size	of the buffer, the type	of the buffer, and pointers to
		   the previous	and next mbufs using this cluster.

     When both the M_EXT and M_PKTHDR flags are	set, an	external storage buf-
     fer is being used to store	the data and this data contains	a packet
     header.  The structure used is the	same as	the previous one except	that
     the m_pkthdr element is not empty,	it contains the	same information as
     when M_PKTHDR is used alone.

     m_copym(struct mbuf *m, int off, int len, int wait)
	     Copy an mbuf chain	starting at off	bytes from the beginning and
	     continuing	for len	bytes.	If off is zero and m has the M_PKTHDR
	     flag set, the header is copied.  If len is	M_COPYALL the whole
	     mbuf is copied.  The wait parameter can be	M_WAIT or M_DONTWAIT.
	     It	does not copy clusters,	it just	increases their	reference
	     count.

     m_free(struct mbuf	*m)
	     Free the mbuf pointed to by m.  A pointer to the successor	of the
	     mbuf, if it exists, is returned by	the function.  If m is a NULL
	     pointer, no action	occurs and NULL	is returned.

     m_get(int how, int	type)
	     Return a pointer to an mbuf of the	type specified.	 If the	how
	     argument is M_WAITOK, the function	may call tsleep(9) to await
	     resources.	 If how	is M_DONTWAIT and resources are	not available,
	     m_get() returns NULL.

     MGET(struct mbuf *m, int how, int type)
	     Return a pointer to an mbuf in m of the type specified.  See
	     m_get() for a description of how.

     m_getclr(int how, int type)
	     Return a pointer to an mbuf of the	type specified,	and clear the
	     data area of the mbuf.  See m_get() for a description of how.

     m_removehdr(struct	mbuf *m)
	     Convert an	mbuf with packet header	to one without.	 Delete	all
	     pf(4) data	and all	tags attached to an mbuf.  Keep	the data and
	     mbuf chain, clear the packet header.

     m_resethdr(struct mbuf *m)
	     Delete all	pf(4) data and all tags	attached to an mbuf.  Keep the
	     data and mbuf chain, initialize the packet	header.

     m_calchdrlen(struct mbuf *m)
	     Set the packet header length to the sum of	all length values in
	     the mbuf chain.

     m_gethdr(int how, int type)
	     Return a pointer to an mbuf of the	type specified after initial-
	     izing it to contain a packet header.  See m_get() for a descrip-
	     tion of how.

     MGETHDR(struct mbuf *m, int how, int type)
	     Return a pointer to an mbuf of the	type specified after initial-
	     izing it to contain a packet header.  See m_get() for a descrip-
	     tion of how.

     m_prepend(struct mbuf *m, int len,	int how)
	     Prepend space of size plen	to the mbuf pointed to by m.  If nec-
	     essary allocate a new mbuf	and prepend it to the mbuf chain
	     pointed to	by m.  If m points to an mbuf with a packet header, it
	     is	moved to the new mbuf that has been prepended.	The return
	     value is a	pointer	on the new mbuf	chain.	If this	function fails
	     to	allocate a new mbuf, m is freed.  See m_get() for a descrip-
	     tion of how.

     M_PREPEND(struct mbuf *m, int plen, int how)
	     Prepend space of size plen	to the mbuf pointed to by m.  If a new
	     mbuf must be allocated, how specifies whether to wait or not.  If
	     this function fails to allocate a new mbuf, m is freed.

     m_pulldown(struct mbuf *m,	int off, int len, int *offp)
	     Ensure that the data in the mbuf chain starting at	off and	ending
	     at	off+len	will be	put in a continuous memory region.  If memory
	     must be allocated,	then it	will fail if the len argument is
	     greater than MAXMCLBYTES.	The pointer returned points to an mbuf
	     in	the chain and the new offset for data in this mbuf is *offp.
	     If	this function fails, m is freed.

     m_pullup(struct mbuf *n, int len)
	     Ensure that the data in the mbuf chain starting at	the beginning
	     of	the chain and ending at	len will be put	in continuous memory
	     region.  If memory	must be	allocated, then	it will	fail if	the
	     len argument is greater than MAXMCLBYTES.	If this	function
	     fails, n is freed.

     m_split(struct mbuf *m0, int len0,	int wait)
	     Split an mbuf chain in two	pieces,	returning a pointer to the
	     tail (which is made of the	previous mbuf chain except the first
	     len0 bytes).

     m_makespace(struct	mbuf *m0, int skip, int	hlen, int *off)
	     Make space	for a continuous memory	region of length hlen at skip
	     bytes into	the mbuf chain.	 On success, the mbuf of the continu-
	     ous memory	is returned together with an offset off	into the mbuf.
	     On	failure, NULL is returned and the mbuf chain may have been
	     modified.	The caller is assumed to always	free the chain.

     m_getptr(struct mbuf *m, int loc, int *off)
	     Returns a pointer to the mbuf containing the data located at loc
	     bytes of the beginning.  The offset in the	new mbuf is pointed to
	     by	off.

     m_adj(struct mbuf *mp, int	req_len)
	     Trims req_len bytes of data from the mbuf chain pointed to	by mp.
	     If	req_len	is positive, the data will be trimmed from the head of
	     the mbuf chain and	if it is negative, it will be trimmed from the
	     tail of the mbuf chain.

     m_copyback(struct mbuf *m0, int off, int len, const void *cp, int wait)
	     Copy data from a buffer pointed to	by cp back into	the mbuf chain
	     pointed to	by m0 starting at off bytes from the beginning,	ex-
	     tending the mbuf chain if necessary, sleeping for mbufs if	wait
	     is	M_WAIT.	 If M_NOWAIT is	set and	no mbufs are available,
	     m_copyback() returns ENOBUFS.  The	mbuf chain must	be initialized
	     properly, including setting m_len.

     m_defrag(struct mbuf *m, int wait)
	     Defragment	the data mbufs referenced by m by replacing the	chain
	     with a copy of their contents made	into a single mbuf or cluster.
	     wait specifies whether it can wait	or not for the replacement
	     storage.  m_defrag() returns 0 on success or ENOBUFS on failure.
	     The mbuf pointer m	remains	in existence and unchanged on failure.

     m_freem(struct mbuf *m)
	     Free the mbuf chain pointed to by m.  A pointer to	the next mbuf
	     in	the list linked	by m_nextpkt, if it exists, is returned	by the
	     function.	If m is	a NULL pointer,	no action occurs and NULL is
	     returned.

     m_freemp(struct mbuf **mp)
	     Set the input mbuf	pointer	to NULL	and call m_freem().

     m_purge(struct mbuf *m)
	     Free the list of mbufs linked by m_nextpkt	that is	pointed	to by
	     m.	 Each mbuf is freed by a call to m_freem().  If	m is a NULL
	     pointer, no action	occurs.

     m_reclaim(void)
	     Ask protocols to free unused memory space.

     m_copydata(struct mbuf *m,	int off, int len, void *cp)
	     Copy data from the	mbuf chain pointed to by m starting at off
	     bytes from	the beginning and continuing for len bytes into	the
	     buffer pointed to by cp.

     m_cat(struct mbuf *m, struct mbuf *n)
	     Concatenate the mbuf chain	pointed	to by n	to the mbuf chain
	     pointed to	by m.  The mbuf	chains must be of the same type.

     m_devget(char *buf, int totlen, int off)
	     Copy totlen bytes of data from device local memory	pointed	to by
	     buf.  The data is copied into an mbuf chain at offset off and a
	     pointer to	the head of the	chain is returned.  Returns NULL on
	     failure.

     m_apply(struct mbuf *m, int off, int len, int (*func)(caddr_t, caddr_t,
	     unsigned int), caddr_t fstate)
	     Apply the function	func to	the data in the	mbuf chain pointed to
	     by	m starting at off bytes	from the beginning and continuing for
	     len bytes.

     mtod(struct mbuf *m, datatype)
	     Return a pointer to the data contained in the specified mbuf m
	     cast to datatype.

     MCLGET(struct mbuf	*m, int	how)
	     Allocate and add an mbuf cluster to the mbuf pointed to by	m.  On
	     success, the flag M_EXT is	set in the mbuf.  See m_get() for a
	     description of how.

     MCLGETL(struct mbuf *m, int how, int len)
	     If	m is NULL, allocate it.	 Then allocate and add an mbuf cluster
	     of	length len to the mbuf pointed to by m.	 Returns either	the
	     mbuf m that was passed in,	or the newly allocated one which was
	     allocated;	in either case the flag	M_EXT is set in	the mbuf.  See
	     m_get() for a description of how.

     MEXTADD(struct mbuf *m, caddr_t buf, u_int	size, int flags, void
	     (*free)(caddr_t, u_int, void *), void *arg)
	     Add pre-allocated storage to the mbuf pointed to by m.  On	suc-
	     cess, the flag M_EXT is set in the	mbuf, and M_EXTWR is specified
	     in	flags.

     m_align(struct mbuf *m, int len)
	     Set the m_data pointer of the newly allocated mbuf	m to an	object
	     of	the specified size len at the end of this mbuf data area,
	     longword aligned.

     M_READONLY(struct mbuf *m)
	     Check if the data of the mbuf pointed to by m is read-only.  This
	     is	true for non-cluster external storage and for clusters that
	     are being referenced by more than one mbuf.

     m_leadingspace(struct mbuf	*m)
	     Compute the amount	of space available before the current start of
	     data in the mbuf pointed to by m.	If the data of the mbuf
	     pointed to	by m is	read-only then 0 is returned.

     m_trailingspace(struct mbuf *m)
	     Compute the amount	of space available after the end of data in
	     the mbuf pointed to by m.	If the data of the mbuf	pointed	to by
	     m is read-only then 0 is returned.

     m_dup_pkt(struct mbuf *m, u_int adj, int how)
	     Allocate a	new mbuf and storage and copy the packet data and
	     header, including mbuf tags, from m.  The data in the new mbuf
	     will be offset from the start of the storage by adj bytes.	 See
	     m_get() for a description of how.

     m_dup_pkthdr(struct mbuf *to, struct mbuf *from, int how)
	     Copy mbuf packet header, including	mbuf tags, from	from to	to.
	     See m_get() for a description of how.

CODE REFERENCES
     The mbuf management functions are implemented in the files
     sys/kern/uipc_mbuf.c and sys/kern/uipc_mbuf2.c.  The function prototypes
     and the macros are	located	in sys/sys/mbuf.h.

SEE ALSO
     netstat(1), mbuf_tags(9), mutex(9), spl(9)

     S.	J. Leffler, W. N. Joy, R. S. Fabry, and	M. J. Karels, "Networking
     Implementation Notes", 4.4BSD System Manager's Manual (SMM).

     Jun-Ichiro	Hagino,	"Mbuf issues in	4.4BSD IPv6/IPsec support (experiences
     from KAME IPv6/IPsec implementation)", Proceedings	of the Freenix Track:
     2000 USENIX Annual	Technical Conference, June 2000.

FreeBSD	13.0			 March 8, 2021			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | CODE REFERENCES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=mbuf&sektion=9&manpath=OpenBSD+6.9>

home | help