1 files changed, 721 insertions, 0 deletions
diff --git a/static/netbsd/man9/mbuf.9 b/static/netbsd/man9/mbuf.9
new file mode 100644
index 00000000..1e3948f6
--- /dev/null
+++ b/static/netbsd/man9/mbuf.9
@@ -0,0 +1,721 @@
+.\"	$NetBSD: mbuf.9,v 1.67 2022/06/28 20:12:52 rillig Exp $
+.\"
+.\" Copyright (c) 1997 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This documentation is derived from text contributed to The NetBSD Foundation
+.\" by S.P.Zeidler (aka stargazer).
+.\"
+.\" 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 NETBSD FOUNDATION, INC. 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 THE FOUNDATION 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.
+.\"
+.Dd June 28, 2022
+.Dt MBUF 9
+.Os
+.Sh NAME
+.Nm mbuf ,
+.Nm m_get ,
+.Nm m_gethdr ,
+.Nm m_devget ,
+.Nm m_copym ,
+.Nm m_copypacket ,
+.Nm m_copydata ,
+.Nm m_copyback ,
+.Nm m_copyback_cow ,
+.Nm m_cat ,
+.Nm m_dup ,
+.Nm m_makewritable ,
+.Nm m_pulldown ,
+.Nm m_pullup ,
+.Nm m_copyup ,
+.Nm m_split ,
+.Nm m_adj ,
+.Nm m_apply ,
+.Nm m_free ,
+.Nm m_freem ,
+.Nm mtod ,
+.Nm MGET ,
+.Nm MGETHDR ,
+.Nm MEXTMALLOC ,
+.Nm MEXTADD ,
+.Nm MCLGET ,
+.Nm m_copy_pkthdr ,
+.Nm m_move_pkthdr ,
+.Nm m_remove_pkthdr ,
+.Nm m_align ,
+.Nm M_LEADINGSPACE ,
+.Nm M_TRAILINGSPACE ,
+.Nm M_PREPEND ,
+.Nm MCHTYPE
+.Nd "functions and macros for managing memory used by networking code"
+.Sh SYNOPSIS
+.In sys/mbuf.h
+.Ft struct mbuf *
+.Fn m_get "int how" "int type"
+.Ft struct mbuf *
+.Fn m_gethdr "int how" "int type"
+.Ft struct mbuf *
+.Fn m_devget "char *buf" "int totlen" "int off" "struct ifnet *ifp"
+.Ft struct mbuf *
+.Fn m_copym "struct mbuf *m" "int off" "int len" "int wait"
+.Ft struct mbuf *
+.Fn m_copypacket "struct mbuf *m" "int how"
+.Ft void
+.Fn m_copydata "struct mbuf *m" "int off" "int len" "void *cp"
+.Ft void
+.Fn m_copyback "struct mbuf *m0" "int off" "int len" "void *cp"
+.Ft struct mbuf *
+.Fn m_copyback_cow "struct mbuf *m0" "int off" "int len" "void *cp" "int how"
+.Ft int
+.Fn m_makewritable "struct mbuf **mp" "int off" "int len" "int how"
+.Ft void
+.Fn m_cat "struct mbuf *m" "struct mbuf *n"
+.Ft struct mbuf *
+.Fn m_dup "struct mbuf *m" "int off" "int len" "int wait"
+.Ft struct mbuf *
+.Fn m_pulldown "struct mbuf *m" "int off" "int len" "int *offp"
+.Ft struct mbuf *
+.Fn m_pullup "struct mbuf *n" "int len"
+.Ft struct mbuf *
+.Fn m_copyup "struct mbuf *m" "int len" "int dstoff"
+.Ft struct mbuf *
+.Fn m_split "struct mbuf *m0" "int len" "int wait"
+.Ft void
+.Fn m_adj "struct mbuf *mp" "int req_len"
+.Ft int
+.Fn m_apply "struct mbuf *m" "int off" "int len" "int *f(void *, void *, unsigned int)" "void *arg"
+.Ft struct mbuf *
+.Fn m_free "struct mbuf *m"
+.Ft void
+.Fn m_freem "struct mbuf *m"
+.Ft datatype
+.Fn mtod "struct mbuf *m" "datatype"
+.Ft void
+.Fn MGET "struct mbuf *m" "int how" "int type"
+.Ft void
+.Fn MGETHDR "struct mbuf *m" "int how" "int type"
+.Ft void
+.Fn MEXTMALLOC "struct mbuf *m" "int len" "int how"
+.Ft void
+.Fn MEXTADD "struct mbuf *m" "void *buf" "int size" "int type" "void (*free)(struct mbuf *, void *, size_t, void *)" "void *arg"
+.Ft void
+.Fn MCLGET "struct mbuf *m" "int how"
+.Ft void
+.Fn m_copy_pkthdr "struct mbuf *to" "struct mbuf *from"
+.Ft void
+.Fn m_move_pkthdr "struct mbuf *to" "struct mbuf *from"
+.Ft void
+.Fn m_remove_pkthdr "struct mbuf *m"
+.Ft void
+.Fn m_align "struct mbuf *m" "int len"
+.Ft int
+.Fn M_LEADINGSPACE "struct mbuf *m"
+.Ft int
+.Fn M_TRAILINGSPACE "struct mbuf *m"
+.Ft void
+.Fn M_PREPEND "struct mbuf *m" "int plen" "int how"
+.Ft void
+.Fn MCHTYPE "struct mbuf *m" "int type"
+.Sh DESCRIPTION
+The
+.Nm
+functions and macros provide an easy and consistent way to handle
+a networking stack's memory management needs.
+An
+.Nm
+consists of a header and a data area.
+It is of a fixed size,
+.Dv MSIZE
+.Pq defined in Aq Pa machine/param.h ,
+which includes the size of the header.
+The header contains a pointer to the next
+.Nm
+in the
+.Sq "mbuf chain" ,
+a pointer to the next
+.Sq "mbuf chain" ,
+a pointer to the data area, the amount of data in this mbuf, its type
+and a
+.Dv flags
+field.
+.Pp
+The
+.Dv type
+variable can signify:
+.Bl -tag -compact -offset indent -width "XXXXXXXXXXX"
+.It Dv MT_FREE
+the mbuf should be on the ``free'' list
+.It Dv MT_DATA
+data was dynamically allocated
+.It Dv MT_HEADER
+data is a packet header
+.It Dv MT_SONAME
+data is a socket name
+.It Dv MT_SOOPTS
+data is socket options
+.It Dv MT_FTABLE
+data is the fragment reassembly header
+.It Dv MT_CONTROL
+mbuf contains ancillary \&(protocol control\&) data
+.It Dv MT_OOBDATA
+mbuf contains out-of-band data.
+.El
+.Pp
+The
+.Dv flags
+variable contains information describing the
+.Nm ,
+notably:
+.Bl -tag -compact -offset indent -width "XXXXXXXXXXX"
+.It Dv M_EXT
+has external storage
+.It Dv M_PKTHDR
+is start of record
+.It Dv M_EOR
+is end of record
+.El
+.Pp
+If an
+.Nm
+designates the start of a record
+.Pq Dv M_PKTHDR ,
+its
+.Dv flags
+field may contain additional information describing the content of
+the record:
+.Bl -tag -compact -offset indent -width "XXXXXXXXXXX"
+.It Dv M_BCAST
+sent/received as link-level broadcast
+.It Dv M_MCAST
+sent/received as link-level multicast
+.El
+.Pp
+An
+.Nm
+may add a single
+.Sq "mbuf cluster"
+of
+.Dv MCLBYTES
+bytes
+.Pq defined in Aq Pa machine/param.h ,
+which has no additional overhead
+and is used instead of the internal data area; this is done when at least
+.Dv MINCLSIZE
+bytes of data must be stored.
+.Pp
+When the
+.Dv M_EXT
+flag is set on an mbuf,
+the external storage area could be shared among multiple mbufs.
+Therefore, care must be taken when overwriting the data content of an
+mbuf, because its external storage could be considered as read-only.
+.Bl -tag -width compact
+.It Fn m_get "int how" "int type"
+Allocates an mbuf and initializes it to contain internal data.
+The
+.Fa how
+parameter is a choice of
+.Dv M_WAIT / M_DONTWAIT
+from caller.
+.Dv M_WAIT
+means the call cannot fail, but may take forever.
+The
+.Fa type
+parameter is an mbuf type.
+.It Fn m_gethdr "int how" "int type"
+Allocates an mbuf and initializes it to contain a packet header and internal
+data.
+The
+.Fa how
+parameter is a choice of
+.Dv M_WAIT / M_DONTWAIT
+from caller.
+The
+.Fa type
+parameter is an mbuf type.
+.It Fn m_devget "char *buf" "int totlen" "int off" "struct ifnet *ifp"
+Copies
+.Fa len
+bytes from device local memory into mbufs.
+If parameter
+.Fa off
+is non-zero, the packet is supposed to be trailer-encapsulated and
+.Fa off
+bytes plus the type and length fields will be skipped before copying.
+Returns the top of the mbuf chain it created.
+.It Fn m_copym "struct mbuf *m" "int off" "int len" "int wait"
+Creates a copy of an mbuf chain starting
+.Fa off
+bytes from the beginning, continuing for
+.Fa len
+bytes.
+If the
+.Fa len
+requested is
+.Dv M_COPYALL ,
+the complete mbuf chain will be copied.
+The
+.Fa wait
+parameter is a choice of
+.Dv M_WAIT / M_DONTWAIT
+from caller.
+.It Fn m_copypacket "struct mbuf *m" "int how"
+Copies an entire packet, including header.
+This function is an optimization of the common case
+.Li m_copym ( m , 0 , Dv M_COPYALL , Fa how ) .
+However, contrary to
+.Fn m_copym ,
+a header must be present.
+It is incorrect to use
+.Fn m_copypacket
+with an mbuf that does not have a header.
+.It Fn m_copydata "struct mbuf *m" "int off" "int len" "void *cp"
+Copies
+.Fa len
+bytes data from mbuf chain
+.Fa m
+into the buffer
+.Fa cp ,
+starting
+.Fa off
+bytes from the beginning.
+.It Fn m_copyback "struct mbuf *m0" "int off" "int len" "void *cp"
+Copies
+.Fa len
+bytes data from buffer
+.Fa cp
+back into the mbuf chain
+.Fa m0 ,
+starting
+.Fa off
+bytes from the beginning of the chain, extending the mbuf chain if necessary.
+.Fn m_copyback
+can only fail when extending the chain.
+The caller should check for this kind of failure
+by checking the resulting length of the chain in that case.
+It is an error to use
+.Fn m_copyback
+on read-only mbufs.
+.It Fn m_copyback_cow "struct mbuf *m0" "int off" "int len" "void *cp" \
+"int how"
+Copies
+.Fa len
+bytes data from buffer
+.Fa cp
+back into the mbuf chain
+.Fa m0
+as
+.Fn m_copyback
+does.
+Unlike
+.Fn m_copyback ,
+it is safe to use
+.Fn m_copyback_cow
+on read-only mbufs.
+If needed,
+.Fn m_copyback_cow
+automatically allocates new mbufs and adjusts the chain.
+On success, it returns a pointer to the resulting mbuf chain,
+and frees the original mbuf
+.Fa m0 .
+Otherwise, it returns
+.Dv NULL .
+The
+.Fa how
+parameter is a choice of
+.Dv M_WAIT / M_DONTWAIT
+from the caller.
+Unlike
+.Fn m_copyback ,
+extending the mbuf chain isn't supported.
+It is an error to attempt to extend the mbuf chain using
+.Fn m_copyback_cow .
+.It Fn m_makewritable "struct mbuf **mp" "int off" "int len" "int how"
+Rearranges an mbuf chain so that
+.Fa len
+bytes from offset
+.Fa off
+are writable.
+When it meets read-only mbufs, it allocates new mbufs, adjusts the chain as
+.Fn m_copyback_cow
+does, and copies the original content into them.
+.Fn m_makewritable
+does
+.Em not
+guarantee that all
+.Fa len
+bytes at
+.Fa off
+are consecutive.
+The
+.Fa how
+parameter is a choice of
+.Dv M_WAIT / M_DONTWAIT
+from the caller.
+.Fn m_makewritable
+preserves the contents of the mbuf chain even in the case of failure.
+It updates a pointer to the mbuf chain pointed to by
+.Fa mp .
+It returns 0 on success.
+Otherwise, it returns an error code, typically
+.Er ENOBUFS .
+.It Fn m_cat "struct mbuf *m" "struct mbuf *n"
+Concatenates mbuf chain
+.Fa n
+to
+.Fa m .
+Both chains must be of the same type; packet headers will
+.Em not
+be updated if present.
+.It Fn m_dup "struct mbuf *m" "int off" "int len" "int wait"
+Similarly to
+.Fn m_copym ,
+the function creates a copy of an mbuf chain starting
+.Fa off
+bytes from the beginning, continuing for
+.Fa len
+bytes.
+While
+.Fn m_copym
+tries to share external storage for mbufs with
+.Dv M_EXT
+flag,
+.Fn m_dup
+will deep-copy the whole data content into new mbuf chain
+and avoids shared external storage.
+.It Fn m_pulldown "struct mbuf *m" "int off" "int len" "int *offp"
+Rearranges an mbuf chain so that
+.Fa len
+bytes from offset
+.Fa off
+are contiguous and in the data area of an mbuf.
+The return value points to an mbuf in the middle of the mbuf chain
+.Fa m .
+If we call the return value
+.Fa n ,
+the contiguous data region is available at
+.Li "mtod(n, void *) + *offp" ,
+or
+.Li "mtod(n, void *)"
+if
+.Fa offp
+is
+.Dv NULL .
+The top of the mbuf chain
+.Fa m ,
+and mbufs up to
+.Fa off ,
+will not be modified.
+On successful return, it is guaranteed that the mbuf pointed to by
+.Fa n
+does not have a shared external storage,
+therefore it is safe to update the contiguous region.
+Returns
+.Dv NULL
+and frees the mbuf chain on failure.
+.Fa len
+must be smaller than or equal to
+.Dv MCLBYTES .
+.It Fn m_pullup "struct mbuf *m" "int len"
+Rearranges an mbuf chain so that
+.Fa len
+bytes are contiguous
+and in the data area of an mbuf (so that
+.Fn mtod
+will work for a structure of size
+.Fa len ) .
+Returns the resulting
+mbuf chain on success, frees it and returns
+.Dv NULL
+on failure.
+If there is room, it will add up to
+.Dv max_protohdr
+-
+.Fa len
+extra bytes to the
+contiguous region to possibly avoid being called again.
+.Fa len
+must be smaller or equal than
+.Dv MHLEN .
+.It Fn m_copyup "struct mbuf *m" "int len" "int dstoff"
+Similar to
+.Fn m_pullup
+but copies
+.Fa len
+bytes of data into a new mbuf at
+.Fa dstoff
+bytes into the mbuf.
+The
+.Fa dstoff
+argument aligns the data and leaves room for a link layer header.
+Returns the new
+mbuf chain on success, and frees the mbuf chain and returns
+.Dv NULL
+on failure.
+Note that
+the function does not allocate mbuf clusters, so
+.Fa len + dstoff
+must be less than
+.Dv MHLEN .
+.It Fn m_split "struct mbuf *m0" "int len" "int wait"
+Partitions an mbuf chain in two pieces, returning the tail,
+which is all but the first
+.Fa len
+bytes.
+In case of failure, it returns
+.Dv NULL
+and restores the chain to its original state.
+.It Fn m_adj "struct mbuf *mp" "int req_len"
+Shaves off
+.Fa req_len
+bytes from head or tail of the (valid) data area.
+If
+.Fa req_len
+is greater than zero, front bytes are being shaved off, if it's smaller,
+from the back (and if it is zero, the mbuf will stay bearded).
+This function does not move data in any way, but is used to manipulate the
+data area pointer and data length variable of the mbuf in a non-clobbering
+way.
+.It Fn m_apply "struct mbuf *m" "int off" "int len" "int (*f)(void *, void *, unsigned int)" "void *arg"
+Apply function
+.Fa f
+to the data in an mbuf chain starting
+.Fa off
+bytes from the beginning, continuing for
+.Fa len
+bytes.
+Neither
+.Fa off
+nor
+.Fa len
+may be negative.
+.Fa arg
+will be supplied as first argument for
+.Fa f ,
+the second argument will be the pointer to the data buffer of a
+packet (starting after
+.Fa off
+bytes in the stream), and the third argument is the amount
+of data in bytes in this call.
+If
+.Fa f
+returns something not equal to zero
+.Fn m_apply
+will bail out, returning the return code of
+.Fa f .
+Upon successful completion it will return zero.
+.It Fn m_free "struct mbuf *m"
+Frees mbuf
+.Fa m .
+.It Fn m_freem "struct mbuf *m"
+Frees the mbuf chain beginning with
+.Fa m .
+This function contains the elementary sanity check for a
+.Dv NULL
+pointer.
+.It Fn mtod "struct mbuf *m" "datatype"
+Returns a pointer to the data contained in the specified mbuf
+.Fa m ,
+type-casted to the specified data type
+.Fa datatype .
+.It Fn MGET "struct mbuf *m" "int how" "int type"
+Allocates mbuf
+.Fa m
+and initializes it to contain internal data.
+See
+.Fn m_get .
+.It Fn MGETHDR "struct mbuf *m" "int how" "int type"
+Allocates mbuf
+.Fa m
+and initializes it to contain a packet header.
+See
+.Fn m_gethdr .
+.It Fn MEXTMALLOC "struct mbuf *m" "int len" "int how"
+Allocates external storage of size
+.Fa len
+for mbuf
+.Fa m .
+The
+.Fa how
+parameter is a choice of
+.Dv M_WAIT / M_DONTWAIT
+from caller.
+The flag
+.Dv M_EXT
+is set upon success.
+.It Fn MEXTADD "struct mbuf *m" "void *buf" "int size" "int type" "void (*free)(struct mbuf *, void *, size_t, void *)" "void *arg"
+Adds pre-allocated external storage
+.Fa buf
+to a normal mbuf
+.Fa m ;
+the parameters
+.Fa size ,
+.Fa type ,
+.Fa free
+and
+.Fa arg
+describe the external storage.
+.Fa size
+is the size of the storage,
+.Fa type
+describes its
+.Xr malloc 9
+type,
+.Fa free
+is a free routine (if not the usual one), and
+.Fa arg
+is a possible argument to the free routine.
+The flag
+.Dv M_EXT
+is set upon success.
+If a free routine is specified, it will be called when the mbuf is freed.
+In the case of former, the first argument for a free routine is the mbuf
+.Fa m
+and the routine is expected to free it in addition to the external storage
+pointed by second argument.
+In the case of latter, the first argument for the routine is NULL.
+.It Fn MCLGET "struct mbuf *m" "int how"
+Allocates and adds an mbuf cluster to a normal mbuf
+.Fa m .
+The
+.Fa how
+parameter is a choice of
+.Dv M_WAIT / M_DONTWAIT
+from caller.
+The flag
+.Dv M_EXT
+is set upon success.
+.It Fn m_copy_pkthdr "struct mbuf *to" "struct mbuf *from"
+Copies the mbuf pkthdr from mbuf
+.Fa from
+to mbuf
+.Fa to .
+.Fa from
+must have the type flag
+.Dv M_PKTHDR
+set, and
+.Fa to
+must be empty.
+.It Fn m_move_pkthdr "struct mbuf *to" "struct mbuf *from"
+Moves the mbuf pkthdr from mbuf
+.Fa from
+to mbuf
+.Fa to .
+.Fa from
+must have the type flag
+.Dv M_PKTHDR
+set, and
+.Fa to
+must be empty.
+The flag
+.Dv M_PKTHDR
+in mbuf
+.Fa from
+will be cleared.
+.It Fn m_remove_pkthdr "struct mbuf *m"
+Removes the mbuf pkthdr from mbuf
+.Fa m .
+.Fa m
+must have the flag
+.Dv M_PKTHDR
+set.
+This flag will be cleared.
+.It Fn m_align "struct mbuf *m" "int len"
+Sets the data pointer of a newly allocated mbuf
+.Fa m
+to
+.Fa len
+bytes from the end of the mbuf data area, so that
+.Fa len
+bytes of data written to the mbuf
+.Fa m ,
+starting at the data pointer, will be aligned to the end of the data area.
+.It Fn M_LEADINGSPACE "struct mbuf *m"
+Returns the amount of space available before the current start of valid
+data in mbuf
+.Fa m .
+Returns 0 if the mbuf data part is shared across multiple mbufs
+.Pq i.e. not writable .
+.It Fn M_TRAILINGSPACE "struct mbuf *m"
+Returns the amount of space available after the current end of valid
+data in mbuf
+.Fa m .
+Returns 0 if the mbuf data part is shared across multiple mbufs
+.Pq i.e. not writable .
+.It Fn M_PREPEND "struct mbuf *m" "int plen" "int how"
+Prepends space of size
+.Fa plen
+to mbuf
+.Fa m .
+If a new mbuf must be allocated,
+.Fa how
+specifies whether to wait.
+If
+.Fa how
+is
+.Dv M_DONTWAIT
+and allocation fails, the original mbuf chain is freed and
+.Fa m
+is set to
+.Dv NULL .
+It is illegal for the
+.Fa plen
+parameter to be greater than
+.Dv MHLEN .
+.It Fn MCHTYPE "struct mbuf *m" "int type"
+Change mbuf
+.Fa m
+to new type
+.Fa type .
+.El
+.Sh CODE REFERENCES
+The
+.Nm
+management functions are implemented within the file
+.Pa sys/kern/uipc_mbuf.c .
+Function prototypes, and the functions implemented as macros
+are located in
+.Pa sys/sys/mbuf.h .
+.Sh SEE ALSO
+.Pa /usr/share/doc/reference/ref9/net ,
+.Xr netstat 1 ,
+.Xr m_tag 9 ,
+.Xr malloc 9
+.Rs
+.%A Jun-ichiro Hagino
+.%T "Mbuf issues in 4.4BSD IPv6/IPsec support (experiences from KAME IPv6/IPsec implementation)"
+.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
+.%D June 2000
+.Re
+.Sh AUTHORS
+.An -nosplit
+The original mbuf data structures were designed by Rob Gurwitz
+when he did the initial TCP/IP implementation at BBN.
+.Pp
+Further extensions and enhancements were made by Bill Joy, Sam Leffler,
+and Mike Karels at CSRG.
+.Pp
+Current implementation of external storage by
+.An Matt Thomas
+.Aq matt@3am-software.com
+and
+.An Jason R. Thorpe
+.Aq thorpej@NetBSD.org .