Start documenting libc.
Bug: N/A
Test: N/A
Change-Id: I17345cb72a5ffc3af1688cf5874589cfb1e1fea0
diff --git a/libc/include/ifaddrs.h b/libc/include/ifaddrs.h
index 0e2b0ea..9eaabbd 100644
--- a/libc/include/ifaddrs.h
+++ b/libc/include/ifaddrs.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _IFADDRS_H_
-#define _IFADDRS_H_
+#pragma once
+
+/**
+ * @file ifaddrs.h
+ * @brief Access to network interface addresses.
+ */
#include <sys/cdefs.h>
#include <netinet/in.h>
@@ -35,25 +39,55 @@
__BEGIN_DECLS
+/**
+ * Returned by getifaddrs() and freed by freeifaddrs().
+ */
struct ifaddrs {
+ /** Pointer to the next element in the linked list. */
struct ifaddrs* ifa_next;
+
+ /** Interface name. */
char* ifa_name;
+ /** Interface flags (like `SIOCGIFFLAGS`). */
unsigned int ifa_flags;
+ /** Interface address. */
struct sockaddr* ifa_addr;
+ /** Interface netmask. */
struct sockaddr* ifa_netmask;
+
union {
+ /** Interface broadcast address (if IFF_BROADCAST is set). */
struct sockaddr* ifu_broadaddr;
+ /** Interface destination address (if IFF_POINTOPOINT is set). */
struct sockaddr* ifu_dstaddr;
} ifa_ifu;
+
+ /** Unused. */
void* ifa_data;
};
+/** Synonym for `ifa_ifu.ifu_broadaddr` in `struct ifaddrs`. */
#define ifa_broadaddr ifa_ifu.ifu_broadaddr
+/** Synonym for `ifa_ifu.ifu_dstaddr` in `struct ifaddrs`. */
#define ifa_dstaddr ifa_ifu.ifu_dstaddr
-void freeifaddrs(struct ifaddrs* __ptr) __INTRODUCED_IN(24);
+/**
+ * [getifaddrs(3)](http://man7.org/linux/man-pages/man3/getifaddrs.3.html) creates a linked list
+ * of `struct ifaddrs`. The list must be freed by freeifaddrs().
+ *
+ * Returns 0 and stores the list in `*__list_ptr` on success,
+ * and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 24.
+ */
int getifaddrs(struct ifaddrs** __list_ptr) __INTRODUCED_IN(24);
-__END_DECLS
+/**
+ * [freeifaddrs(3)](http://man7.org/linux/man-pages/man3/freeifaddrs.3.html) frees a linked list
+ * of `struct ifaddrs` returned by getifaddrs().
+ *
+ * Available since API level 24.
+ */
+void freeifaddrs(struct ifaddrs* __ptr) __INTRODUCED_IN(24);
-#endif
+__END_DECLS