Go to main content

man pages section 3: Basic Library Functions

Exit Print View

Updated: Wednesday, July 27, 2022

if_nametoindex (3C)


if_nametoindex, if_indextoname, if_nameindex, if_freenameindex - routines to map Internet Protocol network interface names and interface indexes


#include <net/if.h>

unsigned int if_nametoindex(const char *ifname);
char *if_indextoname(unsigned int ifindex, char *
struct if_nameindex *if_nameindex(void);
void if_freenameindex(struct if_nameindex *ptr);



interface name


interface index


pointer returned by if_nameindex()


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 net0, net1, 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.


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.


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 is set to the proper value, for example, ENOMEM.


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;  /* "net0", ... */

While any IPMP IP interfaces are returned by if_nameindex (), the underlying IP interfaces that comprise each IPMP group are not returned.

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.


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().


See attributes(7) for descriptions of the following attributes:

Interface Stability

See Also

if(4P), attributes(7), dladm(8), ifconfig(8), ipadm(8)

Gilligan, R. RFC 3493, Basic Socket Interface Extensions for IPv6. Network Working Group. February 2003. https://tools.ietf.org/html/rfc3493


These functions were added to Oracle Solaris in the Solaris 8 release.