if_nameindex()--Return All Interface Names and Indexes
Syntax
#include <net/if.h> struct if_nameindex *if_nameindex(void);Service Program Name: QSOSRV2
Default Public Authority: *USE
Threadsafe: Yes
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
- 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.
- 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.
- 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; } ... }
API introduced: V5R4