Mac Developer Library

Developer

kpi_mbuf.h Reference

Options
Deployment Target:

On This Page

kpi_mbuf.h Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

This header defines an API for interacting with mbufs. mbufs are the primary method of storing packets in the networking stack.

mbufs are used to store various items in the networking stack. The most common usage of an mbuf is to store a packet or data on a socket waiting to be sent or received. The mbuf is a contiguous structure with some header followed by some data. To store more data than would fit in an mbuf, external data is used. Most mbufs with external data use clusters to store the external data.

mbufs can be chained, contiguous data in a packet can be found by following the m_next chain. Packets may be bundled together using m_nextpacket. Many parts of the stack do not properly handle chains of packets. When in doubt, don't chain packets.

Included Headers

  • <sys/kernel_types.h>

  • <mach/vm_types.h>

Functions

  • Declaration

    Objective-C

    void mbuf_adj ( mbuf_t mbuf, int len );

    Parameters

    mbuf

    The mbuf chain to trim.

    len

    The number of bytes to trim from the mbuf chain.

    Discussion

    Trims len bytes from the mbuf. If the length is greater than zero, the bytes are trimmed from the front of the mbuf. If the length is less than zero, the bytes are trimmed from the end of the mbuf chain.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    errno_t mbuf_adjustlen ( mbuf_t mbuf, int amount );

    Parameters

    mbuf

    The mbuf to adjust.

    amount

    The number of bytes increment the length by.

    Return Value

    0 upon success otherwise the errno error.

    Discussion

    Adds amount to the mbuf len. Verifies that the new length is valid (greater than or equal to zero and less than maximum amount of data that may be stored in the mbuf). This function will not adjust the packet header length field or affect any other mbufs in a chain.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.5 and later.

  • Declaration

    Objective-C

    errno_t mbuf_align_32 ( mbuf_t mbuf, size_t len );

    Parameters

    mbuf

    The mbuf.

    len

    The minimum length of space that should follow the new data location.

    Return Value

    0 on success, errno error on failure.

    Discussion

    mbuf_align_32 is a replacement for M_ALIGN and MH_ALIGN. mbuf_align_32 will set the data pointer to a location aligned on a four byte boundry with at least 'len' bytes between the data pointer and the end of the data block.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    errno_t mbuf_alloccluster ( mbuf_how_t how, size_t *size, caddr_t *addr );

    Parameters

    how

    Blocking or non-blocking.

    size

    Pointer to size of requested cluster. Sizes up to 2048 will be rounded up to 2048; sizes greater than 2048 and up to 4096 will be rounded up to 4096. Sizes greater than 4096 will be rounded up to 16384.

    addr

    Pointer to the address of the requested cluster.

    Return Value

    0 on success or ENOMEM if failure. If the caller requests greater than 4096 bytes and the system is unable to fulfill the request due to the lack of jumbo clusters support based on the configuration, this routine will return ENOTSUP. In this case, the caller is advised to use 4096 bytes or smaller during subseqent requests.

    Discussion

    Allocate a cluster that can be later attached to an mbuf by calling mbuf_attachcluster(). The allocated cluster can also be freed (without being attached to an mbuf) by calling mbuf_freecluster(). At the moment this routine will either return a cluster of 2048, 4096 or 16384 bytes depending on the requested size. Note that clusters greater than 4096 bytes might not be available in all configurations; the caller must additionally check for ENOTSUP (see below).

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.5 and later.

  • Declaration

    Objective-C

    errno_t mbuf_allocpacket ( mbuf_how_t how, size_t packetlen, unsigned int *maxchunks, mbuf_t *mbuf );

    Parameters

    how

    Blocking or non-blocking

    packetlen

    The total length of the packet mbuf to be allocated. The length must be greater than zero.

    maxchunks

    An input/output pointer to the maximum number of mbufs segments making up the chain. On input, if maxchunks is NULL, or the value pointed to by maxchunks is zero, the packet will be made up of as few or as many buffer segments as necessary to fit the length. The allocation will fail with ENOBUFS if the number of segments requested is too small and the sum of the maximum size of each individual segment is less than the packet length. On output, if the allocation succeed and maxchunks is non-NULL, it will point to the actual number of segments allocated. Additional notes for packetlen greater than 4096 bytes: the caller may pass a non-NULL maxchunks and initialize it with zero such that upon success, it can find out whether or not the system configuration allows for larger than 4096 bytes cluster allocations, by checking on the value pointed to by maxchunks. E.g. a request for 9018 bytes may result in 1 chunk when jumbo clusters are available, or 3 chunks otherwise.

    Upon

    success, *mbuf will be a reference to the new mbuf.

    Return Value

    Returns 0 upon success or the following error code: EINVAL - Invalid parameter ENOMEM - Not enough memory available ENOBUFS - Buffers not big enough for the maximum number of chunks requested

    Discussion

    Allocate an mbuf chain to store a single packet of the requested length. According to the requested length, a chain of mbufs will be created. The mbuf type will be set to MBUF_TYPE_DATA. The caller may specify the maximum number of buffer.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    errno_t mbuf_allocpacket_list ( unsigned int numpkts, mbuf_how_t how, size_t packetlen, unsigned int *maxchunks, mbuf_t *mbuf );

    Parameters

    numpkts

    Number of packets to allocate

    how

    Blocking or non-blocking

    packetlen

    The total length of the packet mbuf to be allocated. The length must be greater than zero.

    maxchunks

    An input/output pointer to the maximum number of mbufs segments making up the chain. On input, if maxchunks is zero, or the value pointed to by maxchunks is zero, the packet will be made of as few or as many buffer segments as necessary to fit the length. The allocation will fail with ENOBUFS if the number of segments requested is too small and the sum of the maximum size of each individual segment is less than the packet length. On output, if the allocation succeed and maxchunks is non zero, it will point to the actual number of segments allocated. Additional notes for packetlen greater than 4096 bytes: the caller may pass a non-NULL maxchunks and initialize it with zero such that upon success, it can find out whether or not the system configuration allows for larger than 4096 bytes cluster allocations, by checking on the value pointed to by maxchunks. E.g. a request for 9018 bytes may result in 1 chunk when jumbo clusters are available, or 3 chunks otherwise.

    Upon

    success, *mbuf will be a reference to the new mbuf.

    Return Value

    Returns 0 upon success or the following error code: EINVAL - Invalid parameter ENOMEM - Not enough memory available ENOBUFS - Buffers not big enough for the maximum number of chunks requested

    Discussion

    Allocate a linked list of packets. According to the requested length, each packet will made of a chain of one or more mbufs. The mbuf type will be set to MBUF_TYPE_DATA. The caller may specify the maximum number of element for each mbuf chain making up a packet.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.5 and later.

  • Declaration

    Objective-C

    errno_t mbuf_attachcluster ( mbuf_how_t how, mbuf_type_t type, mbuf_t *mbuf, caddr_t extbuf, void (*extfree)(caddr_t, u_int, caddr_t), size_t extsize, caddr_t extarg );

    Parameters

    how

    Blocking or non-blocking.

    type

    The type of the mbuf if mbuf is non-NULL; otherwise ignored.

    mbuf

    Pointer to the address of the mbuf; if NULL, an mbuf will be allocated, otherwise, it must point to a valid mbuf address. If the user-supplied mbuf is already attached to a cluster, the current cluster will be freed before the mbuf gets attached to the supplied external buffer. Note that this routine may return a different mbuf_t than the one you passed in.

    extbuf

    Address of the external buffer.

    extfree

    Free routine for the external buffer; the caller is required to defined a routine that will be invoked when the mbuf is freed.

    extsize

    Size of the external buffer.

    extarg

    Private value that will be passed to the free routine when it is called at the time the mbuf is freed.

    Return Value

    0 on success EINVAL - Invalid parameter ENOMEM - Not enough memory available

    Discussion

    Attach an external buffer as a cluster for an mbuf. If mbuf points to a NULL mbuf_t, an mbuf will be allocated for you. If mbuf points to a non-NULL mbuf_t, the user-supplied mbuf will be used instead. The caller is responsible for allocating the external buffer by calling mbuf_alloccluster().

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.5 and later.

  • Declaration

    Objective-C

    errno_t mbuf_clear_csum_performed ( mbuf_t mbuf );

    Parameters

    mbuf

    The mbuf containing the packet.

    Return Value

    0 upon success otherwise the errno error.

    Discussion

    Clears the hardware checksum flags and values.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    errno_t mbuf_clear_csum_requested ( mbuf_t mbuf );

    Parameters

    mbuf

    The mbuf containing the packet.

    Return Value

    0 upon success otherwise the errno error.

    Discussion

    This function clears the checksum request flags.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    errno_t mbuf_clear_vlan_tag ( mbuf_t mbuf );

    Parameters

    mbuf

    The mbuf containing the packet.

    Return Value

    0 upon success otherwise the errno error.

    Discussion

    This function will clear any vlan tag associated with the mbuf.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    mbuf_t mbuf_concatenate ( mbuf_t dst, mbuf_t src );

    Parameters

    dst

    The destination mbuf chain.

    src

    The source mbuf chain.

    Return Value

    A pointer to the head of the concatenated mbuf chain. This should be treated as the updated destination mbuf chain; the caller must no longer refer to the original src or dst mbuf chain. Otherwise it returns NULL if the original dst mbuf chain is NULL.

    Discussion

    Concatenate mbuf chain src to dst using m_next and return a chain which represents the concatenated chain. The routine does not prevent two chains of different mbuf types to be concatenated, nor does it modify any packet header in the destination chain. Therefore, it's the responsibility of the caller to ensure that the resulted concatenated mbuf chain is correct for further usages.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.6 and later.

  • Declaration

    Objective-C

    errno_t mbuf_copy_pkthdr ( mbuf_t dest, const mbuf_t src );

    Parameters

    src

    The mbuf from which the packet header will be copied.

    mbuf

    The mbuf to which the packet header will be copied.

    Return Value

    0 upon success otherwise the errno error.

    Discussion

    Copies the packet header from src to dest.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    errno_t mbuf_copyback ( mbuf_t mbuf, size_t offset, size_t length, const void *data, mbuf_how_t how );

    Parameters

    mbuf

    The first mbuf in the chain to copy the data in to.

    offset

    Offset in bytes to skip before copying data.

    length

    The length, in bytes, of the data to copy in to the mbuf chain.

    data

    A pointer to data in the kernel's address space.

    how

    Blocking or non-blocking.

    Return Value

    0 upon success, EINVAL or ENOBUFS upon failure.

    Discussion

    Copies data from a buffer to an mbuf chain. mbuf_copyback will grow the chain to fit the specified buffer.

    If mbuf_copydata is unable to allocate enough mbufs to grow the chain, ENOBUFS will be returned. The mbuf chain will be shorter than expected but all of the data up to the end of the mbuf chain will be valid.

    If an offset is specified, mbuf_copyback will skip that many bytes in the mbuf chain before starting to write the buffer in to the chain. If the mbuf chain does not contain this many bytes, mbufs will be allocated to create the space.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    errno_t mbuf_copydata ( const mbuf_t mbuf, size_t offset, size_t length, void *out_data );

    Parameters

    mbuf

    The mbuf chain to copy data out of.

    offset

    The offset in to the mbuf to start copying.

    length

    The number of bytes to copy.

    out_data

    A pointer to the location where the data will be copied.

    Return Value

    0 upon success otherwise the errno error.

    Discussion

    Copies data out of an mbuf in to a specified buffer. If the data is stored in a chain of mbufs, the data will be copied from each mbuf in the chain until length bytes have been copied.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    errno_t mbuf_copym ( const mbuf_t src, size_t offset, size_t len, mbuf_how_t how, mbuf_t *new_mbuf );

    Parameters

    src

    The source mbuf.

    offset

    The offset in the mbuf to start copying from.

    len

    The the number of bytes to copy.

    how

    To block or not to block, that is a question.

    new_mbuf

    Upon success, the newly allocated mbuf.

    Return Value

    0 upon success otherwise the errno error.

    Discussion

    Copies len bytes from offset from src to a new mbuf. If the original mbuf contains a packet header, the new mbuf will contain similar packet header except for any tags which may be associated with the original mbuf. mbuf_dup() should be used instead if tags are to be copied to the new mbuf.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    void * mbuf_data ( mbuf_t mbuf );

    Parameters

    mbuf

    The mbuf.

    Return Value

    A pointer to the data in the mbuf.

    Discussion

    Returns a pointer to the start of data in this mbuf. There may be additional data on chained mbufs. The data you're looking for may not be virtually contiguous if it spans more than one mbuf. In addition, data that is virtually contiguous might not be represented by physically contiguous pages; see further comments in mbuf_data_to_physical. Use mbuf_len to determine the lenght of data available in this mbuf. If a data structure you want to access stradles two mbufs in a chain, either use mbuf_pullup to get the data contiguous in one mbuf or copy the pieces of data from each mbuf in to a contiguous buffer. Using mbuf_pullup has the advantage of not having to copy the data. On the other hand, if you don't make sure there is space in the mbuf, mbuf_pullup may fail and free the mbuf.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    addr64_t mbuf_data_to_physical ( void *ptr );

    Parameters

    ptr

    A pointer to data stored in an mbuf.

    Return Value

    The 64 bit physical address of the mbuf data or NULL if ptr does not point to data stored in an mbuf.

    Discussion

    mbuf_data_to_physical is a replacement for mcl_to_paddr. Given a pointer returned from mbuf_data of mbuf_datastart, mbuf_data_to_physical will return the phyical address for that block of data. Note that even though the data is in virtually contiguous span, the underlying physical pages might not be physically contiguous. Because of this, callers must ensure to call this routine for each page boundary. Device drivers that deal with DMA are strongly encouraged to utilize the IOMbufNaturalMemoryCursor and walk down the list of vectors instead of using this interface to obtain the physical address. Use of this routine is therefore discouraged.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    void * mbuf_datastart ( mbuf_t mbuf );

    Parameters

    mbuf

    The mbuf.

    Return Value

    A pointer to smallest possible value for data.

    Discussion

    Returns the start of the space set aside for storing data in an mbuf. An mbuf's data may come from a cluster or be embedded in the mbuf structure itself. The data pointer retrieved by mbuf_data may not be at the start of the data (mbuf_leadingspace will be non-zero). This function will return a pointer that matches mbuf_data() - mbuf_leadingspace().

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    errno_t mbuf_dup ( const mbuf_t src, mbuf_how_t how, mbuf_t *new_mbuf );

    Parameters

    src

    The source mbuf.

    how

    Blocking or non-blocking.

    new_mbuf

    Upon success, the newly allocated mbuf.

    Return Value

    0 upon success otherwise the errno error.

    Discussion

    Exactly duplicates an mbuf chain. If the original mbuf contains a packet header (including tags), the new mbuf will have the same packet header contents and a copy of each tag associated with the original mbuf.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    mbuf_flags_t mbuf_flags ( const mbuf_t mbuf );

    Parameters

    mbuf

    The mbuf.

    Return Value

    The flags.

    Discussion

    Returns the set flags.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    mbuf_t mbuf_free ( mbuf_t mbuf );

    Parameters

    mbuf

    The mbuf to free.

    Return Value

    The next mbuf in the chain.

    Discussion

    Frees a single mbuf. Not commonly used because it doesn't touch the rest of the mbufs on the chain.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    void mbuf_freecluster ( caddr_t addr, size_t size );

    Parameters

    addr

    The address of the cluster.

    size

    The actual size of the cluster.

    Discussion

    Free a cluster that was previously allocated by a call to mbuf_alloccluster(). The caller must pass the actual size of the cluster as returned by mbuf_alloccluster(), which at this point must be either 2048, 4096 or 16384 bytes.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.5 and later.

  • Declaration

    Objective-C

    void mbuf_freem ( mbuf_t mbuf );

    Parameters

    mbuf

    The first mbuf in the chain to free.

    Discussion

    Frees a chain of mbufs link through mnext.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    int mbuf_freem_list ( mbuf_t mbuf );

    Parameters

    mbuf

    The first mbuf in the linked list to free.

    Return Value

    The number of mbufs freed.

    Discussion

    Frees linked list of mbuf chains. Walks through mnextpackt and does the equivalent of mbuf_freem to each.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    errno_t mbuf_get ( mbuf_how_t how, mbuf_type_t type, mbuf_t *mbuf );

    Parameters

    how

    Blocking or non-blocking.

    type

    The type of the mbuf.

    mbuf

    The mbuf.

    Return Value

    0 on success, errno error on failure.

    Discussion

    Allocates an mbuf without a cluster for external data.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    errno_t mbuf_get_csum_requested ( mbuf_t mbuf, mbuf_csum_request_flags_t *request, u_int32_t *value );

    Parameters

    mbuf

    The mbuf containing the packet.

    request

    Flags indicating which checksums are being requested for this packet.

    value

    This parameter is currently unsupported.

    Return Value

    0 upon success otherwise the errno error.

    Discussion

    This function is used by the driver to determine which checksum operations should be performed in hardware.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    u_int32_t mbuf_get_mhlen ( void );

    Return Value

    The number of bytes of available data.

    Discussion

    This routine returns the number of data bytes in a packet header mbuf. This is equivalent to the legacy MHLEN macro.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.6 and later.

  • Declaration

    Objective-C

    u_int32_t mbuf_get_minclsize ( void );

    Return Value

    The minimum number of bytes before a cluster will be used.

    Discussion

    This routine returns the minimum number of data bytes before an external cluster is used. This is equivalent to the legacy MINCLSIZE macro.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.7 and later.

  • Declaration

    Objective-C

    u_int32_t mbuf_get_mlen ( void );

    Return Value

    The number of bytes of available data.

    Discussion

    This routine returns the number of data bytes in a normal mbuf, i.e. an mbuf that is not a packet header, nor one with an external cluster attached to it. This is equivalent to the legacy MLEN macro.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.6 and later.

  • Declaration

    Objective-C

    mbuf_traffic_class_t mbuf_get_traffic_class ( mbuf_t mbuf );

    Parameters

    mbuf

    The mbuf to get the traffic class of.

    Return Value

    The traffic class

    Discussion

    Get the traffic class of an mbuf packet

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.7 and later.

  • Declaration

    Objective-C

    errno_t mbuf_get_tso_requested ( mbuf_t mbuf, mbuf_tso_request_flags_t *request, u_int32_t *value );

    Parameters

    mbuf

    The mbuf containing the packet.

    request

    Flags indicating which values are being requested for this packet.

    value

    The requested value.

    Return Value

    0 upon success otherwise the errno error.

    Discussion

    This function is used by the driver to determine which checksum operations should be performed in hardware.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.6 and later.

  • Declaration

    Objective-C

    errno_t mbuf_get_vlan_tag ( mbuf_t mbuf, u_int16_t *vlan );

    Parameters

    mbuf

    The mbuf containing the packet.

    vlan

    The protocol family of the aux data to add.

    Return Value

    0 upon success otherwise the errno error. ENXIO indicates that the vlan tag is not set.

    Discussion

    This function is used by drivers that support hardware vlan tagging to determine which vlan this packet belongs to. To differentiate between the case where the vlan tag is zero and the case where there is no vlan tag, this function will return ENXIO when there is no vlan.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    errno_t mbuf_getcluster ( mbuf_how_t how, mbuf_type_t type, size_t size, mbuf_t *mbuf );

    Parameters

    how

    Blocking or non-blocking.

    type

    The type of the mbuf.

    size

    The size of the cluster to be allocated. Supported sizes for a cluster are be 2048, 4096, or 16384. Any other value with return EINVAL. Note that clusters greater than 4096 bytes might not be available in all configurations; the caller must additionally check for ENOTSUP (see below).

    mbuf

    The mbuf the cluster will be attached to.

    Return Value

    0 on success, errno error on failure. If you specified NULL for the mbuf, any intermediate mbuf that may have been allocated will be freed. If you specify an mbuf value in *mbuf, mbuf_mclget will not free it. EINVAL - Invalid parameter ENOMEM - Not enough memory available ENOTSUP - The caller had requested greater than 4096 bytes cluster and the system is unable to fulfill it due to the lack of jumbo clusters support based on the configuration. In this case, the caller is advised to use 4096 bytes or smaller during subsequent requests.

    Discussion

    Allocate a cluster of the requested size and attach it to an mbuf for use as external data. If mbuf points to a NULL mbuf_t, an mbuf will be allocated for you. If mbuf points to a non-NULL mbuf_t, mbuf_getcluster may return a different mbuf_t than the one you passed in.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    errno_t mbuf_gethdr ( mbuf_how_t how, mbuf_type_t type, mbuf_t *mbuf );

    Parameters

    how

    Blocking or non-blocking.

    type

    The type of the mbuf.

    mbuf

    The mbuf.

    Return Value

    0 on success, errno error on failure.

    Discussion

    Allocates an mbuf without a cluster for external data. Sets a flag to indicate there is a packet header and initializes the packet header.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    errno_t mbuf_getpacket ( mbuf_how_t how, mbuf_t *mbuf );

    Parameters

    how

    Blocking or non-blocking.

    mbuf

    Upon success, *mbuf will be a reference to the new mbuf.

    Return Value

    0 on success, errno error on failure.

    Discussion

    Allocate an mbuf, allocate and attach a cluster, and set the packet header flag.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    void mbuf_inbound_modified ( mbuf_t mbuf );

    Parameters

    mbuf

    The mbuf that has been modified.

    Discussion

    This function will clear the checksum flags to indicate that a hardware checksum should not be used. Any filter modifying data should call this function on an mbuf before passing the packet up the stack. If a filter modifies a packet in a way that affects any checksum, the filter is responsible for either modifying the checksum to compensate for the changes or verifying the checksum before making the changes and then modifying the data and calculating a new checksum only if the original checksum was valid.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    errno_t mbuf_inet6_cksum ( mbuf_t mbuf, int protocol, u_int32_t offset, u_int32_t length, u_int16_t *csum );

    Parameters

    mbuf

    The mbuf (or chain of mbufs) containing the packet.

    protocol

    A zero or non-zero value. A non-zero value specifies the transport protocol used for pseudo header checksum.

    offset

    A zero or non-zero value; if the latter, it specifies the offset of the transport header from the beginning of mbuf.

    length

    The total (non-zero) length of the transport segment.

    csum

    Pointer to the checksum variable; upon success, this routine will return the calculated Internet checksum through this variable. The caller must set it to a non-NULL value.

    Return Value

    0 upon success otherwise the errno error.

    Discussion

    @discussions Calculates 16-bit 1's complement Internet checksum of the transport segment with or without the pseudo header checksum of a given IPv6 packet. If the caller specifies a non-zero transport protocol, the checksum returned will also include the pseudo header checksum for the corresponding transport header. Otherwise, no header parsing will be done and the caller may use this to calculate the Internet checksum of an arbitrary span of data.

    This routine does not modify the contents of the packet. If the caller specifies a non-zero protocol and/or offset, the routine expects the complete protocol header(s) to be present at the beginning of the first mbuf.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.5 and later.

  • Declaration

    Objective-C

    errno_t mbuf_inet_cksum ( mbuf_t mbuf, int protocol, u_int32_t offset, u_int32_t length, u_int16_t *csum );

    Parameters

    mbuf

    The mbuf (or chain of mbufs) containing the packet.

    protocol

    A zero or non-zero value. A non-zero value specifies the transport protocol used for pseudo header checksum.

    offset

    A zero or non-zero value; if the latter, it specifies the offset of the transport header from the beginning of mbuf.

    length

    The total (non-zero) length of the transport segment.

    csum

    Pointer to the checksum variable; upon success, this routine will return the calculated Internet checksum through this variable. The caller must set it to a non-NULL value.

    Return Value

    0 upon success otherwise the errno error.

    Discussion

    @discussions Calculates 16-bit 1's complement Internet checksum of the transport segment with or without the pseudo header checksum of a given IPv4 packet. If the caller specifies a non-zero transport protocol, the checksum returned will also include the pseudo header checksum for the corresponding transport header. Otherwise, no header parsing will be done and the caller may use this to calculate the Internet checksum of an arbitrary span of data.

    This routine does not modify the contents of the packet. If the caller specifies a non-zero protocol and/or offset, the routine expects the complete protocol header to be present at the beginning of the first mbuf.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.5 and later.

  • Declaration

    Objective-C

    int mbuf_is_traffic_class_privileged ( mbuf_t mbuf );

    Parameters

    mbuf

    The mbuf to retrieve the status from.

    Return Value

    Non-zero if privileged, 0 otherwise.

    Discussion

    Returns the privileged status of the traffic class of the packet specified by the mbuf.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.8 and later.

  • Declaration

    Objective-C

    size_t mbuf_leadingspace ( const mbuf_t mbuf );

    Parameters

    mbuf

    The mbuf.

    Return Value

    The number of unused bytes at the start of the mbuf.

    Discussion

    Determines the space available in the mbuf proceeding the current data.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    size_t mbuf_len ( const mbuf_t mbuf );

    Parameters

    mbuf

    The mbuf.

    Return Value

    The length.

    Discussion

    Gets the length of data in this mbuf.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    size_t mbuf_maxlen ( const mbuf_t mbuf );

    Parameters

    mbuf

    The mbuf.

    Return Value

    The maximum lenght of data for this mbuf.

    Discussion

    Retrieves the maximum length of data that may be stored in this mbuf. This value assumes that the data pointer was set to the start of the possible range for that pointer (mbuf_data_start).

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    errno_t mbuf_mclget ( mbuf_how_t how, mbuf_type_t type, mbuf_t *mbuf );

    Parameters

    how

    Blocking or non-blocking.

    type

    The type of the mbuf.

    mbuf

    The mbuf the cluster will be attached to.

    Return Value

    0 on success, errno error on failure. If you specified NULL for the mbuf, any intermediate mbuf that may have been allocated will be freed. If you specify an mbuf value in *mbuf, mbuf_mclget will not free it.

    Discussion

    Allocate a cluster and attach it to an mbuf for use as external data. If mbuf points to a NULL mbuf_t, an mbuf will be allocated for you. If mbuf points to a non-NULL mbuf_t, mbuf_mclget may return a different mbuf_t than the one you passed in.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    int mbuf_mclhasreference ( mbuf_t mbuf );

    Parameters

    mbuf

    The mbuf with the cluster to test.

    Return Value

    0 if there is no reference by another mbuf, 1 otherwise.

    Discussion

    Check if a cluster of an mbuf is referenced by another mbuf. References may be taken, for example, as a result of a call to mbuf_split or mbuf_copym

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    mbuf_t mbuf_next ( const mbuf_t mbuf );

    Parameters

    mbuf

    The mbuf.

    Return Value

    The next mbuf in the chain.

    Discussion

    Returns the next mbuf in the chain.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    mbuf_t mbuf_nextpkt ( const mbuf_t mbuf );

    Parameters

    mbuf

    The mbuf.

    Return Value

    The nextpkt.

    Discussion

    Gets the next packet from the mbuf.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    void mbuf_outbound_finalize ( mbuf_t mbuf, u_int32_t protocol_family, size_t protocol_offset );

    Parameters

    mbuf

    The mbuf that should be finalized.

    protocol_family

    The protocol family of the packet in the mbuf.

    protocol_offset

    The offset from the start of the mbuf to the protocol header. For an IP packet with an ethernet header, this would be the length of an ethernet header.

    Discussion

    This function will "finalize" the packet allowing your code to inspect the final packet.

    There are a number of operations that are performed in hardware, such as calculating checksums. This function will perform in software the various opterations that were scheduled to be done in hardware. Future operations may include IPSec processing or vlan support. If you are redirecting a packet to a new interface which may not have the same hardware support or encapsulating the packet, you should call this function to force the stack to calculate and fill out the checksums. This will bypass hardware checksums but give you a complete packet to work with. If you need to inspect aspects of the packet which may be generated by hardware, you must call this function to get an aproximate final packet. If you plan to modify the packet in any way, you should call this function.

    This function should be called before modifying any outbound packets.

    This function may be called at various levels, in some cases additional headers may have already been prepended, such as the case of a packet seen by an interface filter. To handle this, the caller must pass the protocol family of the packet as well as the offset from the start of the packet to the protocol header.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    void mbuf_pkthdr_adjustlen ( mbuf_t mbuf, int amount );

    Parameters

    mbuf

    The mbuf containing the packet header.

    amount

    The number of bytes to adjust the packet header length field by.

    Discussion

    Adjusts the length of the packet in the packet header.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.5 and later.

  • Declaration

    Objective-C

    void * mbuf_pkthdr_header ( const mbuf_t mbuf );

    Parameters

    mbuf

    The mbuf containing the packet header.

    Return Value

    A pointer to the packet header.

    Discussion

    Returns a pointer to the packet header.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    size_t mbuf_pkthdr_len ( const mbuf_t mbuf );

    Parameters

    mbuf

    The mbuf containing the packet header with the length to be changed.

    Return Value

    The length, in bytes, of the packet.

    Discussion

    Returns the length as reported by the packet header.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    ifnet_t mbuf_pkthdr_rcvif ( const mbuf_t mbuf );

    Parameters

    mbuf

    The mbuf containing the packet header.

    Return Value

    A reference to the interface.

    Discussion

    Returns the interface the packet was received on. This funciton does not modify the reference count of the interface. The interface is only valid for as long as the mbuf is not freed and the rcvif for the mbuf is not changed. Take a reference on the interface that you will release later before doing any of the following: free the mbuf, change the rcvif, pass the mbuf to any function that may free the mbuf or change the rcvif.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    void mbuf_pkthdr_setheader ( mbuf_t mbuf, void *header );

    Parameters

    mbuf

    The mbuf containing the packet header.

    ifnet

    A pointer to the header.

    Return Value

    0 upon success otherwise the errno error.

    Discussion

    Sets the pointer to the packet header.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    void mbuf_pkthdr_setlen ( mbuf_t mbuf, size_t len );

    Parameters

    mbuf

    The mbuf containing the packet header.

    len

    The new length of the packet.

    Discussion

    Sets the length of the packet in the packet header.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    errno_t mbuf_pkthdr_setrcvif ( mbuf_t mbuf, ifnet_t ifp );

    Parameters

    mbuf

    The mbuf containing the packet header.

    ifnet

    A reference to an interface.

    Return Value

    0 upon success otherwise the errno error.

    Discussion

    Sets the interface the packet was received on.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    errno_t mbuf_prepend ( mbuf_t *mbuf, size_t len, mbuf_how_t how );

    Parameters

    mbuf

    The mbuf to prepend data to. This may change if a new mbuf must be allocated or may be NULL if the operation fails.

    len

    The length, in bytes, to be prepended to the mbuf.

    how

    Blocking or non-blocking.

    Return Value

    0 upon success otherwise the errno error.

    Discussion

    Prepend len bytes to an mbuf. If there is space (mbuf_leadingspace >= len), the mbuf's data ptr is changed and the same mbuf is returned. If there is no space, a new mbuf may be allocated and prepended to the mbuf chain. If the operation fails, the mbuf may be freed (*mbuf will be NULL).

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    errno_t mbuf_pulldown ( mbuf_t src, size_t *offset, size_t length, mbuf_t *location );

    Parameters

    src

    The start of the mbuf chain.

    offset

    Pass in a pointer to a value with the offset of the data you're interested in making contiguous. Upon success, this will be overwritten with the offset from the mbuf returned in location.

    length

    The length of data that should be made contiguous.

    location

    Upon success, *location will be the mbuf the data is in.

    Return Value

    0 upon success otherwise the errno error.

    Discussion

    Make length bytes at offset in the mbuf chain contiguous. Nothing before offset bytes in the chain will be modified. Upon return, location will be the mbuf the data is contiguous in and offset will be the offset in that mbuf at which the data is located. In the case of a failure, the mbuf chain will be freed.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    errno_t mbuf_pullup ( mbuf_t *mbuf, size_t len );

    Parameters

    mbuf

    The mbuf in the chain the data should be contiguous in.

    len

    The number of bytes to pull from the next mbuf(s).

    Return Value

    0 upon success otherwise the errno error. In the case of an error, the mbuf chain has been freed.

    Discussion

    Move the next len bytes in to mbuf from other mbufs in the chain. This is commonly used to get the IP and TCP or UDP header contiguous in the first mbuf. If mbuf_pullup fails, the entire mbuf chain will be freed.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    errno_t mbuf_set_csum_performed ( mbuf_t mbuf, mbuf_csum_performed_flags_t flags, u_int32_t value );

    Parameters

    mbuf

    The mbuf containing the packet.

    flags

    Flags indicating which hardware checksum operations were performed.

    value

    If the MBUF_CSUM_DID_DATA flag is set, value should be set to the value of the TCP or UDP header as calculated by the hardware.

    Return Value

    0 upon success otherwise the errno error.

    Discussion

    This is used by the driver to indicate to the stack which checksum operations were performed in hardware.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    errno_t mbuf_set_traffic_class ( mbuf_t mbuf, mbuf_traffic_class_t tc );

    Parameters

    mbuf

    The mbuf to set the traffic class on. @tc The traffic class

    Return Value

    0 on success, EINVAL if bad parameter is passed

    Discussion

    Set the traffic class of an mbuf packet.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.7 and later.

  • Declaration

    Objective-C

    errno_t mbuf_set_vlan_tag ( mbuf_t mbuf, u_int16_t vlan );

    Parameters

    mbuf

    The mbuf containing the packet.

    vlan

    The protocol family of the aux data to add.

    Return Value

    0 upon success otherwise the errno error.

    Discussion

    This function is used by interfaces that support vlan tagging in hardware. This function will set properties in the mbuf to indicate which vlan the packet was received for.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    errno_t mbuf_setdata ( mbuf_t mbuf, void *data, size_t len );

    Parameters

    mbuf

    The mbuf.

    data

    The new pointer value for data.

    len

    The new length of data in the mbuf.

    Return Value

    0 on success, errno error on failure.

    Discussion

    Sets the data and length values for an mbuf. The data value must be in a valid range. In the case of an mbuf with a cluster, the data value must point to a location in the cluster and the data value plus the length, must be less than the end of the cluster. For data embedded directly in an mbuf (no cluster), the data value must fall somewhere between the start and end of the data area in the mbuf and the data + length must also be in the same range.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    errno_t mbuf_setflags ( mbuf_t mbuf, mbuf_flags_t flags );

    Parameters

    mbuf

    The mbuf.

    flags

    The flags that should be set, all other flags will be cleared. Certain flags such as MBUF_EXT cannot be altered.

    Return Value

    0 upon success otherwise the errno error.

    Discussion

    Sets the set of set flags.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    errno_t mbuf_setflags_mask ( mbuf_t mbuf, mbuf_flags_t flags, mbuf_flags_t mask );

    Parameters

    mbuf

    The mbuf.

    flags

    The flags that should be set or cleared. Certain flags such as MBUF_EXT cannot be altered.

    mask

    The mask controlling which flags will be modified.

    Return Value

    0 upon success otherwise the errno error.

    Discussion

    Useful for setting or clearing individual flags. Easier than calling mbuf_setflags(m, mbuf_flags(m) | M_FLAG).

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    void mbuf_setlen ( mbuf_t mbuf, size_t len );

    Parameters

    mbuf

    The mbuf.

    len

    The new length.

    Return Value

    0 upon success otherwise the errno error.

    Discussion

    Sets the length of data in this packet. Be careful to not set the length over the space available in the mbuf.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    errno_t mbuf_setnext ( mbuf_t mbuf, mbuf_t next );

    Parameters

    mbuf

    The mbuf.

    next

    The new next mbuf.

    Return Value

    0 upon success otherwise the errno error.

    Discussion

    Sets the next mbuf in the chain.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    void mbuf_setnextpkt ( mbuf_t mbuf, mbuf_t nextpkt );

    Parameters

    mbuf

    The mbuf.

    nextpkt

    The new next packet.

    Discussion

    Sets the next packet attached to this mbuf.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    errno_t mbuf_settype ( mbuf_t mbuf, mbuf_type_t new_type );

    Parameters

    mbuf

    The mbuf.

    new_type

    The new type.

    Return Value

    0 upon success otherwise the errno error.

    Discussion

    Sets the type of mbuf.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    errno_t mbuf_split ( mbuf_t src, size_t offset, mbuf_how_t how, mbuf_t *new_mbuf );

    Parameters

    src

    The mbuf to be split.

    offset

    The offset in the buffer where the mbuf should be split.

    how

    Blocking or non-blocking.

    new_mbuf

    Upon success, the second half of the split mbuf chain.

    Return Value

    0 upon success otherwise the errno error. In the case of failure, the original mbuf chain passed in to src will be preserved.

    Discussion

    Split an mbuf chain at a specific offset.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    void mbuf_stats ( struct mbuf_stat *stats );

    Parameters

    stats

    Storage to copy the stats in to.

    Discussion

    Get the mbuf statistics.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    errno_t mbuf_tag_allocate ( mbuf_t mbuf, mbuf_tag_id_t module_id, mbuf_tag_type_t type, size_t length, mbuf_how_t how, void **data_p );

    Parameters

    mbuf

    The mbuf to attach this tag to.

    module_id

    A module identifier returned by mbuf_tag_id_find.

    type

    A 16 bit type value. For a given module_id, you can use a number of different tag types.

    length

    The length, in bytes, to allocate for storage that will be associated with this tag on this mbuf.

    how

    Indicate whether you want to block and wait for memory if memory is not immediately available.

    data_p

    Upon successful return, *data_p will point to the buffer allocated for the mtag.

    Return Value

    0 upon success otherwise the errno error.

    Discussion

    Allocate an mbuf tag. Mbuf tags allow various portions of the stack to tag mbufs with data that will travel with the mbuf through the stack.

    Tags may only be added to mbufs with packet headers (MBUF_PKTHDR flag is set). Mbuf tags are freed when the mbuf is freed or when mbuf_tag_free is called.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    errno_t mbuf_tag_find ( mbuf_t mbuf, mbuf_tag_id_t module_id, mbuf_tag_type_t type, size_t *length, void **data_p );

    Parameters

    mbuf

    The mbuf the tag is attached to.

    module_id

    A module identifier returned by mbuf_tag_id_find.

    type

    The 16 bit type of the tag to find.

    length

    Upon success, the length of data will be store in *length.

    data_p

    Upon successful return, *data_p will point to the buffer allocated for the mtag.

    Return Value

    0 upon success otherwise the errno error.

    Discussion

    Find the data associated with an mbuf tag.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    void mbuf_tag_free ( mbuf_t mbuf, mbuf_tag_id_t module_id, mbuf_tag_type_t type );

    Parameters

    mbuf

    The mbuf the tag was allocated on.

    module_id

    The ID of the tag to free.

    type

    The type of the tag to free.

    Discussion

    Frees a previously allocated mbuf tag.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    errno_t mbuf_tag_id_find ( const char *module_string, mbuf_tag_id_t *module_id );

    Parameters

    module_string

    A unique string identifying your module. Example: com.apple.nke.SharedIP.

    module_id

    Upon return, a unique identifier for use with mbuf_tag_* functions. This identifier is valid until the machine is rebooted.

    Return Value

    0 upon success otherwise the errno error.

    Discussion

    Lookup the module id for a string. If there is no module id assigned to this string, a new module id will be assigned. The string should be the bundle id of the kext. In the case of a tag that will be shared across multiple kexts, a common bundle id style string should be used.

    The lookup operation is not optimized. A module should call this function once during startup and chache the module id. The module id will not be resassigned until the machine reboots.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    size_t mbuf_trailingspace ( const mbuf_t mbuf );

    Parameters

    mbuf

    The mbuf.

    Return Value

    The number of unused bytes following the current data.

    Discussion

    Determines the space available in the mbuf following the current data.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    mbuf_type_t mbuf_type ( const mbuf_t mbuf );

    Parameters

    mbuf

    The mbuf.

    Return Value

    The type.

    Discussion

    Gets the type of mbuf.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.4 and later.

