Another round of documentation.
Bug: N/A
Test: N/A
Change-Id: I1b818fbb36ddd6d084dee56828290c2717a0c9b0
diff --git a/libc/include/bits/auxvec.h b/libc/include/bits/auxvec.h
index de3cfbb..4d39477 100644
--- a/libc/include/bits/auxvec.h
+++ b/libc/include/bits/auxvec.h
@@ -26,18 +26,24 @@
* SUCH DAMAGE.
*/
-#ifndef _BITS_AUXVEC_H_
-#define _BITS_AUXVEC_H_
+#pragma once
+
+/**
+ * @file bits/auxvec.h
+ * @brief Constants for use with getauxval().
+ */
#include <sys/cdefs.h>
#include <linux/auxvec.h>
-/* Historical arch-specific cruft. */
-#define AT_FPUCW 18 /* SuperH */
-#define AT_DCACHEBSIZE 19 /* PowerPC */
-#define AT_ICACHEBSIZE 20 /* PowerPC */
-#define AT_UCACHEBSIZE 21 /* PowerPC */
-#define AT_IGNOREPPC 22 /* PowerPC */
-
-#endif
+/** Historical SuperH cruft. Irrelevant on Android. */
+#define AT_FPUCW 18
+/** Historical PowerPC cruft. Irrelevant on Android. */
+#define AT_DCACHEBSIZE 19
+/** Historical PowerPC cruft. Irrelevant on Android. */
+#define AT_ICACHEBSIZE 20
+/** Historical PowerPC cruft. Irrelevant on Android. */
+#define AT_UCACHEBSIZE 21
+/** Historical PowerPC cruft. Irrelevant on Android. */
+#define AT_IGNOREPPC 22
diff --git a/libc/include/bits/epoll_event.h b/libc/include/bits/epoll_event.h
index 054323c..b2b4c87 100644
--- a/libc/include/bits/epoll_event.h
+++ b/libc/include/bits/epoll_event.h
@@ -26,12 +26,17 @@
* SUCH DAMAGE.
*/
-#ifndef _BITS_EPOLL_EVENT_H_
-#define _BITS_EPOLL_EVENT_H_
+#pragma once
+
+/**
+ * @file bits/epoll_event.h
+ * @brief Types for epoll().
+ */
#include <sys/cdefs.h>
#include <stdint.h>
+/** The union of possible data types for an `epoll_event`. */
typedef union epoll_data {
void* ptr;
int fd;
@@ -39,6 +44,7 @@
uint64_t u64;
} epoll_data_t;
+/** The type representing an epoll() event. */
struct epoll_event {
uint32_t events;
epoll_data_t data;
@@ -47,5 +53,3 @@
__packed
#endif
;
-
-#endif
diff --git a/libc/include/bits/fcntl.h b/libc/include/bits/fcntl.h
index e3b0e8c..597aa6e 100644
--- a/libc/include/bits/fcntl.h
+++ b/libc/include/bits/fcntl.h
@@ -26,15 +26,23 @@
* SUCH DAMAGE.
*/
-#ifndef _BITS_FCNTL_H_
-#define _BITS_FCNTL_H_
+#pragma once
+
+/**
+ * @file bits/fcntl.h
+ * @brief The fcntl() function.
+ */
#include <sys/cdefs.h>
__BEGIN_DECLS
+/**
+ * [fcntl(3)](http://man7.org/linux/man-pages/man2/fcntl.2.html) performs various operations
+ * on file descriptors.
+ *
+ * The return value depends on the operation.
+ */
int fcntl(int __fd, int __cmd, ...);
__END_DECLS
-
-#endif
diff --git a/libc/include/bits/getopt.h b/libc/include/bits/getopt.h
index 5481449..0411716 100644
--- a/libc/include/bits/getopt.h
+++ b/libc/include/bits/getopt.h
@@ -26,18 +26,42 @@
* SUCH DAMAGE.
*/
-#ifndef _BITS_GETOPT_H_
-#define _BITS_GETOPT_H_
+#pragma once
#include <sys/cdefs.h>
__BEGIN_DECLS
+/**
+ * [getopt(3)](http://man7.org/linux/man-pages/man3/getopt.3.html) parses command-line options.
+ *
+ * Returns the next option character on success, returns -1 if all options have been parsed, and
+ * returns `'?'` on error.
+ */
int getopt(int __argc, char* const __argv[], const char* __options);
+/**
+ * Points to the text of the corresponding value for options that take an argument.
+ */
extern char* optarg;
-extern int optind, opterr, optopt;
+
+/**
+ * The index of the next element to be processed.
+ * On Android, callers should set `optreset = 1` rather than trying to reset `optind` to
+ * scan a new argument vector.
+ */
+extern int optind;
+
+/**
+ * Determines whether getopt() outputs error messages.
+ * Callers should set this to `0` to disable error messages.
+ * Defaults to non-zero.
+ */
+extern int opterr;
+
+/**
+ * The last unrecognized option character, valid when getopt() returns `'?'`.
+ */
+extern int optopt;
__END_DECLS
-
-#endif
diff --git a/libc/include/bits/in_addr.h b/libc/include/bits/in_addr.h
index 834c056..30eb04b 100644
--- a/libc/include/bits/in_addr.h
+++ b/libc/include/bits/in_addr.h
@@ -26,16 +26,20 @@
* SUCH DAMAGE.
*/
-#ifndef _BITS_IN_ADDR_H_
-#define _BITS_IN_ADDR_H_
+#pragma once
+
+/**
+ * @file bits/in_addr.h
+ * @brief IPv4 address types.
+ */
#include <sys/cdefs.h>
#include <stdint.h>
+/** An integral type representing an IPv4 address. */
typedef uint32_t in_addr_t;
+/** A structure representing an IPv4 address. */
struct in_addr {
in_addr_t s_addr;
};
-
-#endif
diff --git a/libc/include/bits/ioctl.h b/libc/include/bits/ioctl.h
index 745bbf0..9ed1292 100644
--- a/libc/include/bits/ioctl.h
+++ b/libc/include/bits/ioctl.h
@@ -26,13 +26,20 @@
* SUCH DAMAGE.
*/
-#ifndef _BITS_IOCTL_H_
-#define _BITS_IOCTL_H_
+#pragma once
+
+/**
+ * @file bits/ioctl.h
+ * @brief The ioctl() function.
+ */
#include <sys/cdefs.h>
__BEGIN_DECLS
+/**
+ * [ioctl(2)](http://man7.org/linux/man-pages/man2/ioctl.2.html) operates on device files.
+ */
int ioctl(int __fd, int __request, ...);
/*
@@ -57,5 +64,3 @@
#endif
__END_DECLS
-
-#endif
diff --git a/libc/include/bits/ip_mreq_source.h b/libc/include/bits/ip_mreq_source.h
index 0eb8d68..83490a4 100644
--- a/libc/include/bits/ip_mreq_source.h
+++ b/libc/include/bits/ip_mreq_source.h
@@ -26,16 +26,21 @@
* SUCH DAMAGE.
*/
-#ifndef _BITS_IP_MREQ_SOURCE_H_
-#define _BITS_IP_MREQ_SOURCE_H_
+#pragma once
+
+/**
+ * @file bits/ip_mreq_source.h
+ * @brief The `ip_mreq_source` type.
+ */
#include <sys/cdefs.h>
#include <bits/in_addr.h>
+/**
+ * The type representing an IPv4 multicast source.
+ */
struct ip_mreq_source {
struct in_addr imr_multiaddr;
struct in_addr imr_interface;
struct in_addr imr_sourceaddr;
};
-
-#endif
diff --git a/libc/include/bits/ip_msfilter.h b/libc/include/bits/ip_msfilter.h
index 23c127d..cb3350b 100644
--- a/libc/include/bits/ip_msfilter.h
+++ b/libc/include/bits/ip_msfilter.h
@@ -26,12 +26,17 @@
* SUCH DAMAGE.
*/
-#ifndef _BITS_IP_MSFILTER_H_
-#define _BITS_IP_MSFILTER_H_
+#pragma once
+
+/**
+ * @file bits/ip_msfilter.h
+ * @brief IPv4 multicast filtering.
+ */
#include <sys/cdefs.h>
#include <bits/in_addr.h>
+/** The type representing an IPv4 multicast filter. */
struct ip_msfilter {
struct in_addr imsf_multiaddr;
struct in_addr imsf_interface;
@@ -39,5 +44,3 @@
uint32_t imsf_numsrc;
struct in_addr imsf_slist[1];
};
-
-#endif
diff --git a/libc/include/bits/lockf.h b/libc/include/bits/lockf.h
index 929c68c..58ab031 100644
--- a/libc/include/bits/lockf.h
+++ b/libc/include/bits/lockf.h
@@ -26,22 +26,42 @@
* SUCH DAMAGE.
*/
-#ifndef _BITS_LOCKF_H_
-#define _BITS_LOCKF_H_
+#pragma once
+
+/**
+ * @file bits/lockf.h
+ * @brief The lockf() function.
+ */
#include <sys/cdefs.h>
#include <sys/types.h>
+/** lockf() command to unlock a section of a file. */
#define F_ULOCK 0
+/** lockf() command to block until it locks a section of a file. */
#define F_LOCK 1
+/** lockf() command to try to lock a section of a file. */
#define F_TLOCK 2
+/** lockf() command to test whether a section of a file is unlocked (or locked by the caller). */
#define F_TEST 3
__BEGIN_DECLS
+/**
+ * [lockf(3)](http://man7.org/linux/man-pages/man3/lockf.3.html) manipulates POSIX file locks.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 24.
+ *
+ * See also flock().
+ */
int lockf(int __fd, int __cmd, off_t __length) __RENAME_IF_FILE_OFFSET64(lockf64) __INTRODUCED_IN(24);
+
+/**
+ * Like lockf() but allows using a 64-bit length
+ * even from a 32-bit process without `__FILE_OFFSET_BITS=64`.
+ */
int lockf64(int __fd, int __cmd, off64_t __length) __INTRODUCED_IN(24);
__END_DECLS
-
-#endif
diff --git a/libc/include/bits/mbstate_t.h b/libc/include/bits/mbstate_t.h
index 057a2c9..0f9323d 100644
--- a/libc/include/bits/mbstate_t.h
+++ b/libc/include/bits/mbstate_t.h
@@ -26,16 +26,22 @@
* SUCH DAMAGE.
*/
-#ifndef _BITS_MBSTATE_T_H_
-#define _BITS_MBSTATE_T_H_
+#pragma once
+
+/**
+ * @file bits/mbstate_t.h
+ * @brief The `mbstate_t` type.
+ */
#include <sys/cdefs.h>
+/**
+ * An opaque type used by the multibyte conversion functions.
+ * Do not make assumptions about the content of this type.
+ */
typedef struct {
unsigned char __seq[4];
#ifdef __LP64__
unsigned char __reserved[4];
#endif
} mbstate_t;
-
-#endif
diff --git a/libc/include/bits/sa_family_t.h b/libc/include/bits/sa_family_t.h
index 98ca27f..df8b695 100644
--- a/libc/include/bits/sa_family_t.h
+++ b/libc/include/bits/sa_family_t.h
@@ -26,11 +26,14 @@
* SUCH DAMAGE.
*/
-#ifndef _BITS_SA_FAMILY_T_H_
-#define _BITS_SA_FAMILY_T_H_
+#pragma once
+
+/**
+ * @file bits/sa_family_t.h
+ * @brief The `sa_family_t` type.
+ */
#include <sys/cdefs.h>
+/** The type of fields like `sa_family`. */
typedef unsigned short sa_family_t;
-
-#endif
diff --git a/libc/include/bits/seek_constants.h b/libc/include/bits/seek_constants.h
index 34c5866..6b88606 100644
--- a/libc/include/bits/seek_constants.h
+++ b/libc/include/bits/seek_constants.h
@@ -26,11 +26,16 @@
* SUCH DAMAGE.
*/
-#ifndef _BITS_SEEK_CONSTANTS_H_
-#define _BITS_SEEK_CONSTANTS_H_
+#pragma once
+/**
+ * @file bits/seek_constants.h
+ * @brief The `SEEK_` constants.
+ */
+
+/** Seek to an absolute offset. */
#define SEEK_SET 0
+/** Seek relative to the current offset. */
#define SEEK_CUR 1
+/** Seek relative to the end of the file. */
#define SEEK_END 2
-
-#endif
diff --git a/libc/include/bits/strcasecmp.h b/libc/include/bits/strcasecmp.h
index 594046a..3994b68 100644
--- a/libc/include/bits/strcasecmp.h
+++ b/libc/include/bits/strcasecmp.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _BITS_STRCASECMP_H_
-#define _BITS_STRCASECMP_H_
+#pragma once
+
+/**
+ * @file bits/strcasecmp.h
+ * @brief Case-insensitive string comparison.
+ */
#include <sys/cdefs.h>
#include <sys/types.h>
@@ -35,11 +39,33 @@
__BEGIN_DECLS
+/**
+ * [strcasecmp(3)](http://man7.org/linux/man-pages/man3/strcasecmp.3.html) compares two strings
+ * ignoring case.
+ *
+ * Returns an integer less than, equal to, or greater than zero if the first string is less than,
+ * equal to, or greater than the second string (ignoring case).
+ */
int strcasecmp(const char* __s1, const char* __s2) __attribute_pure__;
+
+/**
+ * Like strcasecmp() but taking a `locale_t`.
+ */
int strcasecmp_l(const char* __s1, const char* __s2, locale_t __l) __attribute_pure__ __INTRODUCED_IN(23);
+
+/**
+ * [strncasecmp(3)](http://man7.org/linux/man-pages/man3/strncasecmp.3.html) compares the first
+ * `n` bytes of two strings ignoring case.
+ *
+ * Returns an integer less than, equal to, or greater than zero if the first `n` bytes of the
+ * first string is less than, equal to, or greater than the first `n` bytes of the second
+ * string (ignoring case).
+ */
int strncasecmp(const char* __s1, const char* __s2, size_t __n) __attribute_pure__;
+
+/**
+ * Like strncasecmp() but taking a `locale_t`.
+ */
int strncasecmp_l(const char* __s1, const char* __s2, size_t __n, locale_t __l) __attribute_pure__ __INTRODUCED_IN(23);
__END_DECLS
-
-#endif
diff --git a/libc/include/bits/struct_file.h b/libc/include/bits/struct_file.h
index 08e18a1..abbd320 100644
--- a/libc/include/bits/struct_file.h
+++ b/libc/include/bits/struct_file.h
@@ -26,13 +26,13 @@
* SUCH DAMAGE.
*/
-#ifndef BITS_FILE_H
-#define BITS_FILE_H
+#pragma once
#include <sys/cdefs.h>
__BEGIN_DECLS
+/** The opaque structure implementing `FILE`. Do not make any assumptions about its content. */
struct __sFILE {
#if defined(__LP64__)
char __private[152];
@@ -42,5 +42,3 @@
} __attribute__((aligned(sizeof(void*))));
__END_DECLS
-
-#endif /* BITS_FILE_H */
diff --git a/libc/include/bits/timespec.h b/libc/include/bits/timespec.h
index df7a7ce..0497cfe 100644
--- a/libc/include/bits/timespec.h
+++ b/libc/include/bits/timespec.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _BITS_TIMESPEC_H_
-#define _BITS_TIMESPEC_H_
+#pragma once
+
+/**
+ * @file bits/timespec.h
+ * @brief The `timespec` struct.
+ */
#include <sys/cdefs.h>
#include <sys/types.h>
@@ -38,10 +42,11 @@
*/
#ifndef _STRUCT_TIMESPEC
#define _STRUCT_TIMESPEC
+/** Represents a time. */
struct timespec {
+ /** Number of seconds. */
time_t tv_sec;
+ /** Number of nanoseconds. Must be less than 1,000,000. */
long tv_nsec;
};
#endif
-
-#endif
diff --git a/libc/include/bits/wait.h b/libc/include/bits/wait.h
index a35f789..a6a2129 100644
--- a/libc/include/bits/wait.h
+++ b/libc/include/bits/wait.h
@@ -26,24 +26,43 @@
* SUCH DAMAGE.
*/
-#ifndef _BITS_WAIT_H_
-#define _BITS_WAIT_H_
+#pragma once
+
+/**
+ * @file bits/wait.h
+ * @brief Process exit status macros.
+ */
#include <sys/cdefs.h>
#include <linux/wait.h>
-#define WEXITSTATUS(s) (((s) & 0xff00) >> 8)
-#define WCOREDUMP(s) ((s) & 0x80)
-#define WTERMSIG(s) ((s) & 0x7f)
-#define WSTOPSIG(s) WEXITSTATUS(s)
+/** Returns the exit status from a process for which `WIFEXITED` is true. */
+#define WEXITSTATUS(__status) (((__status) & 0xff00) >> 8)
-#define WIFEXITED(s) (WTERMSIG(s) == 0)
-#define WIFSTOPPED(s) (WTERMSIG(s) == 0x7f)
-#define WIFSIGNALED(s) (WTERMSIG((s)+1) >= 2)
-#define WIFCONTINUED(s) ((s) == 0xffff)
+/** Returns true if a process dumped core. */
+#define WCOREDUMP(__status) ((__status) & 0x80)
-#define W_EXITCODE(ret, sig) ((ret) << 8 | (sig))
-#define W_STOPCODE(sig) ((sig) << 8 | 0x7f)
+/** Returns the terminating signal from a process, or 0 if it exited normally. */
+#define WTERMSIG(__status) ((__status) & 0x7f)
-#endif
+/** Returns the signal that stopped the process, if `WIFSTOPPED` is true. */
+#define WSTOPSIG(__status) WEXITSTATUS(__status)
+
+/** Returns true if the process exited normally. */
+#define WIFEXITED(__status) (WTERMSIG(__status) == 0)
+
+/** Returns true if the process was stopped by a signal. */
+#define WIFSTOPPED(__status) (WTERMSIG(__status) == 0x7f)
+
+/** Returns true if the process was terminated by a signal. */
+#define WIFSIGNALED(__status) (WTERMSIG((__status)+1) >= 2)
+
+/** Returns true if the process was resumed . */
+#define WIFCONTINUED(__status) ((__status) == 0xffff)
+
+/** Constructs a status value from the given exit code and signal number. */
+#define W_EXITCODE(__exit_code, __signal_number) ((__exit_code) << 8 | (__signal_number))
+
+/** Constructs a status value for a process stopped by the given signal. */
+#define W_STOPCODE(__signal_number) ((__signal_number) << 8 | 0x7f)
diff --git a/libc/include/bits/wchar_limits.h b/libc/include/bits/wchar_limits.h
index ffad604..311b02e 100644
--- a/libc/include/bits/wchar_limits.h
+++ b/libc/include/bits/wchar_limits.h
@@ -26,19 +26,23 @@
* SUCH DAMAGE.
*/
-#ifndef _BITS_WCHAR_LIMITS_H_
-#define _BITS_WCHAR_LIMITS_H_
+#pragma once
+
+/**
+ * @file bits/wchar_limits.h
+ * @brief `wchar_t` limits.
+ */
#include <sys/cdefs.h>
-/* Both GCC and clang define __WCHAR_MAX__. */
+/** The maximum value of a `wchar_t`. */
#define WCHAR_MAX __WCHAR_MAX__
/* As of 3.4, clang still doesn't define __WCHAR_MIN__. */
#if defined(__WCHAR_UNSIGNED__)
+/** The minimum value of a `wchar_t`. */
# define WCHAR_MIN L'\0'
#else
+/** The minimum value of a `wchar_t`. */
# define WCHAR_MIN (-(WCHAR_MAX) - 1)
#endif
-
-#endif