kpi_interface.h Reference

Declared in
bpf.h
kpi_interface.h

Overview

This header defines an API to interact with network interfaces in the kernel. The network interface KPI may be used to implement network interfaces or to attach protocols to existing interfaces.

Included Headers

  • <TargetConditionals.h>

  • <sys/kernel_types.h>

  • <sys/_types/_sa_family_t.h>

Functions

See the Overview section above for header-level documentation.

ifaddr_address

extern errno_t ifaddr_address(
   ifaddr_t ifaddr,
   struct sockaddr *out_addr,
   u_int32_t addr_size);
Parameters
ifaddr

The interface address.

out_addr

The sockaddr storage for the address.

addr_size

The size of the storage for the address.

Return Value

0 upon success

Discussion

Copies the address out of the ifaddr.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifaddr_address_family

extern sa_family_t ifaddr_address_family(
   ifaddr_t ifaddr);
Parameters
ifaddr

The interface address.

Return Value

0 on failure, address family on success.

Discussion

Returns the address family of the address.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifaddr_dstaddress

extern errno_t ifaddr_dstaddress(
   ifaddr_t ifaddr,
   struct sockaddr *out_dstaddr,
   u_int32_t dstaddr_size);
Parameters
ifaddr

The interface address.

out_dstaddr

The sockaddr storage for the destination address.

dstaddr_size

The size of the storage for the destination address.

Return Value

0 upon success

Discussion

Copies the destination address out of the ifaddr.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifaddr_findbestforaddr

extern ifaddr_t ifaddr_findbestforaddr(
   const struct sockaddr *addr,
   ifnet_t interface);
Parameters
addr

The remote address.

interface

The local interface.

Return Value

A reference to the interface address.

Discussion

Finds the best local address assigned to a specific interface to use when communicating with another address. Increments the reference count on the ifaddr before returning to the caller. Caller is responsible for calling ifaddr_release.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifaddr_ifnet

extern ifnet_t ifaddr_ifnet(
   ifaddr_t ifaddr);
Parameters
ifaddr

The interface address.

Return Value

A reference to the interface the address is attached to.

Discussion

Returns the interface the address is attached to. The reference is only valid until the ifaddr is released. If you need to hold a reference to the ifnet for longer than you hold a reference to the ifaddr, increment the reference using ifnet_reference.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifaddr_netmask

extern errno_t ifaddr_netmask(
   ifaddr_t ifaddr,
   struct sockaddr *out_netmask,
   u_int32_t netmask_size);
Parameters
ifaddr

The interface address.

out_netmask

The sockaddr storage for the netmask.

netmask_size

The size of the storage for the netmask.

Return Value

0 upon success

Discussion

Copies the netmask out of the ifaddr.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifaddr_reference

extern errno_t ifaddr_reference(
   ifaddr_t ifaddr);
Parameters
ifaddr

The interface address.

Return Value

0 upon success

Discussion

Increment the reference count of an address tied to an interface.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifaddr_release

extern errno_t ifaddr_release(
   ifaddr_t ifaddr);
Parameters
ifaddr

The interface address.

Return Value

0 upon success

Discussion

Decrements the reference count of and possibly frees an address tied to an interface.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifaddr_withaddr

extern ifaddr_t ifaddr_withaddr(
   const struct sockaddr *address);
Parameters
address

The address to search for.

Return Value

A reference to the interface address.

Discussion

Returns an interface address with the address specified. Increments the reference count on the ifaddr before returning to the caller. Caller is responsible for calling ifaddr_release.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifaddr_withdstaddr

extern ifaddr_t ifaddr_withdstaddr(
   const struct sockaddr *destination);
Parameters
destination

The destination to search for.

Return Value

A reference to the interface address.

Discussion

Returns an interface address for the interface address that matches the destination when the netmask is applied. Increments the reference count on the ifaddr before returning to the caller. Caller is responsible for calling ifaddr_release.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifaddr_withnet

extern ifaddr_t ifaddr_withnet(
   const struct sockaddr *net);
Parameters
net

The network to search for.

Return Value

A reference to the interface address.

Discussion

Returns an interface address for the interface with the network described by net. Increments the reference count on the ifaddr before returning to the caller. Caller is responsible for calling ifaddr_release.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifaddr_withroute

extern ifaddr_t ifaddr_withroute(
   int flags,
   const struct sockaddr *destination,
   const struct sockaddr *gateway);
Parameters
flags

Routing flags. See net/route.h, RTF_GATEWAY etc.

destination

The destination to search for.

gateway

A gateway to search for.

Return Value

A reference to the interface address.

Discussion

Returns an interface address given a destination and gateway. Increments the reference count on the ifaddr before returning to the caller. Caller is responsible for calling ifaddr_release.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifmaddr_address

extern errno_t ifmaddr_address(
   ifmultiaddr_t ifmaddr,
   struct sockaddr *out_multicast,
   u_int32_t addr_size);
Parameters
out_multicast

Storage for a sockaddr.

addr_size

Size of the storage.

Return Value

0 on success.

Discussion

Copies the multicast address to out_multicast.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifmaddr_ifnet

extern ifnet_t ifmaddr_ifnet(
   ifmultiaddr_t ifmaddr);
Parameters
ifmaddr

The interface multicast address.

Return Value

A reference to the interface.

Discussion

Returns the interface this multicast address is attached to. The interface reference count is not bumped by this function. The interface is only valid as long as you don't release the refernece to the multiast address. If you need to maintain your pointer to the ifnet, call ifnet_reference followed by ifnet_release when you're finished.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifmaddr_lladdress

extern errno_t ifmaddr_lladdress(
   ifmultiaddr_t ifmaddr,
   struct sockaddr *out_link_layer_multicast,
   u_int32_t addr_size);
Parameters
out_link_layer_multicast

Storage for a sockaddr.

addr_size

Size of the storage.

Return Value

0 on success.

Discussion

Copies the link layer multicast address to out_link_layer_multicast.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifmaddr_reference

extern errno_t ifmaddr_reference(
   ifmultiaddr_t ifmaddr);
Parameters
ifmaddr

The interface multicast address.

Return Value

0 on success. Only error will be EINVAL if ifmaddr is not valid.

Discussion

Increment the reference count of an interface multicast address.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifmaddr_release

extern errno_t ifmaddr_release(
   ifmultiaddr_t ifmaddr);
Parameters
ifmaddr

The interface multicast address.

Return Value

0 on success. Only error will be EINVAL if ifmaddr is not valid.

Discussion

Decrement the reference count of an interface multicast address. If the reference count reaches zero, the ifmultiaddr will be removed from the interface and the ifmultiaddr will be freed.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_addrlen

extern u_int8_t ifnet_addrlen(
   ifnet_t interface);
Parameters
interface

The interface.

Return Value

The address length.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_add_multicast

extern errno_t ifnet_add_multicast(
   ifnet_t interface,
   const struct sockaddr *maddr,
   ifmultiaddr_t *multicast);
Parameters
interface

The interface.

maddr

The multicast address (AF_UNSPEC/AF_LINK) to join. Either a physical address or logical address to be translated to a physical address.

multicast

The resulting ifmultiaddr_t multicast address.

Return Value

0 on success otherwise the errno error.

Discussion

Joins a multicast and returns an ifmultiaddr_t with the reference count incremented for you. You are responsible for decrementing the reference count after calling ifnet_remove_multicast and making sure you no longer have any references to the multicast.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_allocate

extern errno_t ifnet_allocate(
   const struct ifnet_init_params *init,
   ifnet_t *interface);
Parameters
init

The initial values for the interface. These values can not be changed after the interface has been allocated.

interface

The interface allocated upon success.

Return Value

May return ENOMEM if there is insufficient memory or EEXIST if an interface with the same uniqueid and family has already been allocated and is in use.

Discussion

Allocate an ifnet_t with an initial refcount of 1. Many parts of the stack do not properly refcount the ifnet_t. In order to avoid freeing the ifnet_t while some parts of the stack may contain a reference to it, the ifnet_ts are only recycled, never freed. A unique id is used to try and recycle the same ifnet_t when allocating an interface. For example, for an ethernet interface, the hardware address of the ethernet card is usually used for the uniqueid. If a PC Card is removed and inserted again, if the ethernet address of the PC card is used, the same ifnet_t will be used for the card the second time it is inserted. In the future, when the ifnet_t is correctly refcounted by all of the stack, the interfaces may be freed and the unique ids ignored.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_attach

