Go to main content

man pages section 3: Basic Library Functions

Exit Print View

Updated: Thursday, June 13, 2019
 
 

getifaddrs(3C)

Name

getifaddrs, freeifaddrs - get interface addresses

Synopsis

 
#include <sys/types.h>
#include <sys/socket.h>
#include <ifaddrs.h>

int getifaddrs(struct ifaddrs **ifap);
void freeifaddrs(struct ifaddrs *ifp);

Description

The getifaddrs() function stores a reference to a linked list of network interface addresses on the local machine in the memory referenced by ifap. The list consists of ifaddrs structures, as defined in the include file ifaddrs.h. Each element of the list describes one network interface address. The caller can process each ifaddrs structure in this list by following the ifa_next pointer, until a null pointer is encountered.

struct ifaddrs {
 struct ifaddrs          *ifa_next;    /* next structure in linked list*/
 char                    *ifa_name;    /* Interface name */
 uint64_t                ifa_flags;    /* Interface flags (if_tcp(4P)) */
 struct sockaddr         *ifa_addr;    /* Interface address */
 struct sockaddr         *ifa_netmask; /* Interface netmask */
 union {
        /* Interface broadcast address */
        struct sockaddr        *ifa_dstaddr;
        /* P2P interface destination */
        struct sockaddr        *ifa_broadaddr;
  } ifa_ifu;
 void                     *ifa_data; /* Address specific data (unused) */
};
#ifndef ifa_broadaddr
#define ifa_broadaddr   ifa_ifu.ifu_broadaddr
#endif
#ifndef ifa_dstaddr
#define ifa_dstaddr     ifa_ifu.ifu_dstaddr
#endif

The ifa_name member contains the interface name.

The ifa_flags member contains the interface flags.

The ifa_addr member references the address of the interface. (The sa_family member of the ifa_addr member should be consulted to determine the format of the ifa_addr address.)

The ifa_netmask member references the netmask associated with ifa_addr, if one is set, otherwise it is NULL.

The ifa_broadaddr member, which should only be referenced for non-P2P interfaces, references the broadcast address associated with ifa_addr, if one exists, otherwise it is NULL.

The ifa_dstaddr member references the destination address on a P2P inter face, if one exists, otherwise it is NULL.

The ifa_data member is currently unused.

The data returned by getifaddrs() is dynamically allocated and should be freed using freeifaddrs() when no longer needed.

Return Values

The getifaddrs() function returns the value 0 if successful; otherwise -1 is returned and errno is set to indicate the error.

Errors

The getifaddrs() function may fail and set errno for any of the errors specified for ioctl(2), socket(3C), and malloc(3C).

Attributes

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

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
MT-Safe

See Also

ioctl(2), malloc(3C), socket(3C), if_tcp(4P), attributes(7), ifconfig(8), ipadm(8)