/** @file ../include/net/if.h

 @internalComponent

 */

 /** @def IF_NAMESIZE	

 Length of interface external name, including terminating '\\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,

 you can go upto 24 characters for 2-byte and 16 characters for 3-byte representations. 

 All lengths are excluding the terminal NULL character.

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  if_freenameindex(struct if_nameindex *ptr)

 @param ptr

 Refer to if_nametoindex() for the documentation

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  if_nameindex(void)

 Refer to if_nametoindex() for the documentation

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  if_indextoname(unsigned int ifindex, char *ifname)

 @param ifindex

 @param ifname

 Refer to if_nametoindex() for the documentation

 @publishedAll

 @externallyDefinedApi

 */

 /** @fn  if_nametoindex(const char *ifname)

 @param ifname

 Note: This description also covers the following functions -

  if_indextoname()  if_nameindex()  if_freenameindex() 

 @return   Upon successful completion, if_nametoindex returns the index number of the interface.

 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.

   The if_nametoindex function maps the interface name specified in ifname to its corresponding index.

 If the specified interface does not exist, it returns 0.

  The if_indextoname function maps the interface index specified in ifindex to it corresponding name, which is copied into the

 buffer pointed to by ifname, which must be of at least IFNAMSIZ bytes.

 This pointer is also the return value of the function.

 If there is no interface corresponding to the specified

 index, NULL is returned.

 @code

  The if_nameindex function returns an array of if_nameindex structures, one structure per interface, as defined in the include 

   file #include <net/if.h>; 

   The if_nameindex structure contains at least the following entries: 

   unsigned int   if_index;  /* 1, 2, ... */

     char          *if_name;   /* null terminated name: "le0", ... */

 @endcode

  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.

  The if_freenameindex function frees the dynamic memory that was

 allocated by if_nameindex.

 @publishedAll

 @externallyDefinedApi

 */

 /** @struct if_nameindex

 Includes the following members,

 @publishedAll

 @externallyDefinedApi

 */

 /** @var if_nameindex::if_index

 Numeric index of the interface. 

 */

 /** @var if_nameindex::if_name

 Null-terminated name of the interface. 

 */

 /** @struct if_clonereq

 Structure used to query names of interface cloners.

 @publishedAll

 @released

 */

 /** @var if_clonereq::ifcr_total

 total cloners (out)

 */

 /** @var if_clonereq::ifcr_count

 room for this many in user buffer

 */

 /** @var if_clonereq::ifcr_buffer

 buffer for cloner names

 */

 /** @struct if_data

 Structure describing information about an interface which may be of interest to management entities.

 @publishedAll

 @released

 */

 /** @var if_data::ifi_type

 generic interface information. 

 ethernet, tokenring, etc

 */

 /** @var if_data::ifi_physical

 generic interface information

 e.g., AUI, Thinnet, 10base-T, etc

 */

 /** @var if_data::ifi_addrlen

 generic interface information

 media address length 

 */

 /** @var if_data::ifi_hdrlen

 generic interface information

 media header length

 */

 /** @var if_data::ifi_link_state

 generic interface information

 current link state

 */

 /** @var if_data::ifi_recvquota

 generic interface information

 polling quota for receive intrs

 */

 /** @var if_data::ifi_xmitquota

 generic interface information

 polling quota for xmit intrs

 */

 /** @var if_data::ifi_datalen

 generic interface information

 length of this data struct 

 */

 /** @var if_data::ifi_mtu

 generic interface information

 maximum transmission unit

 */

 /** @var if_data::ifi_metric

 generic interface information

 routing metric (external only)

 */

 /** @var if_data::ifi_baudrate

 generic interface information

 linespeed

 */

 /** @var if_data::ifi_ipackets

 volatile statistics.

 packets received on interface 

 */

 /** @var if_data::ifi_ierrors

 volatile statistics.

 input errors on interface

 */

 /** @var if_data::ifi_opackets

 volatile statistics.

 packets sent on interface.

 */

 /** @var if_data::ifi_oerrors

 volatile statistics.

 output errors on interface.

 */

 /** @var if_data::ifi_collisions

 volatile statistics.

 collisions on csma interfaces.

 */

 /** @var if_data::ifi_ibytes

 volatile statistics.

 total number of octets received.

 */

 /** @var if_data::ifi_obytes

 volatile statistics.

 total number of octets sent.

 */

 /** @var if_data::ifi_imcasts

 volatile statistics.

 packets received via multicast.

 */

 /** @var if_data::ifi_omcasts

 volatile statistics.

 packets sent via multicast

 */

 /** @var if_data::ifi_iqdrops

 volatile statistics.

 dropped on input, this interface.

 */

 /** @var if_data::ifi_noproto

 volatile statistics.

 destined for unsupported protocol.

 */

 /** @var if_data::ifi_hwassist

 volatile statistics.

 HW offload capabilities

 */

 /** @var if_data::ifi_epoch

 volatile statistics.

 uptime at attach or stat reset.

 */

 /** @var if_data::ifi_timepad

 volatile statistics.

 time_t is int, not long on alpha.

 */

 /** @var if_data::ifi_lastchange

 volatile statistics.

 time of last administrative change

 */

 /** @struct if_msghdr

 Message format for use in obtaining information about interfaces from getkerninfo and the routing socket

 @publishedAll

 @released

 */

 /** @struct ifa_msghdr

 Message format for use in obtaining information about interface addresses from getkerninfo and the routing socket

 @publishedAll

 @released

 */

 /** @var ifa_msghdr::ifam_msglen

 to skip over non-understood messages

 */

 /** @var ifa_msghdr::ifam_version

 future binary compatibility

 */

 /** @var ifa_msghdr::ifam_type

 message type

 */

 /** @var ifa_msghdr::ifam_addrs

 like rtm_addrs

 */

 /** @var ifa_msghdr::ifam_flags

 value of ifa_flags

 */

 /** @var ifa_msghdr::ifam_index

 index for associated ifp

 */

 /** @var ifa_msghdr::ifam_metric

 index for associated ifp

 */

 /** @struct ifma_msghdr

 Message format for use in obtaining information about multicast addresses from the routing socket

 @publishedAll

 @released

 */

 /** @var ifma_msghdr::ifmam_msglen

 to skip over non-understood messages

 */

 /** @var ifma_msghdr::ifmam_version

 future binary compatibility

 */

 /** @var ifma_msghdr::ifmam_type

 message type

 */

 /** @var ifma_msghdr::ifmam_addrs

 like rtm_addrs

 */

 /** @var ifma_msghdr::ifmam_flags

 value of ifa_flags

 */

 /** @var ifma_msghdr::ifmam_index

 index for associated ifp

 */

 /** @struct if_announcemsghdr

 Message format announcing the arrival or departure of a network interface.

 @publishedAll

 @released

 */

 /** @var if_announcemsghdr::ifan_msglen

 to skip over non-understood messages

 */

 /** @var if_announcemsghdr::ifan_version

 future binary compatibility

 */

 /** @var if_announcemsghdr::ifan_type

 message type

 */

 /** @var if_announcemsghdr::ifan_index

 index for associated ifp

 */

 /** @var if_announcemsghdr::ifan_name

 if name, e.g. "en0"

 */

 /** @var if_announcemsghdr::ifan_what

 what type of announcement

 */

 /** @struct ifreq

 Interface request structure used for socket ioctl's.  

 All interface ioctl's must have parameter definitions which begin with ifr_name.  The remainder may be interface specific.

 @publishedAll

 @released

 */

 /** @struct ifconf

 Structure used in SIOCGIFCONF request.

 Used to retrieve interface configuration for machine (useful for programs which must know all networks accessible).

 @publishedAll

 @released

 */

 /** @struct if_laddrreq

 Structure for SIOC[AGD]LIFADDR

 @publishedAll

 @released

 */

 /** @fn  int setdefaultif( const struct ifreq* ifrequest )

 @param ifrequest

 @return   The  setdefaultif returns 0 on success and -1 on failure.

 Specifically, if the interface is not found, -1 is returned and errno is set to ENOENT.

 The setdefaultif function can be used to set (or remove) a default network interface (either IAP or SNAP) for the application. 

 This default interface, if set, will be used by all the further socket related function calls (connect, send, write etc)

 and all the host resolver function calls (getaddrinfo, getnameinfo, gethostbyname, getaddrbyname etc).

 If there is a default interface set using setdefaultif and if there is a separate interface set on a socket 

 using the ioctl system call, network operations on that socket will not use the default one, 

 but the socket specific interface.

 To remove the default interace, pass NULL as the argument.  

 To set an IAP name as the default interface, the 'ifr_name' member of the 'ifreq' structure must be filled with 

 the IAP name to be set. Unicode IAP names can also be set by converting them to UTF8 format before passing them to 

 this API. See the example below:

 @code

 #include <stdio.h>

 #include <string.h>

 #include <net/if.h>

 int main()

 	{

 	struct ifreq ifReq;

 	int ret;

 	/* Set the default interface using IAP name */

 	strcpy( ifReq.ifr_name, "Example Interface Name" );

 	ret = setdefaultif( &ifReq );

 	if( ret == -1 )

 		printf( "Setting default interface failed with errno = %d", errno );

 	/* Perform network operations */

 	/* ... */

 	/* Remove the default interface */

 	ret = setdefaultif( NULL );

 	if( ret == -1 )

 		printf( "Removing default interface failed with errno = %d", errno );

 	return 0;

 	}

 @endcode 

 To set a SNAP id as the default interface, the 'ifr_name' member of the 'ifreq' structure must be an empty string.

 In this case, the 'snap_id' member of the 'ifr_ifru' union in the parameter should contain the SNAP id to be set.

 It is recommended to zero initialize the 'ifreq' structure in this case. See the example below. 

 @code

 #include <stdio.h>

 #include <string.h>

 #include <net/if.h>

 int main()

 	{

 	struct ifreq ifReq;

 	int ret;

 	unsigned int snapId = /* Get the SNAP id to be set from the application settings */

 	/* Set the default interface using SNAP id */

 	/* memset the ifreq to make sure that the interface name is an empty string */

 	memset(&ifReq, 0, sizeof(struct ifreq));

 	ifReq.ifr_ifru.snap_id = snapId;

 	ret = setdefaultif( &ifReq );

 	if( ret == -1 )

 		printf( "Setting default interface failed with errno = %d", errno );

 	/* Perform network operations */

 	/* ... */

 	/* Remove the default interface */

 	ret = setdefaultif( NULL );

 	if( ret == -1 )

 		printf( "Removing default interface failed with errno = %d", errno );

 	return 0;

 	}

 @endcode 

 The setdefaultif is not guaranteed to be thread safe.

 @publishedAll

 @released

 */