extern errno_t ifnet_attach(
   ifnet_t interface,
   const struct sockaddr_dl *ll_addr);
Parameters
interface

The interface to attach.

ll_addr

The link layer address of the interface. This is used to fill out the first ifaddr in the list of addresses for the interface. This parameter is not required for interfaces such as PPP that have no link-layer address.

Return Value

Will return an error if there is anything wrong with the interface.

Discussion

Attaches an interface to the global interface list. The interface must be setup properly before calling attach. The stack will take a reference on the interface and hold it until ifnet_detach is called.

This function is intended to be called by the driver. A kext must not call this function on an interface the kext does not own.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_attach_protocol

extern errno_t ifnet_attach_protocol(
   ifnet_t interface,
   protocol_family_t protocol_family,
   const struct ifnet_attach_proto_param *proto_details);
Parameters
interface

The interface.

protocol_family

The protocol family being attached (PF_INET/PF_INET6/etc...).

proto_details

Details of the protocol being attached.

Return Value

0 on success otherwise the errno error.

Discussion

Attaches a protocol to an interface.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_attach_protocol_v2

extern errno_t ifnet_attach_protocol_v2(
   ifnet_t interface,
   protocol_family_t protocol_family,
   const struct ifnet_attach_proto_param_v2 *proto_details);
Parameters
interface

The interface.

protocol_family

The protocol family being attached (PF_INET/PF_INET6/etc...).

proto_details

Details of the protocol being attached.

Return Value

0 on success otherwise the errno error.

Discussion

Attaches a protocol to an interface using the newer version 2 style interface. So far the only difference is support for packet chains which improve performance.

Availability
  • Available in OS X v10.5 and later.
Declared In
kpi_interface.h

ifnet_baudrate

extern u_int64_t ifnet_baudrate(
   ifnet_t interface);
Parameters
interface

The interface.

Return Value

The baudrate.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_capabilities_enabled

extern u_int32_t ifnet_capabilities_enabled(
   ifnet_t interface);
Parameters
interface

Interface to retrieve the capabilities from.

Return Value

Flags. Capabilities flags are defined in net/if.h

Discussion

Retrieve the interface capabilities enabled on the interface.

Availability
  • Available in OS X v10.7 and later.
Declared In
kpi_interface.h

ifnet_capabilities_supported

extern u_int32_t ifnet_capabilities_supported(
   ifnet_t interface);
Parameters
interface

Interface to retrieve the capabilities from.

Return Value

Flags. Capabilities flags are defined in net/if.h

Discussion

Retrieve the interface capabilities supported by the interface.

Availability
  • Available in OS X v10.7 and later.
Declared In
kpi_interface.h

ifnet_detach

extern errno_t ifnet_detach(
   ifnet_t interface);
Parameters
interface

The interface to detach.

Return Value

0 on success, otherwise errno error.

Discussion

Detaches the interface.

Call this to indicate this interface is no longer valid (i.e. PC Card was removed). This function will begin the process of removing knowledge of this interface from the stack.

The function will return before the interface is detached. The functions you supplied in to the interface may continue to be called. When the detach has been completed, your detached function will be called. Your kext must not unload until the detached function has been called. The interface will be properly freed when the reference count reaches zero.

An interface may not be attached again. You must call ifnet_allocate to create a new interface to attach.

This function is intended to be called by the driver. A kext must not call this function on an interface the kext does not own.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_detach_protocol

extern errno_t ifnet_detach_protocol(
   ifnet_t interface,
   protocol_family_t protocol_family);
Parameters
interface

The interface.

protocol_family

The protocol family of the protocol to detach.

Return Value

0 on success otherwise the errno error.

Discussion

Detaches a protocol from an interface.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_event

extern errno_t ifnet_event(
   ifnet_t interface,
   struct kern_event_msg *event_ptr);
Parameters
interface

The interface.

event_ptr

Pointer to an kern_event structure describing the event.

Return Value

0 on success otherwise the errno error.

Discussion

Calls the interface's event function.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_family

extern ifnet_family_t ifnet_family(
   ifnet_t interface);
Parameters
interface

Interface to retrieve the family from.

Return Value

Interface family type.

Discussion

Returns the family of the interface.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_find_by_name

extern errno_t ifnet_find_by_name(
   const char *ifname,
   ifnet_t *interface);
Parameters
name

The name of the interface, including any unit number (i.e. "en0").

interface

A pointer to an interface reference. This will be filled in if a matching interface is found.

Return Value

0 on success otherwise the errno error.

Discussion

Find an interface by the name including the unit number. Caller must call ifnet_release on any non-null interface return value.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_flags

extern u_int16_t ifnet_flags(
   ifnet_t interface);
Parameters
interface

Interface to retrieve the flags from.

Return Value

Flags. These flags are defined in net/if.h

Discussion

Returns the interface flags that are set.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_free_address_list

extern void ifnet_free_address_list(
   ifaddr_t *addresses);
Parameters
addresses

An array of ifaddr_ts.

Discussion

Free a list of addresses returned from ifnet_get_address_list. Decrements the refcounts and frees the memory used for the array of references.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_free_multicast_list

extern void ifnet_free_multicast_list(
   ifmultiaddr_t *multicasts);
Parameters
multicasts

An array of references to the multicast addresses.

Return Value

0 on success otherwise the errno error.

Discussion

Frees a list of multicasts returned by ifnet_get_multicast_list. Decrements the refcount on each multicast address and frees the array.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_get_address_list

extern errno_t ifnet_get_address_list(
   ifnet_t interface,
   ifaddr_t **addresses);
Parameters
interface

The interface.

addresses

A pointer to a NULL terminated array of ifaddr_ts.

Return Value

0 on success otherwise the errno error.

Discussion

Get a list of addresses on the interface. Passing NULL for the interface will return a list of all addresses. The addresses will have their reference count bumped so they will not go away. Calling ifnet_free_address_list will decrement the refcount and free the array. If you wish to hold on to a reference to an ifaddr_t, be sure to bump the reference count before calling ifnet_free_address_list.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_get_address_list_family

extern errno_t ifnet_get_address_list_family(
   ifnet_t interface,
   ifaddr_t **addresses,
   sa_family_t family);
Parameters
interface

The interface.

addresses

A pointer to a NULL terminated array of ifaddr_ts.

Return Value

0 on success otherwise the errno error.

Discussion

Get a list of addresses on the interface. Passing NULL for the interface will return a list of all addresses. The addresses will have their reference count bumped so they will not go away. Calling ifnet_free_address_list will decrement the refcount and free the array. If you wish to hold on to a reference to an ifaddr_t, be sure to bump the reference count before calling ifnet_free_address_list. Unlike ifnet_get_address_list, this function lets the caller specify the address family to get a list of only a specific address type.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_get_link_mib_data

extern errno_t ifnet_get_link_mib_data(
   ifnet_t interface,
   void *mibData,
   u_int32_t *mibLen);
Parameters
interface

The interface.

mibData

A pointer to space for the mibData to be copied in to.

mibLen

When calling, this should be the size of the buffer passed in mibData. Upon return, this will be the size of data copied in to mibData.

Return Value

Returns an error if the buffer size is too small or there is no data.

Discussion

Copies the link MIB data in to mibData, up to mibLen bytes. Returns error if the buffer is too small to hold all of the MIB data.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_get_link_mib_data_length

extern u_int32_t ifnet_get_link_mib_data_length(
   ifnet_t interface);
Parameters
interface

The interface.

Return Value

Returns the number of bytes of mib data associated with the interface.

Discussion

Retrieve the size of the mib data.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_get_multicast_list

extern errno_t ifnet_get_multicast_list(
   ifnet_t interface,
   ifmultiaddr_t **addresses);
Parameters
interface

The interface.

multicasts

A pointer to a NULL terminated array of references to the multicast addresses.

Return Value

0 on success otherwise the errno error.

Discussion

