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(7) for descriptions of the following attributes:


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

SEE ALSO

if_nametoindex(3SOCKET), if(4P), attributes(7), standards(7),
ifconfig(8)

December 14, 2003 IF_NAMETOINDEX(3XNET)