if_nameindex.3n (2010 09)

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 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 run-
ning 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.
HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1