NAME
if_nameindex(), if_nametoindex(), if_indextoname(), if_freenameindex() — functions that map between an interface name and index value
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" and
"vlan200."
The index is a 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/if.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/if.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().
CHANGE HISTORY
The function prototypes and
struct if_nameindex
were defined in
<net/if6.h>
prior to HP-UX 11i v3.
They are now defined in
<net/if.h>.
Beginning with HP-UX 11i v3, these functions may pass on both IPv4 and IPv6 interfaces,
and they no longer reside in the IPv6 library.
They currently reside in the C library.
Therefore, applications using these functions no longer need to link with
-lipv6.
Applications using other IPv6 interfaces that reside in IPv6 library will
need to continue to link with
-lipv6.
AUTHOR
if_nametoindex(),
if_indextoname(),
if_nameindex(),
and
if_freenameindex()
were developed by HP, IETF, and X/Open Company Limited.
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.
STANDARDS CONFORMANCE
socket(): UNIX 03
Printable version
