include, misc: Add net interface API.

Adds `uv_network_interface_t` structure and a new API for retrieving
network interfaces, `uv_network_interfaces`.  This new API intends to
eventually replace `uv_interface_addresses`, adding new capabilities,
such as:

 * Not filtering out interfaces without addresses;
 * Marking missing addresses as `AF_UNSPEC`;
 * Including all common cross-platform flags;
 * Including link-layer addresses for interfaces;
 * Supporting 8-byte Firewire link-layer addresses;
 * Including broadcast/point-to-point addresses

The interface is added and documented, and returns `-ENOTSUP` on all
platforms. Once the individual platform support is merged, the test
driver will no longer accept the `-ENOTSUP` return and the existing
`uv_interface_addresses` function will be changed to be implemented
on top of this new API.

docs/src/misc.rst

@@ -125,6 +125,36 @@ Data types
             } netmask;
         } uv_interface_address_t;
 
+.. c:type:: uv_network_interface_t
+
+    Data type for network interfaces.
+
+    ::
+
+        typedef struct uv_network_interface_s {
+            char* name;
+            int is_up_and_running;
+            int is_loopback;
+            int is_point_to_point;
+            int is_promiscuous;
+            int has_broadcast;
+            int has_multicast;
+            char phys_addr[8]; /* Enough to store a firewire address. */
+            unsigned int phys_addr_len;
+            union {
+                struct sockaddr_in address4;
+                struct sockaddr_in6 address6;
+            } address;
+            union {
+                struct sockaddr_in broadcast4;
+                struct sockaddr_in6 broadcast6;
+            } broadcast;
+            union {
+                struct sockaddr_in netmask4;
+                struct sockaddr_in6 netmask6;
+            } netmask;
+        } uv_network_interface_t;
+
 .. c:type:: uv_passwd_t
 
     Data type for password file information.
@@ -226,14 +256,33 @@ API
 .. c:function:: int uv_interface_addresses(uv_interface_address_t** addresses, int* count)
 
     Gets address information about the network interfaces on the system. An
-    array of `count` elements is allocated and returned in `addresses`. It must
-    be freed by the user, calling :c:func:`uv_free_interface_addresses`.
+    array of `count` elements is allocated and returned in `addresses`. Only
+    includes interfaces with `INET` or `INET6` addresses. It must be freed by
+    the user, calling :c:func:`uv_free_interface_addresses`.
 
 .. c:function:: void uv_free_interface_addresses(uv_interface_address_t* addresses, int count)
 
     Free an array of :c:type:`uv_interface_address_t` which was returned by
     :c:func:`uv_interface_addresses`.
 
+.. c:function:: int uv_network_interfaces(uv_network_interface_t** interfaces, int* count)
+
+    Gets information about internet network interfaces on the system. An array
+    of `count` elements is allocated and returned in `interfaces`. Includes up,
+    down, unattached interfaces and interfaces without addresses. Missing
+    addresses are marked with a family of `AF_UNSPEC` and their contents are
+    unspecified. At least one link-layer record is returned for each interface.
+    It must be freed by the user, calling :c:func:`uv_free_network_interfaces`.
+
+	.. note::
+	    This interface will return `-ENOTSUP` until individual platform support
+        has been implemented for each supported platform.
+
+.. c:function:: void uv_free_network_interfaces(uv_network_interface_t* interfaces, int count)
+
+    Free an array of :c:type:`uv_network_interface_t` which was returned by
+    :c:func:`uv_network_interfaces`.
+
 .. c:function:: void uv_loadavg(double avg[3])
 
     Gets the load average. See: `<http://en.wikipedia.org/wiki/Load_(computing)>`_

include/uv.h

@@ -229,6 +229,7 @@ typedef struct uv_work_s uv_work_t;
 /* None of the above. */
 typedef struct uv_cpu_info_s uv_cpu_info_t;
 typedef struct uv_interface_address_s uv_interface_address_t;
+typedef struct uv_network_interface_s uv_network_interface_t;
 typedef struct uv_dirent_s uv_dirent_t;
 typedef struct uv_passwd_s uv_passwd_t;
 
@@ -1005,6 +1006,30 @@ struct uv_interface_address_s {
   } netmask;
 };
 