Retrieves a list of multicast address the interface is set to receive. This function allocates and returns an array of references to the various multicast addresses. The multicasts have their reference counts bumped on your behalf. Calling ifnet_free_multicast_list will decrement the reference counts and free the array.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_get_tso_mtu

extern errno_t ifnet_get_tso_mtu(
   ifnet_t interface,
   sa_family_t family,
   u_int32_t *mtuLen);
Parameters
interface

The interface.

family

The family for which the offload MTU is provided for (AF_INET or AF_INET6)

mtuLen

Value of the maximum MTU supported for the interface and family provided.

Return Value

0 on success otherwise the errno error.

Discussion

Returns maximum TCP Segmentation Offload segment size for the interface

Availability
  • Available in OS X v10.6 and later.
Declared In
kpi_interface.h

ifnet_get_wake_flags

extern u_int32_t ifnet_get_wake_flags(
   ifnet_t interface);
Parameters
interface

The interface.

Return Value

The wake properties

Discussion

Returns the wake properties set on the interface.

Availability
  • Available in OS X v10.6 and later.
Declared In
kpi_interface.h

ifnet_hdrlen

extern u_int8_t ifnet_hdrlen(
   ifnet_t interface);
Parameters
interface

The interface.

Return Value

The header length.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_index

extern u_int32_t ifnet_index(
   ifnet_t interface);
Parameters
interface

Interface to retrieve the index of.

Return Value

Index.

Discussion

Returns the index of the interface. This index value will match the index you would find in a sockaddr_dl or using if_nametoindex or if_indextoname in user space. The value of the interface index is undefined for an interface that is not currently attached.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_input

extern errno_t ifnet_input(
   ifnet_t interface,
   mbuf_t first_packet,
   const struct ifnet_stat_increment_param *stats);
Parameters
interface

The interface.

first_packet

The first packet in a chain of packets.

stats

Counts to be integrated in to the stats. The interface statistics will be incremented by the amounts specified in stats. This parameter may be NULL.

Return Value

0 on success otherwise the errno error.

Discussion

Inputs packets from the interface. The interface's demux will be called to determine the protocol. Once the protocol is determined, the interface filters and protocol filters will be called. From there, the packet will be passed to the registered protocol. If there is an error, the mbuf chain will be freed.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_interface_family_find

extern errno_t ifnet_interface_family_find(
   const char *module_string,
   ifnet_family_t *family_id);
Parameters
module_string

A unique string identifying your interface family

family_id

Upon return, a unique interface family identifier for use with ifnet_* functions. This identifier is valid until the system is rebooted.

Return Value

0 on success, otherwise errno error.

Discussion

Look up the interface family identifier for a string. If there is no interface family identifier assigned for this string a new interface family identifier is created and assigned. It is recommended to use the bundle id of the KEXT as the string to avoid collisions with other KEXTs. The lookup operation is not optimized so a module should call this function once during startup and cache the interface family identifier. The interface family identifier for a string will not be re-assigned until the system reboots.

Availability
  • Available in OS X v10.6 and later.
Declared In
kpi_interface.h

ifnet_ioctl

extern errno_t ifnet_ioctl(
   ifnet_t interface,
   protocol_family_t protocol,
   unsigned long ioctl_code,
   void *ioctl_arg);
Parameters
interface

The interface.

protocol

The protocol family of the protocol to send the ioctl to (may be zero). Some ioctls apply to a protocol while other ioctls apply to just an interface.

ioctl_code

The ioctl to perform.

ioctl_arg

Any parameters to the ioctl.

Return Value

0 on success otherwise the errno error.

Discussion

Calls the interface's ioctl function with the parameters passed.

All undefined ioctls are reserved for future use by Apple. If you need to communicate with your kext using an ioctl, please use SIOCSIFKPI and SIOCGIFKPI.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_lastchange

extern errno_t ifnet_lastchange(
   ifnet_t interface,
   struct timeval *last_change);
Parameters
interface

The interface.

last_change

A timeval struct to copy the last time changed in to.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_list_free

extern void ifnet_list_free(
   ifnet_t *interfaces);
Parameters
interfaces

An array of interface references from ifnet_list_get.

Discussion

Free a list of interfaces returned by ifnet_list_get. Decrements the reference count on each interface and frees the array of references. If you keep a reference to an interface, be sure to increment the reference count before calling ifnet_list_free.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_list_get

extern errno_t ifnet_list_get(
   ifnet_family_t family,
   ifnet_t **interfaces,
   u_int32_t *count);
Parameters
family

The interface family (i.e. IFNET_FAMILY_ETHERNET). To find interfaces of all families, use IFNET_FAMILY_ANY.

interfaces

A pointer to an array of interface references.

count

A pointer that will be filled in with the number of matching interfaces in the array.

Return Value

0 on success otherwise the errno error.

Discussion

Get a list of attached interfaces. List will be set to point to an array allocated by ifnet_list_get. The interfaces are refcounted and the counts will be incremented before the function returns. The list of interfaces must be freed using ifnet_list_free.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_lladdr_copy_bytes

extern errno_t ifnet_lladdr_copy_bytes(
   ifnet_t interface,
   void *lladdr,
   size_t length);
Parameters
interface

The interface to copy the link-layer address from.

lladdr

The buffer to copy the link-layer address in to.

length

The length of the buffer. This value must match the length of the link-layer address.

Discussion

Copies the bytes of the link-layer address into the specified buffer.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_llbroadcast_copy_bytes

extern errno_t ifnet_llbroadcast_copy_bytes(
   ifnet_t interface,
   void *addr,
   size_t bufferlen,
   size_t *addr_len);
Parameters
interface

The interface.

addr

A buffer to copy the broadcast address in to.

bufferlen

The length of the buffer at addr.

addr_len

On return, the length of the broadcast address.

lladdr_len

The length, in bytes, of the link layer address.

Discussion

Retrieves the link-layer broadcast address for this interface.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_metric

extern u_int32_t ifnet_metric(
   ifnet_t interface);
Parameters
interface

The interface.

Return Value

The metric.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_mtu

extern u_int32_t ifnet_mtu(
   ifnet_t interface);
Parameters
interface

The interface.

Return Value

The MTU.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_name

extern const char *ifnet_name(
   ifnet_t interface);
Parameters
interface

Interface to retrieve the name from.

Return Value

Pointer to the name.

Discussion

Returns a pointer to the name of the interface.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_offload

extern ifnet_offload_t ifnet_offload(
   ifnet_t interface);
Parameters
interface

Interface to retrieve the offload from.

Return Value

Abilities flags, see ifnet_offload_t.

Discussion

Returns flags indicating which operations can be offloaded to the interface.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_output

extern errno_t ifnet_output(
   ifnet_t interface,
   protocol_family_t protocol_family,
   mbuf_t packet,
   void *route,
   const struct sockaddr *dest);
Parameters
interface

The interface.

protocol_family

The family of the protocol generating this packet (i.e. AF_INET).

packet

The packet to be transmitted.

route

A pointer to a routing structure for this packet. The preoutput function determines whether this value may be NULL or not.

dest

The destination address of protocol_family type. This will be passed to the preoutput function. If the preoutput function does not require this value, you may pass NULL.

Return Value

0 on success otherwise the errno error.

Discussion

Handles an outbound packet on the interface by calling any filters, a protocol preoutput function, the interface framer function, and finally the interface's output function. The protocol_family will be used to apply protocol filters and determine which preoutput function to call. The route and dest parameters will be passed to the preoutput function defined for the attachment of the specified protocol to the specified interface. ifnet_output will always free the mbuf chain.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_output_raw

extern errno_t ifnet_output_raw(
   ifnet_t interface,
   protocol_family_t protocol_family,
   mbuf_t packet);
Parameters
interface

The interface.

protocol_family

The family of the protocol generating this packet (i.e. AF_INET).

packet

The fully formed packet to be transmitted.

Return Value

0 on success otherwise the errno error.

Discussion

Handles and outbond raw packet on the interface by calling any filters followed by the interface's output function. protocol_family may be zero. If the packet is from a specific protocol the protocol_family will be used to apply protocol filters. All interface filters will be applied to the outgoing packet. Processing, such as calling the protocol preoutput and interface framer functions will be bypassed. The packet will pass through the filters and be sent on the interface as is. ifnet_output_raw will always free the packet chain.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_reference