Data Types

See the Overview section above for header-level documentation.

  • Traffic class of a packet

    Declaration

    Objective-C

    typedef enum { MBUF_TC_BE = 0, MBUF_TC_BK = 1, MBUF_TC_VI = 2, MBUF_TC_VO = 3 } mbuf_traffic_class_t;

    Constants

    • MBUF_TC_BE

      MBUF_TC_BE

      Best effort, normal class.

      Available in OS X v10.7 and later.

    • MBUF_TC_BK

      MBUF_TC_BK

      Background, low priority or bulk traffic.

      Available in OS X v10.7 and later.

    • MBUF_TC_VI

      MBUF_TC_VI

      Interactive video, constant bit rate, low latency.

      Available in OS X v10.7 and later.

    • MBUF_TC_VO

      MBUF_TC_VO

      Interactive voice, constant bit rate, lowest latency.

      Available in OS X v10.7 and later.

    Discussion

    Property that represent the category of traffic of a packet. This information may be used by the driver and at the link level.

    Import Statement

    Objective-C

    #include <kpi_mbuf.h>;

    Availability

    Available in OS X v10.7 and later.

  • Declaration

    Objective-C

    struct mbuf_stat { u_int32_t mbufs; /* mbufs obtained from page pool */ u_int32_t clusters; /* clusters obtained from page pool */ u_int32_t clfree; /* free clusters */ u_int32_t drops; /* times failed to find space */ u_int32_t wait; /* times waited for space */ u_int32_t drain; /* times drained protocols for space */ u_short mtypes[256]; /* type specific mbuf allocations */ u_int32_t mcfail; /* times m_copym failed */ u_int32_t mpfail; /* times m_pullup failed */ u_int32_t msize; /* length of an mbuf */ u_int32_t mclbytes; /* length of an mbuf cluster */ u_int32_t minclsize; /* min length of data to allocate a cluster */ u_int32_t mlen; /* length of data in an mbuf */ u_int32_t mhlen; /* length of data in a header mbuf */ u_int32_t bigclusters; /* number of big clusters */ u_int32_t bigclfree; /* number of big clustser free */ u_int32_t bigmclbytes; /* length of data in a big cluster */ };

    Fields

    mbufs

    Number of mbufs (free or otherwise).

    clusters

    Number of clusters (free or otherwise).

    clfree

    Number of free clusters.

    drops

    Number of times allocation failed.

    wait

    Number of times allocation blocked.

    drain

    Number of times protocol drain functions were called.

    mtypes

    An array of counts of each type of mbuf allocated.

    mcfail

    Number of times m_copym failed.

    mpfail

    Number of times m_pullup failed.

    msize

    Length of an mbuf.

    mclbytes

    Length of an mbuf cluster.

    minclsize

    Minimum length of data to allocate a cluster. Anything smaller than this should be placed in chained mbufs.

    mlen

    Length of data in an mbuf.

    mhlen

    Length of data in an mbuf with a packet header.

    bigclusters

    Number of big clusters.

    bigclfree

    Number of unused big clusters.

    bigmclbytes

    Length of a big mbuf cluster.

    Discussion

    The mbuf_stat contains mbuf statistics.

    Availability

    Available in OS X v10.6 and later.

