|
ADC Home > Reference Library > Reference > Darwin > Kernel Framework Reference
|
kpi_interface.h |
| Includes: |
<sys/kernel_types.h>
|
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.
ifaddr_address(ifaddr_t) |
sa_family_t ifaddr_address_family( ifaddr_t ifaddr);
ifaddrThe interface address.
0 on failure, address family on success.
Returns the address family of the address.
ifaddr_address(ifaddr_t, struct sockaddr *, u_int32_t) |
errno_t ifaddr_address( ifaddr_t ifaddr, struct sockaddr *out_addr, u_int32_t addr_size);
ifaddrThe interface address.
out_addrThe sockaddr storage for the address.
addr_sizeThe size of the storage for the address.
0 upon success
Copies the address out of the ifaddr.
ifaddr_address_family |
sa_family_t ifaddr_address_family( ifaddr_t ifaddr);
ifaddrThe interface address.
0 on failure, address family on success.
Returns the address family of the address.
ifaddr_dstaddress |
errno_t ifaddr_dstaddress( ifaddr_t ifaddr, struct sockaddr *out_dstaddr, u_int32_t dstaddr_size);
ifaddrThe interface address.
out_dstaddrThe sockaddr storage for the destination address.
dstaddr_sizeThe size of the storage for the destination address.
0 upon success
Copies the destination address out of the ifaddr.
ifaddr_findbestforaddr |
ifaddr_t ifaddr_findbestforaddr( const struct sockaddr *addr, ifnet_t interface);
addrThe remote address.
interfaceThe local interface.
A reference to the interface address.
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.
ifaddr_ifnet |
ifnet_t ifaddr_ifnet( ifaddr_t ifaddr);
ifaddrThe interface address.
A reference to the interface the address is attached to.
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.
ifaddr_netmask |
errno_t ifaddr_netmask( ifaddr_t ifaddr, struct sockaddr *out_netmask, u_int32_t netmask_size);
ifaddrThe interface address.
out_netmaskThe sockaddr storage for the netmask.
netmask_sizeThe size of the storage for the netmask.
0 upon success
Copies the netmask out of the ifaddr.
ifaddr_reference |
errno_t ifaddr_reference( ifaddr_t ifaddr);
ifaddrThe interface address.
0 upon success
Increment the reference count of an address tied to an interface.
ifaddr_release |
errno_t ifaddr_release( ifaddr_t ifaddr);
ifaddrThe interface address.
0 upon success
Decrements the reference count of and possibly frees an address tied to an interface.
ifaddr_withaddr |
ifaddr_t ifaddr_withaddr( const struct sockaddr* address);
addressThe address to search for.
A reference to the interface address.
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.
ifaddr_withdstaddr |
ifaddr_t ifaddr_withdstaddr( const struct sockaddr* destination);
destinationThe destination to search for.
A reference to the interface address.
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.
ifaddr_withnet |
ifaddr_t ifaddr_withnet( const struct sockaddr* net);
netThe network to search for.
A reference to the interface address.
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.
ifaddr_withroute |
ifaddr_t ifaddr_withroute( int flags, const struct sockaddr* destination, const struct sockaddr* gateway);
flagsRouting flags. See net/route.h, RTF_GATEWAY etc.
destinationThe destination to search for.
gatewayA gateway to search for.
A reference to the interface address.
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.
ifmaddr_address |
errno_t ifmaddr_address( ifmultiaddr_t ifmaddr, struct sockaddr *out_multicast, u_int32_t addr_size);
out_multicastStorage for a sockaddr.
addr_sizeSize of the storage.
0 on success.
Copies the multicast address to out_multicast.
ifmaddr_ifnet |
ifnet_t ifmaddr_ifnet( ifmultiaddr_t ifmaddr);
ifmaddrThe interface multicast address.
A reference to the interface.
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.
ifmaddr_lladdress |
errno_t ifmaddr_lladdress( ifmultiaddr_t ifmaddr, struct sockaddr *out_link_layer_multicast, u_int32_t addr_size);
out_link_layer_multicastStorage for a sockaddr.
addr_sizeSize of the storage.
0 on success.
Copies the link layer multicast address to out_link_layer_multicast.
ifmaddr_reference |
errno_t ifmaddr_reference( ifmultiaddr_t ifmaddr);
ifmaddrThe interface multicast address.
0 on success. Only error will be EINVAL if ifmaddr is not valid.
Increment the reference count of an interface multicast address.
ifmaddr_release |
errno_t ifmaddr_release( ifmultiaddr_t ifmaddr);
ifmaddrThe interface multicast address.
0 on success. Only error will be EINVAL if ifmaddr is not valid.
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.
ifnet_add_multicast |
errno_t ifnet_add_multicast( ifnet_t interface, const struct sockaddr *maddr, ifmultiaddr_t *multicast);
interfaceThe interface.
maddrThe multicast address to join. Either a physical address or logical address to be translated to a physical address.
multicastThe resulting ifmultiaddr_t multicast address.
0 on success otherwise the errno error.
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.
ifnet_addrlen |
u_int8_t ifnet_addrlen( ifnet_t interface);
interfaceThe interface.
The address length.
ifnet_allocate |
errno_t ifnet_allocate( const struct ifnet_init_params *init, ifnet_t *interface);
initThe initial values for the interface. These values can not be changed after the interface has been allocated.
interfaceThe interface allocated upon success.
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.
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.
ifnet_attach |
errno_t ifnet_attach( ifnet_t interface, const struct sockaddr_dl *ll_addr);
interfaceThe interface to attach.
ll_addrThe 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.
Will return an error if there is anything wrong with the interface.
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.
ifnet_attach_protocol |
errno_t ifnet_attach_protocol( ifnet_t interface, protocol_family_t protocol_family, const struct ifnet_attach_proto_param *proto_details);
interfaceThe interface.
protocol_familyThe protocol family being attached (PF_INET/PF_APPLETALK/etc...).
proto_detailsDetails of the protocol being attached.
0 on success otherwise the errno error.
Attaches a protocol to an interface.
ifnet_attach_protocol_v2 |
errno_t ifnet_attach_protocol_v2( ifnet_t interface, protocol_family_t protocol_family, const struct ifnet_attach_proto_param_v2 *proto_details);
interfaceThe interface.
protocol_familyThe protocol family being attached (PF_INET/PF_APPLETALK/etc...).
proto_detailsDetails of the protocol being attached.
0 on success otherwise the errno error.
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.
ifnet_baudrate |
u_int64_t ifnet_baudrate( ifnet_t interface);
interfaceThe interface.
The baudrate.
ifnet_detach |
errno_t ifnet_detach( ifnet_t interface);
interfaceThe interface to detach.
0 on success, otherwise errno error.
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.
ifnet_detach_protocol |
errno_t ifnet_detach_protocol( ifnet_t interface, protocol_family_t protocol_family);
interfaceThe interface.
protocol_familyThe protocol family of the protocol to detach.
0 on success otherwise the errno error.
Detaches a protocol from an interface.
ifnet_event |
errno_t ifnet_event( ifnet_t interface, struct kern_event_msg *event_ptr);
interfaceThe interface.
event_ptrPointer to an kern_event structure describing the event.
0 on success otherwise the errno error.
Calls the interface's event function.
ifnet_family |
ifnet_family_t ifnet_family( ifnet_t interface);
interfaceInterface to retrieve the unit number from.
Unit number.
Returns the family of the interface.
ifnet_find_by_name |
errno_t ifnet_find_by_name( const char *ifname, ifnet_t *interface);
nameThe name of the interface, including any unit number (i.e. "en0").
interfaceA pointer to an interface reference. This will be filled in if a matching interface is found.
0 on success otherwise the errno error.
Find an interface by the name including the unit number. Caller must call ifnet_release on any non-null interface return value.
ifnet_flags |
u_int16_t ifnet_flags( ifnet_t interface);
interfaceInterface to retrieve the flags from.
Flags. These flags are defined in net/if.h
Returns the interface flags that are set.
ifnet_free_address_list |
void ifnet_free_address_list( ifaddr_t *addresses);
addressesAn array of ifaddr_ts.
Free a list of addresses returned from ifnet_get_address_list. Decrements the refcounts and frees the memory used for the array of references.
ifnet_free_multicast_list |
void ifnet_free_multicast_list( ifmultiaddr_t *multicasts);
multicastsAn array of references to the multicast addresses.
0 on success otherwise the errno error.
Frees a list of multicasts returned by ifnet_get_multicast_list. Decrements the refcount on each multicast address and frees the array.
ifnet_get_address_list |
errno_t ifnet_get_address_list( ifnet_t interface, ifaddr_t **addresses);
interfaceThe interface.
addressesA pointer to a NULL terminated array of ifaddr_ts.
0 on success otherwise the errno error.
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.
ifnet_get_address_list_family |
errno_t ifnet_get_address_list_family( ifnet_t interface, ifaddr_t **addresses, sa_family_t family);
interfaceThe interface.
addressesA pointer to a NULL terminated array of ifaddr_ts.
0 on success otherwise the errno error.
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.
ifnet_get_link_mib_data |
errno_t ifnet_get_link_mib_data( ifnet_t interface, void *mibData, u_int32_t *mibLen);
interfaceThe interface.
mibDataA pointer to space for the mibData to be copied in to.
mibLenWhen 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.
Returns an error if the buffer size is too small or there is no data.
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.
ifnet_get_link_mib_data_length |
u_int32_t ifnet_get_link_mib_data_length( ifnet_t interface);
interfaceThe interface.
Returns the number of bytes of mib data associated with the interface.
Retrieve the size of the mib data.
ifnet_get_multicast_list |
errno_t ifnet_get_multicast_list( ifnet_t interface, ifmultiaddr_t **addresses);
interfaceThe interface.
multicastsA pointer to a NULL terminated array of references to the multicast addresses.
0 on success otherwise the errno error.
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.
ifnet_hdrlen |
u_int8_t ifnet_hdrlen( ifnet_t interface);
interfaceThe interface.
The header length.
ifnet_index |
u_int32_t ifnet_index( ifnet_t interface);
interfaceInterface to retrieve the index of.
Index.
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.
ifnet_input |
errno_t ifnet_input( ifnet_t interface, mbuf_t first_packet, const struct ifnet_stat_increment_param *stats);
interfaceThe interface.
first_packetThe first packet in a chain of packets.
statsCounts to be integrated in to the stats. The interface statistics will be incremented by the amounts specified in stats. This parameter may be NULL.
0 on success otherwise the errno error.
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.
ifnet_ioctl |
errno_t ifnet_ioctl( ifnet_t interface, protocol_family_t protocol, u_int32_t ioctl_code, void *ioctl_arg);
interfaceThe interface.
protocolThe 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_codeThe ioctl to perform.
ioctl_argAny parameters to the ioctl.
0 on success otherwise the errno error.
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.
ifnet_lastchange |
errno_t ifnet_lastchange( ifnet_t interface, struct timeval *last_change);
interfaceThe interface.
last_changeA timeval struct to copy the last time changed in to.
ifnet_list_free |
void ifnet_list_free( ifnet_t *interfaces);
interfacesAn array of interface references from ifnet_list_get.
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.
ifnet_list_get |
errno_t ifnet_list_get( ifnet_family_t family, ifnet_t **interfaces, u_int32_t *count);
familyThe interface family (i.e. IFNET_FAMILY_ETHERNET). To find interfaces of all families, use IFNET_FAMILY_ANY.
interfacesA pointer to an array of interface references.
countA pointer that will be filled in with the number of matching interfaces in the array.
0 on success otherwise the errno error.
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.
ifnet_lladdr_copy_bytes |
errno_t ifnet_lladdr_copy_bytes( ifnet_t interface, void *lladdr, size_t length);
interfaceThe interface to copy the link-layer address from.
lladdrThe buffer to copy the link-layer address in to.
lengthThe length of the buffer. This value must match the length of the link-layer address.
Copies the bytes of the link-layer address in to the specified buffer.
ifnet_llbroadcast_copy_bytes |
errno_t ifnet_llbroadcast_copy_bytes( ifnet_t interface, void *addr, size_t bufferlen, size_t *addr_len);
interfaceThe interface.
addrA buffer to copy the broadcast address in to.
bufferlenThe length of the buffer at addr.
addr_lenOn return, the length of the broadcast address.
lladdr_lenThe length, in bytes, of the link layer address.
Retrieves the link-layer broadcast address for this interface.
ifnet_metric |
u_int32_t ifnet_metric( ifnet_t interface);
interfaceThe interface.
The metric.
ifnet_mtu |
u_int32_t ifnet_mtu( ifnet_t interface);
interfaceThe interface.
The MTU.
ifnet_name |
const char* ifnet_name(ifnet_t interface);
interfaceInterface to retrieve the name from.
Pointer to the name.
Returns a pointer to the name of the interface.
ifnet_offload |
ifnet_offload_t ifnet_offload( ifnet_t interface);
interfaceInterface to retrieve the offload from.
Abilities flags, see ifnet_offload_t.
Returns flags indicating which operations can be offloaded to the interface.
ifnet_output |
errno_t ifnet_output( ifnet_t interface, protocol_family_t protocol_family, mbuf_t packet, void *route, const struct sockaddr *dest);
interfaceThe interface.
protocol_familyThe family of the protocol generating this packet (i.e. AF_INET).
packetThe packet to be transmitted.
routeA pointer to a routing structure for this packet. The preoutput function determines whether this value may be NULL or not.
destThe 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.
0 on success otherwise the errno error.
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.
ifnet_output_raw |
errno_t ifnet_output_raw( ifnet_t interface, protocol_family_t protocol_family, mbuf_t packet);
interfaceThe interface.
protocol_familyThe family of the protocol generating this packet (i.e. AF_INET).
packetThe fully formed packet to be transmitted.
0 on success otherwise the errno error.
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.
ifnet_reference |
errno_t ifnet_reference( ifnet_t interface);
interfaceThe interface to increment the reference count of.
May return EINVAL if the interface is not valid.
Increment the reference count of the ifnet to assure that it will not go away. The interface must already have at least one reference.
ifnet_release |
errno_t ifnet_release( ifnet_t interface);
interfaceThe interface to decrement the reference count of and possibly free.
May return EINVAL if the interface is not valid.
Release a reference of the ifnet, this may trigger a free if the reference count reaches 0.
ifnet_remove_multicast |
errno_t ifnet_remove_multicast( ifmultiaddr_t multicast);
multicastThe multicast to be removed.
0 on success otherwise the errno error.
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.
ifnet_resolve_multicast |
errno_t ifnet_resolve_multicast( ifnet_t ifp, const struct sockaddr *proto_addr, struct sockaddr *ll_addr, size_t ll_len);
interfaceThe interface.
proto_addrA protocol address to be converted to a link-layer address.
ll_addrStorage for the resulting link-layer address.
ll_lenLength of the storage for the link-layer address.
0 on success. EOPNOTSUPP indicates the multicast address was not supported or could not be translated. Other errors may indicate other failures.
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.
ifnet_set_addrlen |
errno_t ifnet_set_addrlen( ifnet_t interface, u_int8_t addrlen);
interfaceThe interface.
addrlenThe new address length.
0 on success otherwise the errno error.
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.
ifnet_set_baudrate |
errno_t ifnet_set_baudrate( ifnet_t interface, u_int64_t baudrate);
interfaceThe interface.
baudrateThe new baudrate.
0 on success otherwise the errno error.
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.
ifnet_set_flags |
errno_t ifnet_set_flags( ifnet_t interface, u_int16_t new_flags, u_int16_t mask);
interfaceInterface to set the flags on.
new_flagsThe new set of flags that should be set. These flags are defined in net/if.h
0 on success otherwise the errno error.
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).
ifnet_set_hdrlen |
errno_t ifnet_set_hdrlen( ifnet_t interface, u_int8_t hdrlen);
interfaceThe interface.
hdrlenThe new header length.
0 on success otherwise the errno error.
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.
ifnet_set_link_mib_data |
errno_t ifnet_set_link_mib_data( ifnet_t interface, void *mibData, u_int32_t mibLen);
interfaceInterface to set the unit number of.
mibDataA pointer to the data.
mibLenLength of data pointed to.
0 on success otherwise the errno error.
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.
ifnet_set_lladdr |
errno_t ifnet_set_lladdr( ifnet_t interface, const void* lladdr, size_t lladdr_len);
interfaceThe interface the link layer address is being changed on.
lladdrA pointer to the raw link layer address (pointer to the 6 byte ethernet address for ethernet).
lladdr_lenThe length, in bytes, of the link layer address.
Sets the link-layer address for this interface.
ifnet_set_metric |
errno_t ifnet_set_metric( ifnet_t interface, u_int32_t metric);
interfaceThe interface.
metricThe new metric.
0 on success otherwise the errno error.
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.
ifnet_set_mtu |
errno_t ifnet_set_mtu( ifnet_t interface, u_int32_t mtu);
interfaceThe interface.
mtuThe new MTU.
0 on success otherwise the errno error.
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.
ifnet_set_offload |
errno_t ifnet_set_offload( ifnet_t interface, ifnet_offload_t offload);
interfaceThe interface.
offloadThe new set of flags indicating which offload options the device supports.
maskThe mask of flags to be modified.
0 on success otherwise the errno error.
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.
ifnet_set_promiscuous |
errno_t ifnet_set_promiscuous( ifnet_t interface, int on);
interfaceThe interface to toggle promiscuous mode on.
onIf 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.
0 on success otherwise the errno error.
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.
ifnet_set_stat |
errno_t ifnet_set_stat( ifnet_t interface, const struct ifnet_stats_param *stats);
interfaceThe interface.
countsThe new stats values.
0 on success otherwise the errno error.
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.
ifnet_softc |
void* ifnet_softc( ifnet_t interface);
interfaceInterface to retrieve the storage from.
Driver's private storage.
Returns the driver's private storage on the interface.
ifnet_stat |
errno_t ifnet_stat( ifnet_t interface, struct ifnet_stats_param *out_stats);
interfaceThe interface.
out_statsStorage for the values.
0 on success otherwise the errno error.
ifnet_stat_increment |
errno_t ifnet_stat_increment( ifnet_t interface, const struct ifnet_stat_increment_param *counts);
interfaceThe interface.
countsA 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.
0 on success otherwise the errno error.
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.
ifnet_stat_increment_in |
errno_t ifnet_stat_increment_in( ifnet_t interface, u_int32_t packets_in, u_int32_t bytes_in, u_int32_t errors_in);
interfaceThe interface.
packets_inThe number of additional packets received.
bytes_inThe number of additional bytes received.
errors_inThe number of additional receive errors.
0 on success otherwise the errno error.
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.
ifnet_stat_increment_out |
errno_t ifnet_stat_increment_out( ifnet_t interface, u_int32_t packets_out, u_int32_t bytes_out, u_int32_t errors_out);
interfaceThe interface.
packets_outThe number of additional packets sent.
bytes_outThe number of additional bytes sent.
errors_outThe number of additional send errors.
0 on success otherwise the errno error.
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.
ifnet_touch_lastchange |
errno_t ifnet_touch_lastchange( ifnet_t interface);
interfaceThe interface.
0 on success otherwise the errno error.
Updates the lastchange value to now.
ifnet_type |
u_int8_t ifnet_type( ifnet_t interface);
interfaceThe interface.
The type. See net/if_types.h.
ifnet_unit |
u_int32_t ifnet_unit( ifnet_t interface);
interfaceInterface to retrieve the unit number from.
Unit number.
Returns the unit number of the interface.
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);
interfaceThe interface being sent or received on.
dataThe packet to be transmitted or received.
An errno value or zero upon success.
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.
bpf_tap_mode |
Mode for tapping. BPF_MODE_DISABLED/BPF_MODE_INPUT_OUTPUT etc.
typedef u_int32_t bpf_tap_mode;
if_del_proto_func |
typedef errno_t ( *ifnet_del_proto_func)( ifnet_t interface, protocol_family_t protocol_family);
interfaceThe interface the protocol will be detached from.
protocol_familyThe family of the protocol being detached.
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.
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.
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);
interfaceThe interface the protocol will be attached to.
protocol_familyThe family of the protocol being attached.
demux_arrayAn array of demux descriptors that describe the interface specific ways of identifying packets belonging to this protocol family.
demux_countThe number of demux descriptors in the array.
If the result is zero, processing will continue normally. If the result is anything else, the add protocol will be aborted.
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).
ifnet_check_multi |
typedef errno_t ( *ifnet_check_multi)( ifnet_t interface, const struct sockaddr* mcast);
Theinterface.
mcastThe multicast address.
Zero upon success, EADDRNOTAVAIL on invalid multicast, EOPNOTSUPP for addresses the interface does not understand.
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.
ifnet_del_proto_func |
typedef errno_t ( *ifnet_del_proto_func)( ifnet_t interface, protocol_family_t protocol_family);
interfaceThe interface the protocol will be detached from.
protocol_familyThe family of the protocol being detached.
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.
ifnet_demux_func |
typedef errno_t ( *ifnet_demux_func)( ifnet_t interface, mbuf_t packet, char *frame_header, protocol_family_t *protocol_family);
interfaceThe interface the packet was received on.
packetThe mbuf containing the packet.
frame_headerA pointer to the frame header.
protocol_familyUpon return, the protocol family matching the packet should be stored here.
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.
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.
ifnet_detached_func |
typedef void ( *ifnet_detached_func)( ifnet_t interface);
interfaceThe interface that has been detached. event.
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.
ifnet_event_func |
typedef void ( *ifnet_event_func)( ifnet_t interface, const struct kev_msg *msg);
interfaceThe interface the event occurred on.
event_ptrPointer to a kern_event structure describing the event.
ifnet_event_func is called when an event occurs on a specific interface.
ifnet_family_t |
Storage type for the interface family.
typedef u_int32_t ifnet_family_t;
ifnet_framer_func |
typedef errno_t ( *ifnet_framer_func)( ifnet_t interface, mbuf_t *packet, const struct sockaddr *dest, const char *desk_linkaddr, const char *frame_type);
interfaceThe interface the packet is being sent on.
packetPointer 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.
destThe higher layer protocol destination (i.e. IP address).
dest_linkaddrThe link layer address as determined by the protocol's pre-output function.
frame_typeThe frame type as determined by the protocol's pre-output function.
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.
ifnet_framer_func is called for each outbound packet to give the interface an opportunity to prepend interface specific headers.
ifnet_ioctl_func |
typedef errno_t ( *ifnet_ioctl_func)( ifnet_t interface, u_int32_t cmd, void *data);
interfaceThe interface the ioctl is being sent to.
proto_familyThe protocol family to handle the ioctl, may be zero for no protocol_family.
cmdThe ioctl command.
dataA pointer to any data related to the ioctl.
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.
ifnet_offload_t |
Flags indicating the offload support of the interface.
typedef u_int32_t ifnet_offload_t;
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);
interfaceThe interface being sent on.
dataThe packet to be sent.
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.
ifnet_set_bpf_tap |
typedef errno_t ( *ifnet_set_bpf_tap)( ifnet_t interface, bpf_tap_mode mode, bpf_packet_func callback);
Deprecated. Specify NULL. Call bpf_tap_in/bpf_tap_out for all packets.
proto_media_detached |
typedef errno_t ( *proto_media_detached)( ifnet_t ifp, protocol_family_t protocol);
ifpThe interface.
protocol_familyThe protocol family.
See the discussion.
proto_media_detached notifies you that your protocol has been detached.
proto_media_event |
typedef void ( *proto_media_event)( ifnet_t ifp, protocol_family_t protocol, const struct kev_msg *event);
ifpThe interface.
protocol_familyThe protocol family.
kev_msgThe event.
proto_media_event is called to notify this layer of interface specific events.
proto_media_input |
typedef errno_t ( *proto_media_input)( ifnet_t ifp, protocol_family_t protocol, mbuf_t packet, char *header);
ifpThe interface the packet was received on.
protocol_familyThe protocol of the packet received.
packetThe packet being input.
headerThe frame header.
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.
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.
proto_media_input_v2 |
typedef errno_t ( *proto_media_input_v2)( ifnet_t ifp, protocol_family_t protocol, mbuf_t packet);
ifpThe interface the packet was received on.
protocol_familyThe protocol of the packet received.
packetThe packet being input.
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.
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.
proto_media_ioctl |
typedef errno_t ( *proto_media_ioctl)( ifnet_t ifp, protocol_family_t protocol, u_int32_t command, void *argument);
ifpThe interface.
protocol_familyThe protocol family.
commandThe ioctl command.
argumentThe argument to the ioctl.
See the 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.
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);
ifpThe interface the packet will be sent on.
protocol_familyThe protocol of the packet being sent (PF_INET/etc...).
packetThe packet being sent.
destThe protocol level destination address.
routeA pointer to the routing structure for the packet.
frame_typeThe media specific frame type.
link_layer_destThe media specific destination.
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.
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.
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);
ifpThe interface.
proto_addrThe protocol address.
out_llA sockaddr_dl to copy the link layer multicast in to.
ll_lenThe length of data allocated for out_ll.
Return zero on success or an errno error value on failure.
proto_media_resolve_multi is called to resolve a protocol layer mulitcast address to a link layer multicast address.
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);
ifpThe interface the arp packet should be sent on.
protocol_familyThe protocol family of the addresses (PF_INET).
arpopThe arp operation (usually ARPOP_REQUEST or ARPOP_REPLY).
sender_hwThe value to use for the sender hardware address field. If this is NULL, use the hardware address of the interface.
sender_protoThe value to use for the sender protocol address field. This will not be NULL.
target_hwThe 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_protoThe target protocol address. This will not be NULL.
Return zero on success or an errno error value on failure.
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.
protocol_family_t |
Storage type for the protocol family.
typedef u_int32_t protocol_family_t;
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 */ };
demux_arrayAn array of ifnet_demux_desc structures describing the protocol.
demux_countThe number of entries in the demux_array array.
inputThe function to be called for inbound packets.
pre_outputThe function to be called for outbound packets.
eventThe function to be called for interface events.
ioctlThe function to be called for ioctls.
detachedThe function to be called for handling the detach.
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.
ifnet_demux_desc |
struct ifnet_demux_desc { u_int32_t type; void *data; u_int32_t datalen; };
typeThe type of identifier data (i.e. ETHER_DESC_ETYPE2)
dataA pointer to an entry of type (i.e. pointer to 0x0800).
datalenThe number of bytes of data used to describe the packet.
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.
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 */ };
uniqueidAn identifier unique to this instance of the interface.
uniqueid_lenThe length, in bytes, of the uniqueid.
nameThe interface name (i.e. en).
unitThe interface unit number (en0's unit number is 0).
familyThe interface family.
typeThe interface type (see sys/if_types.h). Must be less than 256. For new types, use IFT_OTHER.
outputThe output function for the interface. Every packet the stack attempts to send through this interface will go out through this function.
demuxThe function used to determine the protocol family of an incoming packet.
add_protoThe function used to attach a protocol to this interface.
del_protoThe function used to remove a protocol from this interface.
framerThe function used to frame outbound packets, may be NULL.
softcDriver specific storage. This value can be retrieved from the ifnet using the ifnet_softc function.
ioctlThe function used to handle ioctls.
set_bpf_tapThe function used to set the bpf_tap function.
detachThe function called to let the driver know the interface has been detached.
eventThe function to notify the interface of various interface specific kernel events.
broadcast_addrThe link-layer broadcast address for this interface.
broadcast_lenThe length of the link-layer broadcast address.
This structure is used to define various properties of the interface when calling ifnet_init. A copy of these values will be stored in the ifnet and can not be modified while the interface is attached.
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; };
packets_inThe number of packets received.
bytes_inThe number of bytes received.
errors_inThe number of receive errors.
packets_outThe number of packets transmitted.
bytes_outThe number of bytes transmitted.
errors_outThe number of transmission errors.
collisionsThe number of collisions seen by this interface.
droppedThe number of packets dropped.
This structure is used increment the counters on a network interface.
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; };
packets_inThe number of packets received.
bytes_inThe number of bytes received.
errors_inThe number of receive errors.
packets_outThe number of packets transmitted.
bytes_outThe number of bytes transmitted.
errors_outThe number of transmission errors.
collisionsThe number of collisions seen by this interface.
droppedThe number of packets dropped.
This structure is used get and set the interface statistics.
BPF |
Constants defining interface families.
enum { BPF_MODE_DISABLED = 0, BPF_MODE_INPUT = 1, BPF_MODE_OUTPUT = 2, BPF_MODE_INPUT_OUTPUT = 3 };
BPF_MODE_DISABLEDDisable bpf.
BPF_MODE_INPUTEnable input only.
BPF_MODE_OUTPUTEnable output only.
BPF_MODE_INPUT_OUTPUTEnable input and output.
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, IFNET_FAMILY_STF = 12, IFNET_FAMILY_FIREWIRE = 13, IFNET_FAMILY_BOND = 14 };
IFNET_FAMILY_ANYMatch interface of any family type.
IFNET_FAMILY_LOOPBACKA software loopback interface.
IFNET_FAMILY_ETHERNETAn Ethernet interface.
IFNET_FAMILY_SLIPA SLIP interface.
IFNET_FAMILY_TUNA tunnel interface.
IFNET_FAMILY_VLANA virtual LAN interface.
IFNET_FAMILY_PPPA PPP interface.
IFNET_FAMILY_PVCA PVC interface.
IFNET_FAMILY_DISCA DISC interface.
IFNET_FAMILY_MDECAPA MDECAP interface.
IFNET_FAMILY_GIFA generic tunnel interface.
IFNET_FAMILY_FAITHA FAITH (IPv4/IPv6 translation) interface.
IFNET_FAMILY_STFA 6to4 interface.
IFNET_FAMILY_FIREWIREAn IEEE 1394 (firewire) interface.
IFNET_FAMILY_BONDA virtual bonded interface.
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_VLAN_TAGGING = 0x00010000, IFNET_VLAN_MTU = 0x00020000, IFNET_MULTIPAGES = 0x00100000, };
IFNET_CSUM_IPHardware will calculate IPv4 checksums.
IFNET_CSUM_TCPHardware will calculate TCP checksums.
IFNET_CSUM_UDPHardware will calculate UDP checksums.
IFNET_CSUM_FRAGMENTHardware will checksum IP fragments.
IFNET_IP_FRAGMENTHardware will fragment IP packets.
IFNET_VLAN_TAGGINGHardware will generate VLAN headers.
IFNET_VLAN_MTUHardware supports VLAN MTU.
IFNET_MULTIPAGESDriver 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.
|
Last Updated: 2008-12-19