GETIFADDRS(3)

GETIFADDRS(3) | Library Functions Manual | GETIFADDRS(3)

# 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 the network interfaces on the local machine in the memory referenced by ifap. The list consists of `ifaddrs` structures, as defined in the include file `<ifaddrs.h>`. The `ifaddrs` structure contains at least the following entries:

        struct ifaddrs   *ifa_next;         /* Pointer to next struct */
        char             *ifa_name;         /* Interface name */
        unsigned int      ifa_flags;        /* Interface flags */
        struct sockaddr  *ifa_addr;         /* Interface address */
        struct sockaddr  *ifa_netmask;      /* Interface netmask */
        struct sockaddr  *ifa_broadaddr;    /* Interface broadcast address */
        struct sockaddr  *ifa_dstaddr;      /* P2P interface destination */
        void             *ifa_data;		/* Address specific data */
        unsigned int      ifa_addrflags;    /* Address flags */

The `ifa_next` field contains a pointer to the next structure on the list. This field is `NULL` in last structure on the list.

The `ifa_name` field contains the interface name.

The `ifa_flags` field contains the interface flags, as set by ifconfig(8) utility.

The `ifa_addr` field references either the address of the interface or the link level address of the interface, if one exists, otherwise it is `NULL`. (The `sa_family` field of the `ifa_addr` field should be consulted to determine the format of the `ifa_addr` address.)

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

The `ifa_broadaddr` field, 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` field references the destination address on a P2P interface, if one exists, otherwise it is `NULL`.

The `ifa_data` field references address family specific data. For `AF_LINK` addresses it contains a pointer to the struct if_data (as defined in include file ⟨net/if.h⟩) which contains various interface attributes and statistics. For all other address families, it is `NULL`.

The `ifa_addrflags` field contains the address flags, which are specific to the address family.

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

# RETURN VALUES

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and errno is set to indicate the error.

# EXAMPLES

The following example program prints a list of all addresses configured on the system.

    #include <sys/types.h>
    #include <sys/socket.h>
    #include <stdio.h>
    #include <ifaddrs.h>
    #include <util.h>
    #include <err.h>
    #include <stdlib.h>

    int
    main(int argc, char *argv[])
    {
    	struct ifaddrs *ifa, *a;

    	if (getifaddrs(&ifa) == -1)
    		err(EXIT_FAILURE, "getifaddrs");

    	for (a = ifa; a; a = a->ifa_next) {
    		char buf[1024];
    		sockaddr_snprintf(buf, sizeof(buf), "%f %a",
    		    a->ifa_addr);
    		printf("%s %x %s\n", a->ifa_name, a->ifa_flags, buf);
    	}
    	freeifaddrs(ifa);
    	return EXIT_SUCCESS;
    }

# ERRORS

The `getifaddrs`() may fail and set errno for any of the errors specified for the library routines ioctl(2), socket(2), malloc(3) or sysctl(3).

# SEE ALSO

ioctl(2), socket(2), sysctl(3), networking(4), ifconfig(8)

# HISTORY

The `getifaddrs` implementation first appeared in BSD/OS.

`ifa_addrflags` was added in NetBSD 8.0.

# BUGS

If both `<net/if.h>` and `<ifaddrs.h>` are being included, `<net/if.h>` must be included before `<ifaddrs.h>`.

September 15, 2016 | NetBSD 10.0