extern errno_t ifnet_reference(
   ifnet_t interface);
Parameters
interface

The interface to increment the reference count of.

Return Value

May return EINVAL if the interface is not valid.

Discussion

Increment the reference count of the ifnet to assure that it will not go away. The interface must already have at least one reference.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_release

extern errno_t ifnet_release(
   ifnet_t interface);
Parameters
interface

The interface to decrement the reference count of and possibly free.

Return Value

May return EINVAL if the interface is not valid.

Discussion

Release a reference of the ifnet, this may trigger a free if the reference count reaches 0.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_remove_multicast

extern errno_t ifnet_remove_multicast(
   ifmultiaddr_t multicast);
Parameters
multicast

The multicast to be removed.

Return Value

0 on success otherwise the errno error.

Discussion

Causes the interface to leave the multicast group. The stack keeps track of how many times ifnet_add_multicast has been called for a given multicast address. The multicast will only be removed when the number of times ifnet_remove_multicast has been called matches the number of times ifnet_add_multicast has been called.

The memory for the multicast address is not actually freed until the separate reference count has reached zero. Some parts of the stack may keep a pointer to the multicast even after that multicast has been removed from the interface.

When an interface is detached, all of the multicasts are removed. If the interface of the multicast passed in is no longer attached, this function will gracefully return, performing no work.

It is the callers responsibility to release the multicast address after calling this function.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_resolve_multicast

extern errno_t ifnet_resolve_multicast(
   ifnet_t ifp,
   const struct sockaddr *proto_addr,
   struct sockaddr *ll_addr,
   size_t ll_len);
Parameters
interface

The interface.

proto_addr

A protocol address to be converted to a link-layer address.

ll_addr

Storage for the resulting link-layer address.

ll_len

Length of the storage for the link-layer address.

Return Value

0 on success. EOPNOTSUPP indicates the multicast address was not supported or could not be translated. Other errors may indicate other failures.

Discussion

Resolves a multicast address for an attached protocol to a link-layer address. If a link-layer address is passed in, the interface will verify that it is a valid multicast address.

Availability
  • Available in OS X v10.5 and later.
Declared In
kpi_interface.h

ifnet_set_addrlen

extern errno_t ifnet_set_addrlen(
   ifnet_t interface,
   u_int8_t addrlen);
Parameters
interface

The interface.

addrlen

The new address length.

Return Value

0 on success otherwise the errno error.

Discussion

This function is intended to be called by the driver. A kext must not call this function on an interface the kext does not own.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_set_baudrate

extern errno_t ifnet_set_baudrate(
   ifnet_t interface,
   u_int64_t baudrate);
Parameters
interface

The interface.

baudrate

The new baudrate.

Return Value

0 on success otherwise the errno error.

Discussion

This function is intended to be called by the driver. A kext must not call this function on an interface the kext does not own.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_set_capabilities_enabled

extern errno_t ifnet_set_capabilities_enabled(
   ifnet_t interface,
   u_int32_t new_caps,
   u_int32_t mask);
Parameters
interface

Interface to set the capabilities on.

new_caps

The value of the capabilities that should be set or unset. These flags are defined in net/if.h

mask

Which capabilities that should be affected. These flags are defined in net/if.h

Return Value

0 on success otherwise the errno error.

Discussion

Sets the interface capabilities to new_caps. This function lets you specify which capabilities you want to change using the mask. The kernel will effectively take the lock, then set the interface's flags to (if_capenable & ~mask) | (new_caps & mask).

This function is intended to be called by the driver. A kext must not call this function on an interface the kext does not own.

Typically this function is called by the driver when the interface is created to specify which of the supported capabilities are enabled by default. This function is also meant to be called when the driver handles the interface ioctl SIOCSIFCAP.

The driver should call ifnet_set_offlad() to indicate the corresponding hardware offload bits that will be used by the networking stack.

It is an error to enable a capability that is not marked as supported by the interface.

Availability
  • Available in OS X v10.7 and later.
Declared In
kpi_interface.h

ifnet_set_capabilities_supported

extern errno_t ifnet_set_capabilities_supported(
   ifnet_t interface,
   u_int32_t new_caps,
   u_int32_t mask);
Parameters
interface

Interface to set the capabilities on.

new_caps

The value of the capabilities that should be set or unset. These flags are defined in net/if.h

mask

Which capabilities that should be affected. These flags are defined in net/if.h

Return Value

0 on success otherwise the errno error.

Discussion

This function lets you specify which capabilities are supported by the interface. Typically this function is called by the driver when the interface gets attached to the system. The mask allows to control which capability to set or unset. The kernel will effectively take the lock, then set the interface's flags to (if_capabilities & ~mask) | (new_caps & mask).

This function is intended to be called by the driver. A kext must not call this function on an interface the kext does not own.

Availability
  • Available in OS X v10.7 and later.
Declared In
kpi_interface.h

ifnet_set_flags

extern errno_t ifnet_set_flags(
   ifnet_t interface,
   u_int16_t new_flags,
   u_int16_t mask);
Parameters
interface

Interface to set the flags on.

new_flags

The new set of flags that should be set. These flags are defined in net/if.h

Return Value

0 on success otherwise the errno error.

Discussion

Sets the interface flags to new_flags. This function lets you specify which flags you want to change using the mask. The kernel will effectively take the lock, then set the interface's flags to (if_flags & ~mask) | (new_flags & mask).

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_set_hdrlen

extern errno_t ifnet_set_hdrlen(
   ifnet_t interface,
   u_int8_t hdrlen);
Parameters
interface

The interface.

hdrlen

The new header length.

Return Value

0 on success otherwise the errno error.

Discussion

This function is intended to be called by the driver. A kext must not call this function on an interface the kext does not own.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_set_link_mib_data

extern errno_t ifnet_set_link_mib_data(
   ifnet_t interface,
   void *mibData,
   u_int32_t mibLen);
Parameters
interface

Interface to set the unit number of.

mibData

A pointer to the data.

mibLen

Length of data pointed to.

Return Value

0 on success otherwise the errno error.

Discussion

Sets the mib link data. The ifnet_t will store the pointer you supply and copy mibLen bytes from the pointer whenever the sysctl for getting interface specific MIB data is used. Since the ifnet_t stores a pointer to your data instead of a copy, you may update the data at the address at any time.

This function is intended to be called by the driver. A kext must not call this function on an interface the kext does not own.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_set_lladdr

extern errno_t ifnet_set_lladdr(
   ifnet_t interface,
   const void *lladdr,
   size_t lladdr_len);
Parameters
interface

The interface the link layer address is being changed on.

lladdr

A pointer to the raw link layer address (pointer to the 6 byte ethernet address for ethernet).

lladdr_len

The length, in bytes, of the link layer address.

Discussion

Sets the link-layer address for this interface.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_set_metric

extern errno_t ifnet_set_metric(
   ifnet_t interface,
   u_int32_t metric);
Parameters
interface

The interface.

metric

The new metric.

Return Value

0 on success otherwise the errno error.

Discussion

This function is intended to be called by the driver. A kext must not call this function on an interface the kext does not own.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_set_mtu

extern errno_t ifnet_set_mtu(
   ifnet_t interface,
   u_int32_t mtu);
Parameters
interface

The interface.

mtu

The new MTU.

Return Value

0 on success otherwise the errno error.

Discussion

Sets the value of the MTU in the interface structure. Calling this function will not notify the driver that the MTU should be changed. Use the appropriate ioctl.

This function is intended to be called by the driver. A kext must not call this function on an interface the kext does not own.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_set_offload

extern errno_t ifnet_set_offload(
   ifnet_t interface,
   ifnet_offload_t offload);
Parameters
interface

The interface.

offload

The new set of flags indicating which offload options the device supports.

Return Value

0 on success otherwise the errno error.

Discussion

Sets a bitfield to indicate special hardware offload support provided by the interface such as hardware checksums and VLAN. This replaces the if_hwassist flags field. Any flags unrecognized by the stack will not be set.

Note the system will automatically set the interface capabilities that correspond to the offload flags modified -- i.e. the driver does not have to call ifnet_set_capabilities_enabled() and ifnet_set_capabilities_supported().

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_set_promiscuous