Constants

See the Overview section above for header-level documentation.

  • Checksum performed/requested flags.

    Declaration

    Objective-C

    enum { MBUF_CSUM_DID_IP = 0x0100, MBUF_CSUM_IP_GOOD = 0x0200, MBUF_CSUM_DID_DATA = 0x0400, MBUF_CSUM_PSEUDO_HDR = 0x0800 };

    Constants

    • MBUF_CSUM_DID_IP

      MBUF_CSUM_DID_IP

      Indicates that the driver/hardware verified the IP checksum in hardware.

      Available in OS X v10.4 and later.

    • MBUF_CSUM_IP_GOOD

      MBUF_CSUM_IP_GOOD

      Indicates whether or not the IP checksum was good or bad. Only valid when MBUF_CSUM_DID_IP is set.

      Available in OS X v10.4 and later.

    • MBUF_CSUM_DID_DATA

      MBUF_CSUM_DID_DATA

      Indicates that the TCP or UDP checksum was calculated. The value for the checksum calculated in hardware should be passed as the second parameter of mbuf_set_csum_performed. The hardware calculated checksum value can be retrieved using the second parameter passed to mbuf_get_csum_performed. This should be done for IPv4 or IPv6.

      Available in OS X v10.4 and later.

    • MBUF_CSUM_PSEUDO_HDR

      MBUF_CSUM_PSEUDO_HDR

      If set, this indicates that the checksum value for MBUF_CSUM_DID_DATA includes the pseudo header value. If this is not set, the stack will calculate the pseudo header value and add that to the checksum. The value of this bit is only valid when MBUF_CSUM_DID_DATA is set.

      Available in OS X v10.4 and later.

    Discussion

    Mbufs often contain packets. Some hardware supports performing checksums in hardware. The driver uses these flags to communicate to the stack the checksums that were calculated in hardware.

  • Checksum performed/requested flags.

    Declaration

    Objective-C

    enum { MBUF_TSO_IPV4 = 0x100000, MBUF_TSO_IPV6 = 0x200000 };

    Constants

    • MBUF_CSUM_REQ_IP

      MBUF_CSUM_REQ_IP

      Indicates the IP checksum has not been calculated yet.

      Available in OS X v10.4 and later.

    • MBUF_CSUM_REQ_TCP

      MBUF_CSUM_REQ_TCP

      Indicates the TCP checksum has not been calculated yet.

      Available in OS X v10.4 and later.

    • MBUF_CSUM_REQ_UDP

      MBUF_CSUM_REQ_UDP

      Indicates the UDP checksum has not been calculated yet.

      Available in OS X v10.4 and later.

    • MBUF_CSUM_REQ_TCPIPV6

      MBUF_CSUM_REQ_TCPIPV6

      Indicates the TCP checksum for IPv6 has not been calculated yet.

      Available in OS X v10.7 and later.

    • MBUF_CSUM_REQ_UDPIPV6

      MBUF_CSUM_REQ_UDPIPV6

      Indicates the UDP checksum for IPv6 has not been calculated yet.

      Available in OS X v10.7 and later.

    Discussion

    Mbufs often contain packets. Some hardware supports performing checksums in hardware. The stack uses these flags to indicate to the driver what sort of checksumming should be handled in by the driver/hardware. These flags will only be set if the driver indicates that it supports the corresponding checksums using ifnet_set_offload.

  • Constants defining mbuf flags. Only the flags listed below can be set or retrieved.

    Declaration

    Objective-C

    enum { MBUF_EXT = 0x0001 , /* has associated external storage */ MBUF_PKTHDR = 0x0002 , /* start of record */ MBUF_EOR = 0x0004 , /* end of record */ MBUF_LOOP = 0x0040 , /* packet is looped back */ MBUF_BCAST = 0x0100 , /* send/received as link-level broadcast */ MBUF_MCAST = 0x0200 , /* send/received as link-level multicast */ MBUF_FRAG = 0x0400 , /* packet is a fragment of a larger packet */ MBUF_FIRSTFRAG = 0x0800 , /* packet is first fragment */ MBUF_LASTFRAG = 0x1000 , /* packet is last fragment */ MBUF_PROMISC = 0x2000 , /* packet is promiscuous */ MBUF_HASFCS = 0x4000 /* packet has FCS */ };

    Constants

    • MBUF_EXT

      MBUF_EXT

      Indicates this mbuf has external data.

      Available in OS X v10.4 and later.

    • MBUF_PKTHDR

      MBUF_PKTHDR

      Indicates this mbuf has a packet header.

      Available in OS X v10.4 and later.

    • MBUF_EOR

      MBUF_EOR

      Indicates this mbuf is the end of a record.

      Available in OS X v10.4 and later.

    • MBUF_LOOP

      MBUF_LOOP

      Indicates this packet is looped back.

      Available in OS X v10.7 and later.

    • MBUF_BCAST

      MBUF_BCAST

      Indicates this packet will be sent or was received as a brodcast.

      Available in OS X v10.4 and later.

    • MBUF_MCAST

      MBUF_MCAST

      Indicates this packet will be sent or was received as a multicast.

      Available in OS X v10.4 and later.

    • MBUF_FRAG

      MBUF_FRAG

      Indicates this packet is a fragment of a larger packet.

      Available in OS X v10.4 and later.

    • MBUF_FIRSTFRAG

      MBUF_FIRSTFRAG

      Indicates this packet is the first fragment.

      Available in OS X v10.4 and later.

    • MBUF_LASTFRAG

      MBUF_LASTFRAG

      Indicates this packet is the last fragment.

      Available in OS X v10.4 and later.

    • MBUF_PROMISC

      MBUF_PROMISC

      Indicates this packet was only received because the interface is in promiscuous mode. This should be set by the demux function. These packets will be discarded after being passed to any interface filters.

      Available in OS X v10.4 and later.

  • Method of allocating an mbuf.

    Declaration

    Objective-C

    enum { MBUF_WAITOK = 0, /* Ok to block to get memory */ MBUF_DONTWAIT = 1 /* Don't block, fail if blocking would be required */ };

    Constants

    • MBUF_WAITOK

      MBUF_WAITOK

      Allow a call to allocate an mbuf to block.

      Available in OS X v10.4 and later.

    • MBUF_DONTWAIT

      MBUF_DONTWAIT

      Don't allow the mbuf allocation call to block, if blocking is necessary fail and return immediately.

      Available in OS X v10.4 and later.

    Discussion

    Blocking will cause the funnel to be dropped. If the funnel is dropped, other threads may make changes to networking data structures. This can lead to very bad things happening. Blocking on the input our output path can also impact performance. There are some cases where making a blocking call is acceptable. When in doubt, use MBUF_DONTWAIT.

  • Types of mbufs.

    Declaration

    Objective-C

    enum { MBUF_TYPE_FREE = 0, /* should be on free list */ MBUF_TYPE_DATA = 1, /* dynamic (data ) allocation */ MBUF_TYPE_HEADER = 2, /* packet header */ MBUF_TYPE_SOCKET = 3, /* socket structure */ MBUF_TYPE_PCB = 4, /* protocol control block */ MBUF_TYPE_RTABLE = 5, /* routing tables */ MBUF_TYPE_HTABLE = 6, /* IMP host tables */ MBUF_TYPE_ATABLE = 7, /* address resolution tables */ MBUF_TYPE_SONAME = 8, /* socket name */ MBUF_TYPE_SOOPTS = 10, /* socket options */ MBUF_TYPE_FTABLE = 11, /* fragment reassembly header */ MBUF_TYPE_RIGHTS = 12, /* access rights */ MBUF_TYPE_IFADDR = 13, /* interface address */ MBUF_TYPE_CONTROL = 14, /* extra-data protocol message */ MBUF_TYPE_OOBDATA = 15 /* expedited data */ };

    Constants

    • MBUF_MT_FREE

      MBUF_MT_FREE

      Indicates the mbuf is free and is sitting on the queue of free mbufs. If you find that an mbuf you have a reference to has this type, something has gone terribly wrong.

    • MBUF_MT_DATA

      MBUF_MT_DATA

      Indicates this mbuf is being used to store data.

    • MBUF_MT_HEADER

      MBUF_MT_HEADER

      Indicates this mbuf has a packet header, this is probably a packet.

    • MBUF_MT_SOCKET

      MBUF_MT_SOCKET

      Socket structure.

    • MBUF_MT_PCB

      MBUF_MT_PCB

      Protocol control block.

    • MBUF_MT_RTABLE

      MBUF_MT_RTABLE

      Routing table entry.

    • MBUF_MT_HTABLE

      MBUF_MT_HTABLE

      IMP host tables???.

    • MBUF_MT_ATABLE

      MBUF_MT_ATABLE

      Address resolution table data.

    • MBUF_MT_SONAME

      MBUF_MT_SONAME

      Socket name, usually a sockaddr of some sort.

    • MBUF_MT_FTABLE

      MBUF_MT_FTABLE

      Fragment reassembly header.

    • MBUF_MT_RIGHTS

      MBUF_MT_RIGHTS

      Access rights.

    • MBUF_MT_IFADDR

      MBUF_MT_IFADDR

      Interface address.

    • MBUF_MT_CONTROL

      MBUF_MT_CONTROL

      Extra-data protocol message (control message).

    • MBUF_MT_OOBDATA

      MBUF_MT_OOBDATA

      Out of band data.

    Discussion

    Some mbufs represent packets, some represnt data waiting on sockets. Other mbufs store control data or other various structures. The mbuf type is used to store what sort of data the mbuf contains.