NAME
if_nameindex(), if_nametoindex(), if_indextoname(), if_freenameindex() — functions that map between an interface name and index
SYNOPSIS
#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);
DESCRIPTION
Interfaces are normally known by names such as "lan0",
"vlan200" etc., and index is an unique positive integer
value assigned to an interface. Index values start at 1,
and 0 is not a valid index.
- if_nametoindex()
This function maps an interface name into its corresponding
index. If the specified interface name does not exist, the
return value is set to 0 and errno is set to
ENXIO.
If there is a system error, the return value is 0, and errno is set
to the appropriate value. For example, if the system is running
out of memory, errno will be set to
ENOMEM.
- if_indextoname()
This function maps an interface index into its corresponding
name. 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. This pointer is also the
return value of the function.
IF_NAMESIZE
is defined in
<net/if6.h>
and its value includes a terminating null byte at the end of the
interface name.
If there is no interface corresponding to the specified index,
NULL is returned and errno is set to
ENXIO.
If there is a system
error, the return value is 0, and errno is set to the appropriate
value.
- if_nameindex()
This function returns all interface names and indexes as
an array of
if_nameindex
structures, one structure per interface.
The
if_nameindex
structure is defined in
<net/if6.h>.
struct if_nameindex {
unsigned int if_index; /* 1, 2, ... */
char *if_name; /* null terminated name: "lan0" */
};
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 would set 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 next
if_freenameindex()
function.
- if_freenameindex()
This function frees the dynamic memory allocated by
if_nameindex().
The argument to this function must be a pointer that was returned
by
if_nameindex().
The function prototypes and
struct if_nameindex
are
defined in
<net/if6.h>.
Applications are not required to
include this header file explicitly; it is automatically
included by
<net/if.h>.
Applications using these functions should link with
-lipv6.
ERRORS
When
if_nametoindex()
or
if_indextoname()
fails, the following error message is set in errno.
- ENXIO
The specified interface or index does not exist.
AUTHOR
These functions were
developed by Hewlett-Packard.