extern errno_t ifnet_set_promiscuous(
   ifnet_t interface,
   int on);
Parameters
interface

The interface to toggle promiscuous mode on.

on

If set, the number of promicuous on requests will be incremented. If this is the first requrest, promiscuous mode will be enabled. If this is not set, the number of promiscous clients will be decremented. If this causes the number to reach zero, promiscuous mode will be disabled.

Return Value

0 on success otherwise the errno error.

Discussion

Enable or disable promiscuous mode on the interface. The interface keeps an internal count of the number of times promiscuous mode has been enabled. Promiscuous mode is only disabled when this count reaches zero. Be sure to disable promiscuous mode only once for every time you enable it.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_set_stat

extern errno_t ifnet_set_stat(
   ifnet_t interface,
   const struct ifnet_stats_param *stats);
Parameters
interface

The interface.

counts

The new stats values.

Return Value

0 on success otherwise the errno error.

Discussion

This function is intended to be called by the driver. A kext must not call this function on an interface the kext does not own.

The one exception would be the case where a kext wants to zero all of the counters.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_set_tso_mtu

extern errno_t ifnet_set_tso_mtu(
   ifnet_t interface,
   sa_family_t family,
   u_int32_t mtuLen);
Parameters
interface

The interface.

family

The family for which the offload MTU is provided for (AF_INET or AF_INET6)

mtuLen

Maximum segment size supported by the interface

Return Value

0 on success otherwise the errno error.

Discussion

Sets maximum TCP Segmentation Offload segment size for the interface

Availability
  • Available in OS X v10.6 and later.
Declared In
kpi_interface.h

ifnet_set_wake_flags

extern errno_t ifnet_set_wake_flags(
   ifnet_t interface,
   u_int32_t properties,
   u_int32_t mask);
Parameters
interface

The interface.

properties

Properties to set or unset.

mask

Mask of the properties to set of unset.

Return Value

0 on success otherwise the errno error.

Discussion

Sets the wake properties of the underlying hardware. These are typically set by the driver.

Availability
  • Available in OS X v10.6 and later.
Declared In
kpi_interface.h

ifnet_softc

extern void *ifnet_softc(
   ifnet_t interface);
Parameters
interface

Interface to retrieve the storage from.

Return Value

Driver's private storage.

Discussion

Returns the driver's private storage on the interface.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_stat

extern errno_t ifnet_stat(
   ifnet_t interface,
   struct ifnet_stats_param *out_stats);
Parameters
interface

The interface.

out_stats

Storage for the values.

Return Value

0 on success otherwise the errno error.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_stat_increment

extern errno_t ifnet_stat_increment(
   ifnet_t interface,
   const struct ifnet_stat_increment_param *counts);
Parameters
interface

The interface.

counts

A pointer to a structure containing the amount to increment each counter by. Any counts not appearing in the ifnet_counter_increment structure are handled in the stack.

Return Value

0 on success otherwise the errno error.

Discussion

This function is intended to be called by the driver. A kext must not call this function on an interface the kext does not own.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_stat_increment_in

extern errno_t ifnet_stat_increment_in(
   ifnet_t interface,
   u_int32_t packets_in,
   u_int32_t bytes_in,
   u_int32_t errors_in);
Parameters
interface

The interface.

packets_in

The number of additional packets received.

bytes_in

The number of additional bytes received.

errors_in

The number of additional receive errors.

Return Value

0 on success otherwise the errno error.

Discussion

This function is intended to be called by the driver. This function allows a driver to update the inbound interface counts. The most efficient time to update these counts is when calling ifnet_input.

A lock protects the counts, this makes the increment functions expensive. The increment function will update the lastchanged value.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_stat_increment_out

extern errno_t ifnet_stat_increment_out(
   ifnet_t interface,
   u_int32_t packets_out,
   u_int32_t bytes_out,
   u_int32_t errors_out);
Parameters
interface

The interface.

packets_out

The number of additional packets sent.

bytes_out

The number of additional bytes sent.

errors_out

The number of additional send errors.

Return Value

0 on success otherwise the errno error.

Discussion

This function is intended to be called by the driver. This function allows a driver to update the outbound interface counts.

A lock protects the counts, this makes the increment functions expensive. The increment function will update the lastchanged value.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_touch_lastchange

extern errno_t ifnet_touch_lastchange(
   ifnet_t interface);
Parameters
interface

The interface.

Return Value

0 on success otherwise the errno error.

Discussion

Updates the lastchange value to now.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_type

extern u_int8_t ifnet_type(
   ifnet_t interface);
Parameters
interface

The interface.

Return Value

The type. See net/if_types.h.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_unit

extern u_int32_t ifnet_unit(
   ifnet_t interface);
Parameters
interface

Interface to retrieve the unit number from.

Return Value

Unit number.

Discussion

Returns the unit number of the interface.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

Callbacks

See the Overview section above for header-level documentation.

bpf_packet_func

/* Fast path - do not block or spend excessive amounts of time */
typedef errno_t ( *bpf_packet_func)(
   ifnet_t interface,
   mbuf_t data);

Parameters
interface

The interface being sent or received on.

data

The packet to be transmitted or received.

Return Value

An errno value or zero upon success.

Discussion

bpf_packet_func The bpf_packet_func is used to intercept inbound and outbound packets. The tap function will never free the mbuf. The tap function will only copy the mbuf in to various bpf file descriptors tapping this interface.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_add_proto_func

typedef errno_t ( *ifnet_add_proto_func)(
   ifnet_t interface,
   protocol_family_t protocol_family,
   const struct ifnet_demux_desc *demux_array,
   u_int32_t demux_count);

Parameters
interface

The interface the protocol will be attached to.

protocol_family

The family of the protocol being attached.

demux_array

An array of demux descriptors that describe the interface specific ways of identifying packets belonging to this protocol family.

demux_count

The number of demux descriptors in the array.

Return Value

If the result is zero, processing will continue normally. If the result is anything else, the add protocol will be aborted.

Discussion

if_add_proto_func is called by the stack when a protocol is attached to an interface. This gives the interface an opportunity to get a list of protocol description structures for demuxing packets to this protocol (demux descriptors).

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_check_multi

typedef errno_t ( *ifnet_check_multi)(
   ifnet_t interface,
   const struct sockaddr *mcast);

Parameters
The

interface.

mcast

The multicast address.

Return Value

Zero upon success, EADDRNOTAVAIL on invalid multicast, EOPNOTSUPP for addresses the interface does not understand.

Discussion

ifnet_check_multi is called for each multicast address added to an interface. This gives the interface an opportunity to reject invalid multicast addresses before they are attached to the interface.

To prevent an address from being added to your multicast list, return EADDRNOTAVAIL. If you don't know how to parse/translate the address, return EOPNOTSUPP.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_del_proto_func

typedef errno_t ( *ifnet_del_proto_func)(
   ifnet_t interface,
   protocol_family_t protocol_family);

Parameters
interface

The interface the protocol will be detached from.

protocol_family

The family of the protocol being detached.

Return Value

If the result is zero, processing will continue normally. If the result is anything else, the detach will continue and the error will be returned to the caller.

Discussion

if_del_proto_func is called by the stack when a protocol is being detached from an interface. This gives the interface an opportunity to free any storage related to this specific protocol being attached to this interface.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_demux_func

typedef errno_t ( *ifnet_demux_func)(
   ifnet_t interface,
   mbuf_t packet,
   char *frame_header,
   protocol_family_t *protocol_family);

Parameters
interface

The interface the packet was received on.

packet

The mbuf containing the packet.

frame_header

A pointer to the frame header.

protocol_family

Upon return, the protocol family matching the packet should be stored here.

Return Value

If the result is zero, processing will continue normally. If the result is EJUSTRETURN, processing will stop but the packet will not be freed. If the result is anything else, the processing will stop and the packet will be freed.

Discussion

ifnet_demux_func is called for each inbound packet to determine which protocol family the packet belongs to. This information is then used by the stack to determine which protocol to pass the packet to. This function may return protocol families for protocols that are not attached. If the protocol family has not been attached to the interface, the packet will be discarded.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_detached_func

typedef void ( *ifnet_detached_func)(
   ifnet_t interface);

