sl@0: /** @file ../include/net/if.h
sl@0: @internalComponent
sl@0: */
sl@0: 
sl@0: 
sl@0: /** @def IF_NAMESIZE	
sl@0: 
sl@0: Length of interface external name, including terminating '\\0'.
sl@0: Limitation: IAP names in P.I.P.S. are restricted to 49 bytes in ASCII. For names in languages with a multi-byte character set,
sl@0: you can go upto 24 characters for 2-byte and 16 characters for 3-byte representations. 
sl@0: All lengths are excluding the terminal NULL character.
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  if_freenameindex(struct if_nameindex *ptr)
sl@0: @param ptr
sl@0: 
sl@0: Refer to if_nametoindex() for the documentation
sl@0: 
sl@0: 
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: 
sl@0: 
sl@0: /** @fn  if_nameindex(void)
sl@0: 
sl@0: Refer to if_nametoindex() for the documentation
sl@0: 
sl@0: 
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: 
sl@0: 
sl@0: /** @fn  if_indextoname(unsigned int ifindex, char *ifname)
sl@0: @param ifindex
sl@0: @param ifname
sl@0: 
sl@0: Refer to if_nametoindex() for the documentation
sl@0: 
sl@0: 
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: 
sl@0: /** @fn  if_nametoindex(const char *ifname)
sl@0: @param ifname
sl@0: 
sl@0: Note: This description also covers the following functions -
sl@0:  if_indextoname()  if_nameindex()  if_freenameindex() 
sl@0: 
sl@0: @return   Upon successful completion, if_nametoindex returns the index number of the interface.
sl@0: If the interface is not found, a value of 0 is returned and errno is set to ENXIO. Upon successful completion, if_indextoname returns ifname. If the interface is not found, a NULL pointer is returned and errno is set to ENXIO. The if_nameindex returns a NULL pointer if sufficient memory cannot be allocated.
sl@0: 
sl@0:   The if_nametoindex function maps the interface name specified in ifname to its corresponding index.
sl@0: If the specified interface does not exist, it returns 0.
sl@0: 
sl@0:  The if_indextoname function maps the interface index specified in ifindex to it corresponding name, which is copied into the
sl@0: buffer pointed to by ifname, which must be of at least IFNAMSIZ bytes.
sl@0: This pointer is also the return value of the function.
sl@0: If there is no interface corresponding to the specified
sl@0: index, NULL is returned.
sl@0: 
sl@0: @code
sl@0:  The if_nameindex function returns an array of if_nameindex structures, one structure per interface, as defined in the include 
sl@0:   file #include <net/if.h>; 
sl@0:   The if_nameindex structure contains at least the following entries: 
sl@0:   unsigned int   if_index;  /* 1, 2, ... */
sl@0:     char          *if_name;   /* null terminated name: "le0", ... */
sl@0: @endcode
sl@0: 
sl@0:  The end of the array of structures is indicated by a structure with an if_index of 0 and an if_name of NULL. A NULL pointer is returned upon an error.
sl@0: 
sl@0:  The if_freenameindex function frees the dynamic memory that was
sl@0: allocated by if_nameindex.
sl@0: 
sl@0: 
sl@0: 
sl@0: 
sl@0: 
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: 
sl@0: 
sl@0: /** @struct if_nameindex
sl@0: 
sl@0: Includes the following members,
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @var if_nameindex::if_index
sl@0: 
sl@0: Numeric index of the interface. 
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var if_nameindex::if_name
sl@0: 
sl@0: Null-terminated name of the interface. 
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @struct if_clonereq
sl@0: 
sl@0: Structure used to query names of interface cloners.
sl@0: 
sl@0: @publishedAll
sl@0: @released
sl@0: */
sl@0: 
sl@0: /** @var if_clonereq::ifcr_total
sl@0: 
sl@0: total cloners (out)
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var if_clonereq::ifcr_count
sl@0: 
sl@0: room for this many in user buffer
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var if_clonereq::ifcr_buffer
sl@0: 
sl@0: buffer for cloner names
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @struct if_data
sl@0: 
sl@0: Structure describing information about an interface which may be of interest to management entities.
sl@0: 
sl@0: @publishedAll
sl@0: @released
sl@0: */
sl@0: 
sl@0: /** @var if_data::ifi_type
sl@0: 
sl@0: generic interface information. 
sl@0: ethernet, tokenring, etc
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var if_data::ifi_physical
sl@0: 
sl@0: generic interface information
sl@0: e.g., AUI, Thinnet, 10base-T, etc
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var if_data::ifi_addrlen
sl@0: 
sl@0: generic interface information
sl@0: media address length 
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var if_data::ifi_hdrlen
sl@0: 
sl@0: generic interface information
sl@0: media header length
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var if_data::ifi_link_state
sl@0: 
sl@0: generic interface information
sl@0: current link state
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var if_data::ifi_recvquota
sl@0: 
sl@0: generic interface information
sl@0: polling quota for receive intrs
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var if_data::ifi_xmitquota
sl@0: 
sl@0: generic interface information
sl@0: polling quota for xmit intrs
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var if_data::ifi_datalen
sl@0: 
sl@0: generic interface information
sl@0: length of this data struct 
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var if_data::ifi_mtu
sl@0: 
sl@0: generic interface information
sl@0: maximum transmission unit
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var if_data::ifi_metric
sl@0: 
sl@0: generic interface information
sl@0: routing metric (external only)
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var if_data::ifi_baudrate
sl@0: 
sl@0: generic interface information
sl@0: linespeed
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var if_data::ifi_ipackets
sl@0: 
sl@0: volatile statistics.
sl@0: packets received on interface 
sl@0: 
sl@0: */
sl@0: /** @var if_data::ifi_ierrors
sl@0: 
sl@0: volatile statistics.
sl@0: input errors on interface
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var if_data::ifi_opackets
sl@0: 
sl@0: volatile statistics.
sl@0: packets sent on interface.
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var if_data::ifi_oerrors
sl@0: 
sl@0: volatile statistics.
sl@0: output errors on interface.
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var if_data::ifi_collisions
sl@0: 
sl@0: volatile statistics.
sl@0: collisions on csma interfaces.
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var if_data::ifi_ibytes
sl@0: 
sl@0: volatile statistics.
sl@0: total number of octets received.
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var if_data::ifi_obytes
sl@0: 
sl@0: volatile statistics.
sl@0: total number of octets sent.
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var if_data::ifi_imcasts
sl@0: 
sl@0: volatile statistics.
sl@0: packets received via multicast.
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var if_data::ifi_omcasts
sl@0: 
sl@0: volatile statistics.
sl@0: packets sent via multicast
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var if_data::ifi_iqdrops
sl@0: 
sl@0: volatile statistics.
sl@0: dropped on input, this interface.
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var if_data::ifi_noproto
sl@0: 
sl@0: volatile statistics.
sl@0: destined for unsupported protocol.
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var if_data::ifi_hwassist
sl@0: 
sl@0: volatile statistics.
sl@0: HW offload capabilities
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var if_data::ifi_epoch
sl@0: 
sl@0: volatile statistics.
sl@0: uptime at attach or stat reset.
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var if_data::ifi_timepad
sl@0: 
sl@0: volatile statistics.
sl@0: time_t is int, not long on alpha.
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var if_data::ifi_lastchange
sl@0: 
sl@0: volatile statistics.
sl@0: time of last administrative change
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @struct if_msghdr
sl@0: 
sl@0: Message format for use in obtaining information about interfaces from getkerninfo and the routing socket
sl@0: 
sl@0: @publishedAll
sl@0: @released
sl@0: */
sl@0: 
sl@0: /** @struct ifa_msghdr
sl@0: 
sl@0: Message format for use in obtaining information about interface addresses from getkerninfo and the routing socket
sl@0: 
sl@0: @publishedAll
sl@0: @released
sl@0: */
sl@0: 
sl@0: /** @var ifa_msghdr::ifam_msglen
sl@0: 
sl@0: to skip over non-understood messages
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var ifa_msghdr::ifam_version
sl@0: 
sl@0: future binary compatibility
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var ifa_msghdr::ifam_type
sl@0: 
sl@0: message type
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var ifa_msghdr::ifam_addrs
sl@0: 
sl@0: like rtm_addrs
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var ifa_msghdr::ifam_flags
sl@0: 
sl@0: value of ifa_flags
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var ifa_msghdr::ifam_index
sl@0: 
sl@0: index for associated ifp
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var ifa_msghdr::ifam_metric
sl@0: 
sl@0: index for associated ifp
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @struct ifma_msghdr
sl@0: 
sl@0: Message format for use in obtaining information about multicast addresses from the routing socket
sl@0: 
sl@0: @publishedAll
sl@0: @released
sl@0: */
sl@0: 
sl@0: /** @var ifma_msghdr::ifmam_msglen
sl@0: 
sl@0: to skip over non-understood messages
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var ifma_msghdr::ifmam_version
sl@0: 
sl@0: future binary compatibility
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var ifma_msghdr::ifmam_type
sl@0: 
sl@0: message type
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var ifma_msghdr::ifmam_addrs
sl@0: 
sl@0: like rtm_addrs
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var ifma_msghdr::ifmam_flags
sl@0: 
sl@0: value of ifa_flags
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var ifma_msghdr::ifmam_index
sl@0: 
sl@0: index for associated ifp
sl@0: 
sl@0: */
sl@0: 
sl@0: 
sl@0: /** @struct if_announcemsghdr
sl@0: 
sl@0: Message format announcing the arrival or departure of a network interface.
sl@0: 
sl@0: @publishedAll
sl@0: @released
sl@0: */
sl@0: 
sl@0: /** @var if_announcemsghdr::ifan_msglen
sl@0: 
sl@0: to skip over non-understood messages
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var if_announcemsghdr::ifan_version
sl@0: 
sl@0: future binary compatibility
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var if_announcemsghdr::ifan_type
sl@0: 
sl@0: message type
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var if_announcemsghdr::ifan_index
sl@0: 
sl@0: index for associated ifp
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var if_announcemsghdr::ifan_name
sl@0: 
sl@0: if name, e.g. "en0"
sl@0: 
sl@0: */
sl@0: 
sl@0: /** @var if_announcemsghdr::ifan_what
sl@0: 
sl@0: what type of announcement
sl@0: 
sl@0: */
sl@0: 
sl@0: 
sl@0: /** @struct ifreq
sl@0: 
sl@0: Interface request structure used for socket ioctl's.  
sl@0: All interface ioctl's must have parameter definitions which begin with ifr_name.  The remainder may be interface specific.
sl@0: 
sl@0: @publishedAll
sl@0: @released
sl@0: */
sl@0: 
sl@0: /** @struct ifconf
sl@0: 
sl@0: Structure used in SIOCGIFCONF request.
sl@0: Used to retrieve interface configuration for machine (useful for programs which must know all networks accessible).
sl@0: 
sl@0: @publishedAll
sl@0: @released
sl@0: */
sl@0: 
sl@0: 
sl@0: /** @struct if_laddrreq
sl@0: 
sl@0: Structure for SIOC[AGD]LIFADDR
sl@0: 
sl@0: @publishedAll
sl@0: @released
sl@0: */
sl@0: 
sl@0: 
sl@0: /** @fn  int setdefaultif( const struct ifreq* ifrequest )
sl@0: @param ifrequest
sl@0: 
sl@0: @return   The  setdefaultif returns 0 on success and -1 on failure.
sl@0: Specifically, if the interface is not found, -1 is returned and errno is set to ENOENT.
sl@0: 
sl@0: The setdefaultif function can be used to set (or remove) a default network interface (either IAP or SNAP) for the application. 
sl@0: This default interface, if set, will be used by all the further socket related function calls (connect, send, write etc)
sl@0: and all the host resolver function calls (getaddrinfo, getnameinfo, gethostbyname, getaddrbyname etc).
sl@0: 
sl@0: If there is a default interface set using setdefaultif and if there is a separate interface set on a socket 
sl@0: using the ioctl system call, network operations on that socket will not use the default one, 
sl@0: but the socket specific interface.
sl@0: 
sl@0: To remove the default interace, pass NULL as the argument.  
sl@0: 
sl@0: To set an IAP name as the default interface, the 'ifr_name' member of the 'ifreq' structure must be filled with 
sl@0: the IAP name to be set. Unicode IAP names can also be set by converting them to UTF8 format before passing them to 
sl@0: this API. See the example below:
sl@0: 
sl@0: @code
sl@0: #include <stdio.h>
sl@0: #include <string.h>
sl@0: #include <net/if.h>
sl@0: 
sl@0: int main()
sl@0: 	{
sl@0: 	struct ifreq ifReq;
sl@0: 	int ret;
sl@0: 	
sl@0: 	/* Set the default interface using IAP name */
sl@0: 	strcpy( ifReq.ifr_name, "Example Interface Name" );
sl@0: 	ret = setdefaultif( &ifReq );
sl@0: 	if( ret == -1 )
sl@0: 		printf( "Setting default interface failed with errno = %d", errno );
sl@0: 	
sl@0: 	/* Perform network operations */
sl@0: 	/* ... */
sl@0: 	
sl@0: 	/* Remove the default interface */
sl@0: 	ret = setdefaultif( NULL );
sl@0: 	if( ret == -1 )
sl@0: 		printf( "Removing default interface failed with errno = %d", errno );
sl@0: 	
sl@0: 	return 0;
sl@0: 	}
sl@0: @endcode 
sl@0: 
sl@0: To set a SNAP id as the default interface, the 'ifr_name' member of the 'ifreq' structure must be an empty string.
sl@0: In this case, the 'snap_id' member of the 'ifr_ifru' union in the parameter should contain the SNAP id to be set.
sl@0: It is recommended to zero initialize the 'ifreq' structure in this case. See the example below. 
sl@0: 
sl@0: @code
sl@0: #include <stdio.h>
sl@0: #include <string.h>
sl@0: #include <net/if.h>
sl@0: 
sl@0: int main()
sl@0: 	{
sl@0: 	struct ifreq ifReq;
sl@0: 	int ret;
sl@0: 	unsigned int snapId = /* Get the SNAP id to be set from the application settings */
sl@0: 	
sl@0: 	/* Set the default interface using SNAP id */
sl@0: 	
sl@0: 	/* memset the ifreq to make sure that the interface name is an empty string */
sl@0: 	memset(&ifReq, 0, sizeof(struct ifreq));
sl@0: 	ifReq.ifr_ifru.snap_id = snapId;
sl@0: 	
sl@0: 	ret = setdefaultif( &ifReq );
sl@0: 	if( ret == -1 )
sl@0: 		printf( "Setting default interface failed with errno = %d", errno );
sl@0: 	
sl@0: 	/* Perform network operations */
sl@0: 	/* ... */
sl@0: 	
sl@0: 	/* Remove the default interface */
sl@0: 	ret = setdefaultif( NULL );
sl@0: 	if( ret == -1 )
sl@0: 		printf( "Removing default interface failed with errno = %d", errno );
sl@0: 	
sl@0: 	return 0;
sl@0: 	}
sl@0: @endcode 
sl@0: 
sl@0: The setdefaultif is not guaranteed to be thread safe.
sl@0: 
sl@0: @publishedAll
sl@0: @released
sl@0: */