if_nameindex()--Return All Interface Names and Indexes

  #include  <net/if.h>

  struct if_nameindex *if_nameindex(void);

The if_nameindex() function returns an array of if_nameindex structures, one structure per interface. The end of the array of structures is indicated by a structure with an if_index of 0 and an if_name of NULL.

Parameters

None.

Authorities

No authorization is required.

Return Value

if_nameindex() returns a pointer to an array of if_nameindex structures. Possible values are:

• Pointer to dynamically allocated memory for the array of if_nameindex structures. (successful). Note: the if_freenameindex() API should be used to free the array once it is no longer needed.
• NULL (unsuccessful)

The structure struct if_nameindex is defined in <net/if.h>.

      struct if_nameindex {
      unsigned int   if_index;  /* 1, 2, ... */
      char          *if_name;   /* null terminated line name */
      };

Error Conditions

When if_nameindex() fails, errno can be set to one of the following:

[ENXIO]

No interfaces names and indexes exist.

[ENOMEM]

No memory available for the if_nameindex array.

Usage Notes

1. The interface (line description) names stored at if_name will be returned in the default coded character set identifier (CCSID) currently in effect for the job.
2. It is important to note that the term "Interface" refers to the name on a line description (i.e. a physical interface) for this API. Other parts of the operating system, when refering to "Interface," mean an IP address.
3. The array returned will contain all configured interfaces (line descriptions). The array may also contain a *LOOPBACK entry.

Related Information

• getsockopt()--Retrieve Information about Socket Options
• if_freenameindex()--Free Memory Allocated by if_nameindex()
• if_indextoname()--Map an Interface Index to its Corresponding Name
• if_nametoindex()--Map an Interface Name to its Corresponding Index
• setsockopt()--Set Socket Options

Example

The following example shows how if_nameindex() is used.

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

#include <net/if.h>
#include <sys/types.h>
#include <errno.h>

void main()
{

  struct if_nameindex *interfaceArray = NULL;
  interfaceArray = if_nameindex(void);    /* retrieve the current interfaces */
  if (interfaceArray != NULL)
  {
    ...

    if_freenameindex(interfaceArray);     /* free the dynamic memory */
    interfaceArray = NULL;                /* prevent use after free  */
  }
  else
  {
     printf("if_nameindex() failed with errno =  %d %s \n",
            errno,strerror(errno));
     return;
  }

  ...

}

[ Back to top | UNIX-Type APIs | APIs by category ]