Parameters
interface

The interface that has been detached. event.

Discussion

ifnet_detached_func is called an interface is detached from the list of interfaces. When ifnet_detach is called, it may not detach the interface immediately if protocols are attached. ifnet_detached_func is used to notify the interface that it has been detached from the networking stack. This is the last function that will be called on an interface. Until this function returns, you must not unload a kext supplying function pointers to this interface, even if ifnet_detacah has been called. Your detach function may be called during your call to ifnet_detach.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_event_func

typedef void ( *ifnet_event_func)(
   ifnet_t interface,
   const struct kev_msg *msg);

Parameters
interface

The interface the event occurred on.

event_ptr

Pointer to a kern_event structure describing the event.

Discussion

ifnet_event_func is called when an event occurs on a specific interface.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_framer_func

typedef errno_t ( *ifnet_framer_func)(
   ifnet_t interface,
   mbuf_t *packet,
   const struct sockaddr *dest,
   const char *dest_linkaddr,
   const char *frame_type  #if KPI_INTERFACE_EMBEDDED
   ,
   u_int32_t *prepend_len,
   u_int32_t *postpend_len  #endif
   /* KPI_INTERFACE_EMBEDDED */
   );

Parameters
interface

The interface the packet is being sent on.

packet

Pointer to the mbuf containing the packet, caller may set this to a different mbuf upon return. This can happen if the frameout function needs to prepend another mbuf to the chain to have enough space for the header.

dest

The higher layer protocol destination (i.e. IP address).

dest_linkaddr

The link layer address as determined by the protocol's pre-output function.

frame_type

The frame type as determined by the protocol's pre-output function.

prepend_len

The length of prepended bytes to the mbuf. (ONLY used if KPI_INTERFACE_EMBEDDED is defined to 1)

postpend_len

The length of the postpended bytes to the mbuf. (ONLY used if KPI_INTERFACE_EMBEDDED is defined to 1)

Return Value

If the result is zero, processing will continue normally. If the result is EJUSTRETURN, processing will stop but the packet will not be freed. If the result is anything else, the processing will stop and the packet will be freed.

Discussion

ifnet_framer_func is called for each outbound packet to give the interface an opportunity to prepend interface specific headers.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_ioctl_func

typedef errno_t ( *ifnet_ioctl_func)(
   ifnet_t interface,
   unsigned long cmd,
   void *data);

Parameters
interface

The interface the ioctl is being sent to.

proto_family

The protocol family to handle the ioctl, may be zero for no protocol_family.

cmd

The ioctl command.

data

A pointer to any data related to the ioctl.

Discussion

ifnet_ioctl_func is used to communicate ioctls from the stack to the driver.

All undefined ioctls are reserved for future use by Apple. If you need to communicate with your kext using an ioctl, please use SIOCSIFKPI and SIOCGIFKPI.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_output_func

/* Fast path - do not block or spend excessive amounts of time */
typedef errno_t ( *ifnet_output_func)(
   ifnet_t interface,
   mbuf_t data);

Parameters
interface

The interface being sent on.

data

The packet to be sent.

Discussion

ifnet_output_func is used to transmit packets. The stack will pass fully formed packets, including frame header, to the ifnet_output function for an interface. The driver is responsible for freeing the mbuf.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_set_bpf_tap

typedef errno_t ( *ifnet_set_bpf_tap)(
   ifnet_t interface,
   bpf_tap_mode mode,
   bpf_packet_func callback);

Discussion

Deprecated. Specify NULL. Call bpf_tap_in/bpf_tap_out for all packets.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

proto_media_detached

typedef errno_t ( *proto_media_detached)(
   ifnet_t ifp,
   protocol_family_t protocol);

Parameters
ifp

The interface.

protocol_family

The protocol family.

Return Value

See the discussion.

Discussion

proto_media_detached notifies you that your protocol has been detached.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

proto_media_event

typedef void ( *proto_media_event)(
   ifnet_t ifp,
   protocol_family_t protocol,
   const struct kev_msg *event);

Parameters
ifp

The interface.

protocol_family

The protocol family.

kev_msg

The event.

Discussion

proto_media_event is called to notify this layer of interface specific events.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

proto_media_input

typedef errno_t ( *proto_media_input)(
   ifnet_t ifp,
   protocol_family_t protocol,
   mbuf_t packet,
   char *header);

Parameters
ifp

The interface the packet was received on.

protocol_family

The protocol of the packet received.

packet

The packet being input.

header

The frame header.

Return Value

If the result is zero, the caller will assume the packet was passed to the protocol. If the result is non-zero and not EJUSTRETURN, the caller will free the packet.

Discussion

proto_media_input is called for all inbound packets for a specific protocol on a specific interface. This function is registered on an interface using ifnet_attach_protocol.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

proto_media_input_v2

typedef errno_t ( *proto_media_input_v2)(
   ifnet_t ifp,
   protocol_family_t protocol,
   mbuf_t packet);

Parameters
ifp

The interface the packet was received on.

protocol_family

The protocol of the packet received.

packet

The packet being input.

Return Value

If the result is zero, the caller will assume the packets were passed to the protocol. If the result is non-zero and not EJUSTRETURN, the caller will free the packets.

Discussion

proto_media_input_v2 is called for all inbound packets for a specific protocol on a specific interface. This function is registered on an interface using ifnet_attach_protocolv2. proto_media_input_v2 differs from proto_media_input in that it will be called for a list of packets instead of once for each individual packet. The frame header can be retrieved using mbuf_pkthdr_header.

Availability
  • Available in OS X v10.5 and later.
Declared In
kpi_interface.h

proto_media_ioctl

typedef errno_t ( *proto_media_ioctl)(
   ifnet_t ifp,
   protocol_family_t protocol,
   unsigned long command,
   void *argument);

Parameters
ifp

The interface.

protocol_family

The protocol family.

command

The ioctl command.

argument

The argument to the ioctl.

Return Value

See the discussion.

Discussion

proto_media_event allows this layer to handle ioctls. When an ioctl is handled, it is passed to the interface filters, protocol filters, protocol, and interface. If you do not support this ioctl, return EOPNOTSUPP. If you successfully handle the ioctl, return zero. If you return any error other than EOPNOTSUPP, other parts of the stack may not get an opportunity to process the ioctl. If you return EJUSTRETURN, processing will stop and a result of zero will be returned to the caller.

All undefined ioctls are reserved for future use by Apple. If you need to communicate with your kext using an ioctl, please use SIOCSIFKPI and SIOCGIFKPI.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

proto_media_preout

typedef errno_t ( *proto_media_preout)(
   ifnet_t ifp,
   protocol_family_t protocol,
   mbuf_t *packet,
   const struct sockaddr *dest,
   void *route,
   char *frame_type,
   char *link_layer_dest);

Parameters
ifp

The interface the packet will be sent on.

protocol_family

The protocol of the packet being sent (PF_INET/etc...).

packet

The packet being sent.

dest

The protocol level destination address.

route

A pointer to the routing structure for the packet.

frame_type

The media specific frame type.

link_layer_dest

The media specific destination.

Return Value

If the result is zero, processing will continue normally. If the result is non-zero, processing will stop. If the result is non-zero and not EJUSTRETURN, the packet will be freed by the caller.

Discussion

proto_media_preout is called just before the packet is transmitted. This gives the proto_media_preout function an opportunity to specify the media specific frame type and destination.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

proto_media_resolve_multi

typedef errno_t ( *proto_media_resolve_multi)(
   ifnet_t ifp,
   const struct sockaddr *proto_addr,
   struct sockaddr_dl *out_ll,
   size_t ll_len);

Parameters
ifp

The interface.

proto_addr

The protocol address.

out_ll

A sockaddr_dl to copy the link layer multicast in to.

ll_len

The length of data allocated for out_ll.

Return Value

Return zero on success or an errno error value on failure.

Discussion

proto_media_resolve_multi is called to resolve a protocol layer mulitcast address to a link layer multicast address.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

proto_media_send_arp

typedef errno_t ( *proto_media_send_arp)(
   ifnet_t ifp,
   u_short arpop,
   const struct sockaddr_dl *sender_hw,
   const struct sockaddr *sender_proto,
   const struct sockaddr_dl *target_hw,
   const struct sockaddr *target_proto);

