IF_NAMETOINDEX(3XNET) X/Open Networking Services Library Functions


NAME


if_nametoindex, if_indextoname, if_nameindex, if_freenameindex -
functions to map Internet Protocol network interface names and interface
indexes

SYNOPSIS


cc [ flag... ] file... -lxnet [ library... ]
#include <net/if.h>

unsigned int if_nametoindex(const char *ifname);


char *if_indextoname(unsigned int ifindex, char *ifname);


struct if_nameindex *if_nameindex(void)


void if_freenameindex(struct if_nameindex *ptr);


PARAMETERS


These functions support the following parameters:

ifname
interface name


ifindex
interface index


ptr
pointer returned by if_nameindex()


DESCRIPTION


This API defines two functions that map between an Internet Protocol
network interface name and index, a third function that returns all the
interface names and indexes, and a fourth function to return the dynamic
memory allocated by the previous function.


Network interfaces are normally known by names such as eri0, sl1, ppp2,
and the like. The ifname argument must point to a buffer of at least
IF_NAMESIZE bytes into which the interface name corresponding to the
specified index is returned. IF_NAMESIZE is defined in <net/if.h> and its
value includes a terminating null byte at the end of the interface name.

if_nametoindex()
The if_nametoindex() function returns the interface
index corresponding to the interface name pointed
to by the ifname pointer. If the specified
interface name does not exist, the return value is
0, and errno is set to ENXIO. If there was a system
error, such as running out of memory, the return
value is 0 and errno is set to the proper value,
for example, ENOMEM.


if_indextoname()
The if_indextoname() function maps an interface
index into its corresponding name. This pointer is
also the return value of the function. If there is
no interface corresponding to the specified index,
NULL is returned, and errno is set to ENXIO, if
there was a system error, such as running out of
memory, if_indextoname() returns NULL and errno
would be set to the proper value, for example,
ENOMEM.


*if_nameindex()
The if_nameindex() function returns an array of
if_nameindex structures, one structure per
interface. The if_nameindex structure holds the
information about a single interface and is defined
when the <net/if.h> header is included:

struct if_nameindex {
unsigned int if_index; /* 1, 2, ... */
char *if_name; /* null terminated name: "eri0", ... */
};

The end of the array of structures is indicated by
a structure with an if_index of 0 and an if_name of
NULL. The function returns a null pointer upon an
error and sets errno to the appropriate value. The
memory used for this array of structures along with
the interface names pointed to by the if_name
members is obtained dynamically. This memory is
freed by the if_freenameindex() function.


if_freenameindex()
The if_freenameindex() function frees the dynamic
memory that was allocated by if_nameindex(). The
argument to this function must be a pointer that
was returned by if_nameindex().


ATTRIBUTES


See attributes(5) for descriptions of the following attributes:


+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Standard |
+--------------------+-----------------+
|MT-Level | MT-Safe |
+--------------------+-----------------+

SEE ALSO


ifconfig(1M), if_nametoindex(3SOCKET), attributes(5), standards(5),
if(7P)


December 14, 2003 IF_NAMETOINDEX(3XNET)