HP-UX Reference (11i v2 04/09) - 3 Library Functions A-M (vol 6)

i
if_nameindex(3N) if_nameindex(3N)
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 appropri-
ate 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.
HP-UX 11i Version 2: September 2004 − 1 − Hewlett-Packard Company Section 3−−529