Parameters
ifp

The interface the arp packet should be sent on.

protocol_family

The protocol family of the addresses (PF_INET).

arpop

The arp operation (usually ARPOP_REQUEST or ARPOP_REPLY).

sender_hw

The value to use for the sender hardware address field. If this is NULL, use the hardware address of the interface.

sender_proto

The value to use for the sender protocol address field. This will not be NULL.

target_hw

The value to use for the target hardware address. If this is NULL, the target hardware address in the ARP packet should be NULL and the link-layer destination for the back should be a broadcast. If this is not NULL, this value should be used for both the link-layer destination and the target hardware address.

target_proto

The target protocol address. This will not be NULL.

Return Value

Return zero on success or an errno error value on failure.

Discussion

proto_media_send_arp is called by the stack to generate an ARP packet. This field is currently only used with IP. This function should inspect the parameters and transmit an arp packet using the information passed in.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

Data Types

See the Overview section above for header-level documentation.

bpf_tap_mode

Mode for tapping. BPF_MODE_DISABLED/BPF_MODE_INPUT_OUTPUT etc.

typedef u_int32_t bpf_tap_mode;
Availability
  • Available in OS X v10.4 and later.
Declared In
bpf.h

ifnet_family_t

Storage type for the interface family.

typedef u_int32_t ifnet_family_t;
Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_offload_t

Flags indicating the offload support of the interface.

typedef u_int32_t ifnet_offload_t;
Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

protocol_family_t

Storage type for the protocol family.

typedef u_int32_t protocol_family_t;
Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_interface.h

ifnet_attach_proto_param

struct ifnet_attach_proto_param {
   struct ifnet_demux_desc *demux_array; /* interface may/may not require */
   u_int32_t demux_count; /* interface may/may not require */
   proto_media_input input; /* required */
   proto_media_preout pre_output; /* required */
   proto_media_event event; /* optional */
   proto_media_ioctl ioctl; /* optional */
   proto_media_detached detached; /* optional */
   proto_media_resolve_multi resolve; /* optional */
   proto_media_send_arp send_arp; /* optional */
};
Fields
demux_array

An array of ifnet_demux_desc structures describing the protocol.

demux_count

The number of entries in the demux_array array.

input

The function to be called for inbound packets.

pre_output

The function to be called for outbound packets.

event

The function to be called for interface events.

ioctl

The function to be called for ioctls.

detached

The function to be called for handling the detach.

Discussion

This structure is used to attach a protocol to an interface. This structure provides the various functions for handling operations related to the protocol on the interface as well as information for how to demux packets for this protocol.

Availability
  • Available in OS X v10.6 and later.
Declared In
kpi_interface.h

ifnet_demux_desc

struct ifnet_demux_desc {
   u_int32_t type;
   void *data;
   u_int32_t datalen;
};
Fields
type

The type of identifier data (i.e. ETHER_DESC_ETYPE2)

data

A pointer to an entry of type (i.e. pointer to 0x0800).

datalen

The number of bytes of data used to describe the packet.

Discussion

This structure is to identify packets that belong to a specific protocol. The types supported are interface specific. Ethernet supports ETHER_DESC_ETYPE2, ETHER_DESC_SAP, and ETHER_DESC_SNAP. The type defines the offset in the packet where the data will be matched as well as context. For example, if ETHER_DESC_SNAP is specified, the only valid datalen is 5 and only in the 5 bytes will only be matched when the packet header indicates that the packet is a SNAP packet.

Availability
  • Available in OS X v10.6 and later.
Declared In
kpi_interface.h

ifnet_init_params

struct ifnet_init_params {
   /* used to match recycled interface */
   const void *uniqueid; /* optional */
   u_int32_t uniqueid_len; /* optional */
   /* used to fill out initial values for interface */
   const char *name; /* required */
   u_int32_t unit; /* required */
   ifnet_family_t family; /* required */
   u_int32_t type; /* required */
   ifnet_output_func output; /* required */
   ifnet_demux_func demux; /* required  */
   ifnet_add_proto_func add_proto; /* required  */
   ifnet_del_proto_func del_proto; /* required  */
   ifnet_check_multi check_multi; /* required for non point-to-point interfaces */
   ifnet_framer_func framer; /* optional */
   void *softc; /* optional */
   ifnet_ioctl_func ioctl; /* optional */
   ifnet_set_bpf_tap set_bpf_tap; /* deprecated */
   ifnet_detached_func detach; /* optional */
   ifnet_event_func event; /* optional */
   const void *broadcast_addr; /* required for non point-to-point interfaces */
   u_int32_t broadcast_len; /* required for non point-to-point interfaces */
};
Fields
uniqueid

An identifier unique to this instance of the interface.

uniqueid_len

The length, in bytes, of the uniqueid.

name

The interface name (i.e. en).

unit

