/** @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

*/