+typedef struct uv_network_interface_s {
+  char* name;
+  int is_up_and_running;
+  int is_loopback;
+  int is_point_to_point;
+  int is_promiscuous;
+  int has_broadcast;
+  int has_multicast;
+  char phys_addr[8]; /* Enough to store a firewire address. */
+  unsigned int phys_addr_len;
+  union {
+    struct sockaddr_in address4;
+    struct sockaddr_in6 address6;
+  } address;
+  union {
+    struct sockaddr_in broadcast4;
+    struct sockaddr_in6 broadcast6;
+  } broadcast;
+  union {
+    struct sockaddr_in netmask4;
+    struct sockaddr_in6 netmask6;
+  } netmask;
+} uv_network_interface_s;
+
 struct uv_passwd_s {
   char* username;
   long uid;
@@ -1081,6 +1106,10 @@ UV_EXTERN int uv_os_unsetenv(const char* name);
 
 UV_EXTERN int uv_os_gethostname(char* buffer, size_t* size);
 
+UV_EXTERN int uv_network_interfaces(uv_network_interface_t** interfaces,
+                                    int* count);
+UV_EXTERN void uv_free_network_interfaces(uv_network_interface_t* interfaces,
+                                          int count);
 
 typedef enum {
   UV_FS_UNKNOWN = -1,

src/unix/aix.c

@@ -1217,6 +1217,23 @@ void uv_free_interface_addresses(uv_interface_address_t* addresses,
   uv__free(addresses);
 }
 
+
+int uv_network_interfaces(uv_network_interface_t** interfaces, int* count) {
+  return -ENOTSUP;
+}
+
+
+void uv_free_network_interfaces(uv_network_interface_t* interfaces, int count) {
+  int i;
+
+  for (i = 0; i < count; i++) {
+    uv__free(interfaces[i].name);
+  }
+
+  uv__free(interfaces);
+}
+
+
 void uv__platform_invalidate_fd(uv_loop_t* loop, int fd) {
   struct pollfd* events;
   uintptr_t i;

src/unix/darwin.c

@@ -229,3 +229,19 @@ void uv_free_cpu_info(uv_cpu_info_t* cpu_infos, int count) {
 
   uv__free(cpu_infos);
 }
+
+
+int uv_network_interfaces(uv_network_interface_t** interfaces, int* count) {
+  return -ENOTSUP;
+}
+
+
+void uv_free_network_interfaces(uv_network_interface_t* interfaces, int count) {
+  int i;
+
+  for (i = 0; i < count; i++) {
+    uv__free(interfaces[i].name);
+  }
+
+  uv__free(interfaces);
+}

src/unix/freebsd.c

@@ -344,3 +344,19 @@ void uv_free_cpu_info(uv_cpu_info_t* cpu_infos, int count) {
 
   uv__free(cpu_infos);
 }
+
+
+int uv_network_interfaces(uv_network_interface_t** interfaces, int* count) {
+  return -ENOTSUP;
+}
+
+
+void uv_free_network_interfaces(uv_network_interface_t* interfaces, int count) {
+  int i;
+
+  for (i = 0; i < count; i++) {
+    uv__free(interfaces[i].name);
+  }
+
+  uv__free(interfaces);
+}

src/unix/linux-core.c

@@ -944,6 +944,22 @@ void uv_free_interface_addresses(uv_interface_address_t* addresses,
 }
 
 
+int uv_network_interfaces(uv_network_interface_t** interfaces, int* count) {
+  return -ENOTSUP;
+}
+
+
+void uv_free_network_interfaces(uv_network_interface_t* interfaces, int count) {
+  int i;
+
+  for (i = 0; i < count; i++) {
+    uv__free(interfaces[i].name);
+  }
+
+  uv__free(interfaces);
+}
+
+
 void uv__set_process_title(const char* title) {
 #if defined(PR_SET_NAME)
   prctl(PR_SET_NAME, title);  /* Only copies first 16 characters. */

src/unix/netbsd.c

@@ -270,3 +270,19 @@ void uv_free_cpu_info(uv_cpu_info_t* cpu_infos, int count) {
 
   uv__free(cpu_infos);
 }
+
+
+int uv_network_interfaces(uv_network_interface_t** interfaces, int* count) {
+  return -ENOTSUP;
+}
+
+
+void uv_free_network_interfaces(uv_network_interface_t* interfaces, int count) {
+  int i;
+
+  for (i = 0; i < count; i++) {
+    uv__free(interfaces[i].name);
+  }
+
+  uv__free(interfaces);
+}

src/unix/openbsd.c

@@ -282,3 +282,19 @@ void uv_free_cpu_info(uv_cpu_info_t* cpu_infos, int count) {
 
   uv__free(cpu_infos);
 }
+
+
+int uv_network_interfaces(uv_network_interface_t** interfaces, int* count) {
+  return -ENOTSUP;
+}
+
+
+void uv_free_network_interfaces(uv_network_interface_t* interfaces, int count) {
+  int i;
+
+  for (i = 0; i < count; i++) {
+    uv__free(interfaces[i].name);
+  }
+
+  uv__free(interfaces);
+}

src/unix/sunos.c

@@ -809,6 +809,7 @@ int uv_interface_addresses(uv_interface_address_t** addresses, int* count) {
 }
 #endif  /* SUNOS_NO_IFADDRS */
 
+
 void uv_free_interface_addresses(uv_interface_address_t* addresses,
   int count) {
   int i;
@@ -819,3 +820,19 @@ void uv_free_interface_addresses(uv_interface_address_t* addresses,
 
   uv__free(addresses);
 }
+
+
+int uv_network_interfaces(uv_network_interface_t** interfaces, int* count) {
+  return -ENOTSUP;
+}
+
+
+void uv_free_network_interfaces(uv_network_interface_t* interfaces, int count) {
+  int i;
+
+  for (i = 0; i < count; i++) {
+    uv__free(interfaces[i].name);
+  }
+
+  uv__free(interfaces);
+}

src/win/util.c

@@ -1085,6 +1085,22 @@ void uv_free_interface_addresses(uv_interface_address_t* addresses,
 }
 
 
+int uv_network_interfaces(uv_network_interface_t** interfaces, int* count) {
+  return -ENOTSUP;
+}
+
+
+void uv_free_network_interfaces(uv_network_interface_t* interfaces, int count) {
+  int i;
+
+  for (i = 0; i < count; i++) {
+    uv__free(interfaces[i].name);
+  }
+
+  uv__free(interfaces);
+}
+
+
 int uv_getrusage(uv_rusage_t *uv_rusage) {
   FILETIME createTime, exitTime, kernelTime, userTime;
   SYSTEMTIME kernelSystemTime, userSystemTime;