The interface unit number (en0's unit number is 0).

family

The interface family.

type

The interface type (see sys/if_types.h). Must be less than 256. For new types, use IFT_OTHER.

output

The output function for the interface. Every packet the stack attempts to send through this interface will go out through this function.

demux

The function used to determine the protocol family of an incoming packet.

add_proto

The function used to attach a protocol to this interface.

del_proto

The function used to remove a protocol from this interface.

framer

The function used to frame outbound packets, may be NULL.

softc

Driver specific storage. This value can be retrieved from the ifnet using the ifnet_softc function.

ioctl

The function used to handle ioctls.

set_bpf_tap

The function used to set the bpf_tap function.

detach

The function called to let the driver know the interface has been detached.

event

The function to notify the interface of various interface specific kernel events.

broadcast_addr

The link-layer broadcast address for this interface.

broadcast_len

The length of the link-layer broadcast address.

Discussion

This structure is used to define various properties of the interface when calling ifnet_allocate. A copy of these values will be stored in the ifnet and cannot be modified while the interface is attached.

Availability
  • Available in OS X v10.6 and later.
Declared In
kpi_interface.h

ifnet_stat_increment_param

struct ifnet_stat_increment_param {
   u_int32_t packets_in;
   u_int32_t bytes_in;
   u_int32_t errors_in;
   u_int32_t packets_out;
   u_int32_t bytes_out;
   u_int32_t errors_out;
   u_int32_t collisions;
   u_int32_t dropped;
};
Fields
packets_in

The number of packets received.

bytes_in

The number of bytes received.

errors_in

The number of receive errors.

packets_out

The number of packets transmitted.

bytes_out

The number of bytes transmitted.

errors_out

The number of transmission errors.

collisions

The number of collisions seen by this interface.

dropped

The number of packets dropped.

Discussion

This structure is used increment the counters on a network interface.

Availability
  • Available in OS X v10.6 and later.
Declared In
kpi_interface.h

ifnet_stats_param

struct ifnet_stats_param {
   u_int64_t packets_in;
   u_int64_t bytes_in;
   u_int64_t multicasts_in;
   u_int64_t errors_in;
   u_int64_t packets_out;
   u_int64_t bytes_out;
   u_int64_t multicasts_out;
   u_int64_t errors_out;
   u_int64_t collisions;
   u_int64_t dropped;
   u_int64_t no_protocol;
};
Fields
packets_in

The number of packets received.

bytes_in

The number of bytes received.

errors_in

The number of receive errors.

packets_out

The number of packets transmitted.

bytes_out

The number of bytes transmitted.

errors_out

The number of transmission errors.

collisions

The number of collisions seen by this interface.

dropped

The number of packets dropped.

Discussion

This structure is used get and set the interface statistics.

Availability
  • Available in OS X v10.6 and later.
Declared In
kpi_interface.h

Constants

See the Overview section above for header-level documentation.

BPF

Constants defining interface families.

enum {
   BPF_MODE_DISABLED = 0,
   BPF_MODE_INPUT = 1,
   BPF_MODE_OUTPUT = 2,
   BPF_MODE_INPUT_OUTPUT = 3
};
Constants
BPF_MODE_DISABLED

Disable bpf.

Available in OS X v10.4 and later.

Declared in kpi_interface.h.

BPF_MODE_INPUT

Enable input only.

Available in OS X v10.4 and later.

Declared in bpf.h.

BPF_MODE_OUTPUT

Enable output only.

Available in OS X v10.4 and later.

Declared in bpf.h.

BPF_MODE_INPUT_OUTPUT

Enable input and output.

Available in OS X v10.4 and later.

Declared in bpf.h.

Discussion

tap mode

Interface

Constants defining interface families.

enum {
   IFNET_FAMILY_ANY = 0,
   IFNET_FAMILY_LOOPBACK = 1,
   IFNET_FAMILY_ETHERNET = 2,
   IFNET_FAMILY_SLIP = 3,
   IFNET_FAMILY_TUN = 4,
   IFNET_FAMILY_VLAN = 5,
   IFNET_FAMILY_PPP = 6,
   IFNET_FAMILY_PVC = 7,
   IFNET_FAMILY_DISC = 8,
   IFNET_FAMILY_MDECAP = 9,
   IFNET_FAMILY_GIF = 10,
   IFNET_FAMILY_FAITH = 11, /* deprecated */
   IFNET_FAMILY_STF = 12,
   IFNET_FAMILY_FIREWIRE = 13,
   IFNET_FAMILY_BOND = 14,
   IFNET_FAMILY_CELLULAR = 15
};
Constants
IFNET_FAMILY_ANY

Match interface of any family type.

Available in OS X v10.4 and later.

Declared in kpi_interface.h.

IFNET_FAMILY_LOOPBACK

A software loopback interface.

Available in OS X v10.4 and later.

Declared in kpi_interface.h.

IFNET_FAMILY_ETHERNET

An Ethernet interface.

Available in OS X v10.4 and later.

Declared in kpi_interface.h.

IFNET_FAMILY_SLIP

A SLIP interface.

Available in OS X v10.4 and later.

Declared in kpi_interface.h.

IFNET_FAMILY_TUN

A tunnel interface.

Available in OS X v10.4 and later.

Declared in kpi_interface.h.

IFNET_FAMILY_VLAN

A virtual LAN interface.

Available in OS X v10.4 and later.

Declared in kpi_interface.h.

IFNET_FAMILY_PPP

A PPP interface.

Available in OS X v10.4 and later.

Declared in kpi_interface.h.

IFNET_FAMILY_PVC

A PVC interface.

Available in OS X v10.4 and later.

Declared in kpi_interface.h.

IFNET_FAMILY_DISC

A DISC interface.

Available in OS X v10.4 and later.

Declared in kpi_interface.h.

IFNET_FAMILY_MDECAP

A MDECAP interface.

Available in OS X v10.4 and later.

Declared in kpi_interface.h.

IFNET_FAMILY_GIF

A generic tunnel interface.

Available in OS X v10.4 and later.

Declared in kpi_interface.h.

IFNET_FAMILY_FAITH

A FAITH [IPv4/IPv6 translation] interface.

Available in OS X v10.4 and later.

Declared in kpi_interface.h.

IFNET_FAMILY_STF

A 6to4 interface.

Available in OS X v10.4 and later.

Declared in kpi_interface.h.

IFNET_FAMILY_FIREWIRE

An IEEE 1394 [Firewire] interface.

Available in OS X v10.4 and later.

Declared in kpi_interface.h.

IFNET_FAMILY_BOND

A virtual bonded interface.

Available in OS X v10.4 and later.

Declared in kpi_interface.h.

IFNET_FAMILY_CELLULAR

A cellular interface.

Available in OS X v10.7 and later.

Declared in kpi_interface.h.

Discussion

Families

Interface

Constants defining interface offload support.

enum {
   IFNET_CSUM_IP = 0x00000001,
   IFNET_CSUM_TCP = 0x00000002,
   IFNET_CSUM_UDP = 0x00000004,
   IFNET_CSUM_FRAGMENT = 0x00000008,
   IFNET_IP_FRAGMENT = 0x00000010,
   IFNET_CSUM_TCPIPV6 = 0x00000020,
   IFNET_CSUM_UDPIPV6 = 0x00000040,
   IFNET_IPV6_FRAGMENT = 0x00000080,
   IFNET_VLAN_TAGGING = 0x00010000,
   IFNET_VLAN_MTU = 0x00020000,
   IFNET_MULTIPAGES = 0x00100000,
   IFNET_TSO_IPV4 = 0x00200000,
   IFNET_TSO_IPV6 = 0x00400000,
   IFNET_TX_STATUS = 0x00800000
};
Constants
IFNET_CSUM_IP

Hardware will calculate IPv4 checksums.

Available in OS X v10.4 and later.

Declared in kpi_interface.h.

IFNET_CSUM_TCP

Hardware will calculate TCP checksums.

Available in OS X v10.4 and later.

Declared in kpi_interface.h.

IFNET_CSUM_UDP

Hardware will calculate UDP checksums.

Available in OS X v10.4 and later.

Declared in kpi_interface.h.

IFNET_CSUM_FRAGMENT

Hardware will checksum IP fragments.

Available in OS X v10.4 and later.

Declared in kpi_interface.h.

IFNET_IP_FRAGMENT

Hardware will fragment IP packets.

Available in OS X v10.4 and later.

Declared in kpi_interface.h.

IFNET_CSUM_TCPIPV6

Hardware will calculate TCP IPv6 checksums.

Available in OS X v10.7 and later.

Declared in kpi_interface.h.

IFNET_CSUM_UDPIPV6

Hardware will calculate UDP IPv6 checksums.

Available in OS X v10.7 and later.

Declared in kpi_interface.h.

IFNET_IPV6_FRAGMENT

Hardware will fragment IPv6 packets.

Available in OS X v10.7 and later.

Declared in kpi_interface.h.

IFNET_VLAN_TAGGING

Hardware will generate VLAN headers.

Available in OS X v10.4 and later.

Declared in kpi_interface.h.

IFNET_VLAN_MTU

Hardware supports VLAN MTU.

Available in OS X v10.4 and later.

Declared in kpi_interface.h.

IFNET_MULTIPAGES

Driver is capable of handling packets coming down from the network stack that reside in virtually, but not in physically contiguous span of the external mbuf clusters. In this case, the data area of a packet in the external mbuf cluster might cross one or more physical pages that are disjoint, depending on the interface MTU and the packet size. Such a use of larger than system page size clusters by the network stack is done for better system efficiency. Drivers that utilize the IOMbufNaturalMemoryCursor with the getPhysicalSegmentsWithCoalesce interfaces and enumerate the list of vectors should set this flag for possible gain in performance during bulk data transfer.

Available in OS X v10.5 and later.

Declared in kpi_interface.h.

IFNET_TSO_IPV4

Hardware supports IPv4 TCP Segment Offloading. If the Interface driver sets this flag, TCP will send larger frames (up to 64KB) as one frame to the adapter which will perform the final packetization. The maximum TSO segment supported by the interface can be set with "ifnet_set_tso_mtu". To retreive the real MTU for the TCP connection the function "mbuf_get_tso_requested" is used by the driver. Note that if TSO is active, all the packets will be flagged for TSO, not just large packets.

Available in OS X v10.6 and later.

Declared in kpi_interface.h.

IFNET_TSO_IPV6

Hardware supports IPv6 TCP Segment Offloading. If the Interface driver sets this flag, TCP IPv6 will send larger frames (up to 64KB) as one frame to the adapter which will perform the final packetization. The maximum TSO segment supported by the interface can be set with "ifnet_set_tso_mtu". To retreive the real MTU for the TCP IPv6 connection the function "mbuf_get_tso_requested" is used by the driver. Note that if TSO is active, all the packets will be flagged for TSO, not just large packets.

Available in OS X v10.6 and later.

Declared in kpi_interface.h.

IFNET_TX_STATUS

Driver supports returning a per packet transmission status (pass, fail or other errors) of whether the packet was successfully transmitted on the link, or the transmission was aborted, or transmission failed.

Available in OS X v10.9 and later.

Declared in kpi_interface.h.

Discussion

Abilities

Interface

Constants defining Interface wake properties.

enum {
   IFNET_WAKE_ON_MAGIC_PACKET = 0x01
};
Constants
IFNET_WAKE_ON_MAGIC_PACKET

Wake on Magic Packet.

Available in OS X v10.6 and later.

Declared in kpi_interface.h.

Discussion

wake properties