Another round of documentation.
Bug: N/A
Test: N/A
Change-Id: I1b818fbb36ddd6d084dee56828290c2717a0c9b0
diff --git a/libc/include/android/set_abort_message.h b/libc/include/android/set_abort_message.h
index 3dde673..5d8d8ee 100644
--- a/libc/include/android/set_abort_message.h
+++ b/libc/include/android/set_abort_message.h
@@ -26,15 +26,26 @@
* SUCH DAMAGE.
*/
-#ifndef _SET_ABORT_MESSAGE_H
-#define _SET_ABORT_MESSAGE_H
+#pragma once
+
+/**
+ * @file android/set_abort_message.h
+ * @brief The android_set_abort_message() function.
+ */
#include <sys/cdefs.h>
__BEGIN_DECLS
+/**
+ * android_set_abort_message() sets the abort message that will be shown
+ * by [debuggerd](https://source.android.com/devices/tech/debug/native-crash).
+ * This is meant for use by libraries that deliberately abort so that they can
+ * provide an explanation. It is used within bionic to implement assert() and
+ * all FORTIFY/fdsan aborts.
+ *
+ * Available since API level 21.
+ */
void android_set_abort_message(const char* __msg) __INTRODUCED_IN(21);
__END_DECLS
-
-#endif
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
diff --git a/libc/include/ctype.h b/libc/include/ctype.h
index df11cb1..e91b0e2 100644
--- a/libc/include/ctype.h
+++ b/libc/include/ctype.h
@@ -37,69 +37,129 @@
* @(#)ctype.h 5.3 (Berkeley) 4/3/91
*/
-#ifndef _CTYPE_H_
-#define _CTYPE_H_
+#pragma once
+
+/**
+ * @file ctype.h
+ * @brief ASCII character classification.
+ */
#include <sys/cdefs.h>
#include <xlocale.h>
+/** Internal implementation detail. Do not use. */
#define _CTYPE_U 0x01
+/** Internal implementation detail. Do not use. */
#define _CTYPE_L 0x02
+/** Internal implementation detail. Do not use. */
#define _CTYPE_D 0x04
+/** Internal implementation detail. Do not use. */
#define _CTYPE_S 0x08
+/** Internal implementation detail. Do not use. */
#define _CTYPE_P 0x10
+/** Internal implementation detail. Do not use. */
#define _CTYPE_C 0x20
+/** Internal implementation detail. Do not use. */
#define _CTYPE_X 0x40
+/** Internal implementation detail. Do not use. */
#define _CTYPE_B 0x80
+/** Internal implementation detail. Do not use. */
#define _CTYPE_R (_CTYPE_P|_CTYPE_U|_CTYPE_L|_CTYPE_D|_CTYPE_B)
+/** Internal implementation detail. Do not use. */
#define _CTYPE_A (_CTYPE_L|_CTYPE_U)
-
-/* _CTYPE_N was added to NDK r10 and is expected by gnu-libstdc++ */
+/** Internal implementation detail. Do not use. */
#define _CTYPE_N _CTYPE_D
__BEGIN_DECLS
+/** Internal implementation detail. Do not use. */
extern const char* _ctype_;
+/** Returns true if `ch` is in `[A-Za-z0-9]`. */
int isalnum(int __ch);
+/** Returns true if `ch` is in `[A-Za-z]`. */
int isalpha(int __ch);
+/** Returns true if `ch` is a space or tab. */
int isblank(int __ch);
+/** Returns true if `ch` is a control character (any character before space, plus DEL). */
int iscntrl(int __ch);
+/** Returns true if `ch` is in `[0-9]`. */
int isdigit(int __ch);
+/** Returns true if `ch` is `[A-Za-z0-9]` or punctuation. */
int isgraph(int __ch);
+/** Returns true if `ch` is in `[a-z]`. */
int islower(int __ch);
+/** Returns true if `ch` is `[A-Za-z0-9]` or punctuation or space. */
int isprint(int __ch);
+/** Returns true if `ch` is punctuation. */
int ispunct(int __ch);
+/** Returns true if `ch` is in `[ \f\n\r\t\v]`. */
int isspace(int __ch);
+/** Returns true if `ch` is in `[A-Z]`. */
int isupper(int __ch);
+/** Returns true if `ch` is in `[0-9a-f]`. */
int isxdigit(int __ch);
+
+/** Returns the corresponding lower-case character if `ch` is upper-case, or `ch` otherwise. */
int tolower(int __ch);
+
+/**
+ * Returns the corresponding lower-case character if `ch` is upper-case, or undefined otherwise.
+ *
+ * Available since API level 21.
+ *
+ * Prefer tolower() instead.
+ */
+int _tolower(int __ch) __INTRODUCED_IN(21);
+
+/** Returns the corresponding upper-case character if `ch` is lower-case, or `ch` otherwise. */
int toupper(int __ch);
+/**
+ * Returns the corresponding upper-case character if `ch` is lower-case, or undefined otherwise.
+ *
+ * Available since API level 21.
+ *
+ * Prefer toupper() instead.
+ */
+int _toupper(int __ch) __INTRODUCED_IN(21);
+
#if __ANDROID_API__ >= __ANDROID_API_L__
+/** Like isalnum but with an ignored `locale_t`. */
int isalnum_l(int __ch, locale_t __l) __INTRODUCED_IN(21);
+/** Like isalpha but with an ignored `locale_t`. */
int isalpha_l(int __ch, locale_t __l) __INTRODUCED_IN(21);
+/** Like isblank but with an ignored `locale_t`. */
int isblank_l(int __ch, locale_t __l) __INTRODUCED_IN(21);
+/** Like iscntrl but with an ignored `locale_t`. */
int iscntrl_l(int __ch, locale_t __l) __INTRODUCED_IN(21);
+/** Like isdigit but with an ignored `locale_t`. */
int isdigit_l(int __ch, locale_t __l) __INTRODUCED_IN(21);
+/** Like isgraph but with an ignored `locale_t`. */
int isgraph_l(int __ch, locale_t __l) __INTRODUCED_IN(21);
+/** Like islower but with an ignored `locale_t`. */
int islower_l(int __ch, locale_t __l) __INTRODUCED_IN(21);
+/** Like isprint but with an ignored `locale_t`. */
int isprint_l(int __ch, locale_t __l) __INTRODUCED_IN(21);
+/** Like ispunct but with an ignored `locale_t`. */
int ispunct_l(int __ch, locale_t __l) __INTRODUCED_IN(21);
+/** Like isspace but with an ignored `locale_t`. */
int isspace_l(int __ch, locale_t __l) __INTRODUCED_IN(21);
+/** Like isupper but with an ignored `locale_t`. */
int isupper_l(int __ch, locale_t __l) __INTRODUCED_IN(21);
+/** Like isxdigit but with an ignored `locale_t`. */
int isxdigit_l(int __ch, locale_t __l) __INTRODUCED_IN(21);
+/** Like tolower but with an ignored `locale_t`. */
int tolower_l(int __ch, locale_t __l) __INTRODUCED_IN(21);
+/** Like toupper but with an ignored `locale_t`. */
int toupper_l(int __ch, locale_t __l) __INTRODUCED_IN(21);
#else
// Implemented as static inlines before 21.
#endif
+/** Returns true if `ch` is less than 0x80. */
int isascii(int __ch);
+/** Returns `ch & 0x7f`. */
int toascii(int __ch);
-int _tolower(int __ch) __INTRODUCED_IN(21);
-int _toupper(int __ch) __INTRODUCED_IN(21);
__END_DECLS
-
-#endif
diff --git a/libc/include/getopt.h b/libc/include/getopt.h
index c5a6106..014226a 100644
--- a/libc/include/getopt.h
+++ b/libc/include/getopt.h
@@ -30,42 +30,58 @@
* POSSIBILITY OF SUCH DAMAGE.
*/
-#ifndef _GETOPT_H_
-#define _GETOPT_H_
+#pragma once
+
+/**
+ * @file getopt.h
+ * @brief The getopt() and getopt_long() functions.
+ */
#include <sys/cdefs.h>
#include <bits/getopt.h>
-/*
- * GNU-like getopt_long()/getopt_long_only() with 4.4BSD optreset extension.
- */
-#define no_argument 0
-#define required_argument 1
-#define optional_argument 2
+/** A `has_arg` value for `struct option`. */
+#define no_argument 0
+/** A `has_arg` value for `struct option`. */
+#define required_argument 1
+/** A `has_arg` value for `struct option`. */
+#define optional_argument 2
struct option {
- /* name of long option */
- const char *name;
- /*
- * one of no_argument, required_argument, and optional_argument:
- * whether option takes an argument
- */
- int has_arg;
- /* if not NULL, set *flag to val when option found */
- int *flag;
- /* if flag not NULL, value to set *flag to; else return value */
- int val;
+ /** Name of long option. */
+ const char *name;
+
+ /**
+ * One of `no_argument`, `required_argument`, or `optional_argument`.
+ */
+ int has_arg;
+
+ /** If not NULL, set `*flag` to val when option found. */
+ int* flag;
+
+ /** If `flag` not NULL, the value to assign to `*flag`; otherwise the return value. */
+ int val;
};
__BEGIN_DECLS
+
+/**
+ * [getopt_long(3)](http://man7.org/linux/man-pages/man3/getopt.3.html) parses command-line options.
+ */
int getopt_long(int __argc, char* const* __argv, const char* __options, const struct option* __long_options, int* __long_index);
+
+/**
+ * [getopt_long_only(3)](http://man7.org/linux/man-pages/man3/getopt.3.html) parses command-line options.
+ */
int getopt_long_only(int __argc, char* const* __argv, const char* __options, const struct option* __long_options, int* __long_index);
#ifndef _OPTRESET_DECLARED
-#define _OPTRESET_DECLARED
-extern int optreset; /* getopt(3) external variable */
+#define _OPTRESET_DECLARED
+/**
+ * Must be set to 1 to reset the `getopt` functions before scanning a new argument vector.
+ */
+extern int optreset;
#endif
+
__END_DECLS
-
-#endif
diff --git a/libc/include/net/route.h b/libc/include/net/route.h
index 9c53875..21cd80b 100644
--- a/libc/include/net/route.h
+++ b/libc/include/net/route.h
@@ -26,13 +26,10 @@
* SUCH DAMAGE.
*/
-#ifndef _NET_ROUTE_H_
-#define _NET_ROUTE_H_
+#pragma once
#include <sys/cdefs.h>
#include <sys/socket.h>
#include <linux/route.h>
#include <linux/in6.h>
#include <linux/ipv6_route.h>
-
-#endif
diff --git a/libc/include/netinet/ether.h b/libc/include/netinet/ether.h
index 3e6a4e3..6268a14 100644
--- a/libc/include/netinet/ether.h
+++ b/libc/include/netinet/ether.h
@@ -26,19 +26,56 @@
* SUCH DAMAGE.
*/
-#ifndef _NETINET_ETHER_H_
-#define _NETINET_ETHER_H_ 1
+#pragma once
+
+/**
+ * @file netinet/ether.h
+ * @brief Ethernet (MAC) addresses.
+ */
#include <sys/cdefs.h>
#include <netinet/if_ether.h>
__BEGIN_DECLS
+/**
+ * [ether_ntoa(3)](http://man7.org/linux/man-pages/man3/ether_ntoa.3.html) returns a string
+ * representation of the given Ethernet address.
+ *
+ * Returns a pointer to a static buffer.
+ *
+ * Available since API level 11.
+ */
char* ether_ntoa(const struct ether_addr* __addr) __INTRODUCED_IN(11);
+
+/**
+ * [ether_ntoa_r(3)](http://man7.org/linux/man-pages/man3/ether_ntoa_r.3.html) returns a string
+ * representation of the given Ethernet address.
+ *
+ * Returns a pointer to the given buffer.
+ *
+ * Available since API level 11.
+ */
char* ether_ntoa_r(const struct ether_addr* __addr, char* __buf) __INTRODUCED_IN(11);
+
+/**
+ * [ether_aton(3)](http://man7.org/linux/man-pages/man3/ether_aton.3.html) returns an `ether_addr`
+ * corresponding to the given Ethernet address string.
+ *
+ * Returns a pointer to a static buffer, or NULL if the given string isn't a valid MAC address.
+ *
+ * Available since API level 11.
+ */
struct ether_addr* ether_aton(const char* __ascii) __INTRODUCED_IN(11);
+
+/**
+ * [ether_aton_r(3)](http://man7.org/linux/man-pages/man3/ether_aton_r.3.html) returns an
+ * `ether_addr` corresponding to the given Ethernet address string.
+ *
+ * Returns a pointer to the given buffer, or NULL if the given string isn't a valid MAC address.
+ *
+ * Available since API level 11.
+ */
struct ether_addr* ether_aton_r(const char* __ascii, struct ether_addr* __addr) __INTRODUCED_IN(11);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/auxv.h b/libc/include/sys/auxv.h
index 9251390..c651940 100644
--- a/libc/include/sys/auxv.h
+++ b/libc/include/sys/auxv.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_AUXV_H_
-#define _SYS_AUXV_H_
+#pragma once
+
+/**
+ * @file sys/auxv.h
+ * @brief The getauxval() function.
+ */
#include <sys/cdefs.h>
@@ -35,8 +39,15 @@
__BEGIN_DECLS
+/**
+ * [getauxval(3)](http://man7.org/linux/man-pages/man2/personality.2.html) returns values from
+ * the ELF auxiliary vector passed by the kernel.
+ *
+ * Returns the corresponding value on success,
+ * and returns 0 and sets `errno` to `ENOENT` on failure.
+ *
+ * Available since API level 18.
+ */
unsigned long int getauxval(unsigned long int __type) __INTRODUCED_IN(18);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/capability.h b/libc/include/sys/capability.h
index 637c844..4cb698f 100644
--- a/libc/include/sys/capability.h
+++ b/libc/include/sys/capability.h
@@ -26,17 +26,32 @@
* SUCH DAMAGE.
*/
-#ifndef _BIONIC_SYS_CAPABILITY_H
-#define _BIONIC_SYS_CAPABILITY_H
+#pragma once
+
+/**
+ * @file sys/capability.h
+ * @brief Capabilities.
+ */
#include <sys/cdefs.h>
#include <linux/capability.h>
__BEGIN_DECLS
+/**
+ * [capget(2)](http://man7.org/linux/man-pages/man2/capget.2.html) gets the calling
+ * thread's capabilities.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ */
int capget(cap_user_header_t __hdr_ptr, cap_user_data_t __data_ptr);
+
+/**
+ * [capset(2)](http://man7.org/linux/man-pages/man2/capset.2.html) sets the calling
+ * thread's capabilities.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ */
int capset(cap_user_header_t __hdr_ptr, const cap_user_data_t __data_ptr);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/eventfd.h b/libc/include/sys/eventfd.h
index 3cfb5e7..85f9877 100644
--- a/libc/include/sys/eventfd.h
+++ b/libc/include/sys/eventfd.h
@@ -26,24 +26,48 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_EVENTFD_H
-#define _SYS_EVENTFD_H
+#pragma once
+
+/**
+ * @file sys/eventfd.h
+ * @brief Event notification file descriptors.
+ */
#include <sys/cdefs.h>
#include <fcntl.h>
__BEGIN_DECLS
+/** The eventfd() flag for a close-on-exec file descriptor. */
#define EFD_CLOEXEC O_CLOEXEC
+/** The eventfd() flag for a non-blocking file descriptor. */
#define EFD_NONBLOCK O_NONBLOCK
-typedef uint64_t eventfd_t;
-
+/**
+ * [eventfd(2)](http://man7.org/linux/man-pages/man2/eventfd.2.html) creates a file descriptor
+ * for event notification.
+ *
+ * Returns a new file descriptor on success, and returns -1 and sets `errno` on failure.
+ */
int eventfd(unsigned int __initial_value, int __flags);
+/** The type used by eventfd_read() and eventfd_write(). */
+typedef uint64_t eventfd_t;
+
+/**
+ * [eventfd_read(3)](http://man7.org/linux/man-pages/man2/eventfd.2.html) is a convenience
+ * wrapper to read an `eventfd_t` from an eventfd file descriptor.
+ *
+ * Returns 0 on success, or returns -1 otherwise.
+ */
int eventfd_read(int __fd, eventfd_t* __value);
+
+/**
+ * [eventfd_write(3)](http://man7.org/linux/man-pages/man2/eventfd.2.html) is a convenience
+ * wrapper to write an `eventfd_t` to an eventfd file descriptor.
+ *
+ * Returns 0 on success, or returns -1 otherwise.
+ */
int eventfd_write(int __fd, eventfd_t __value);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/file.h b/libc/include/sys/file.h
index a420021..ccdfeea 100644
--- a/libc/include/sys/file.h
+++ b/libc/include/sys/file.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_FILE_H_
-#define _SYS_FILE_H_
+#pragma once
+
+/**
+ * @file sys/file.h
+ * @brief The flock() function.
+ */
#include <sys/cdefs.h>
#include <sys/types.h>
@@ -36,8 +40,12 @@
__BEGIN_DECLS
+/**
+ * [flock(2)](http://man7.org/linux/man-pages/man2/flock.2.html) performs
+ * advisory file lock operations.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ */
int flock(int __fd, int __op);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/fsuid.h b/libc/include/sys/fsuid.h
index bb7a58d..c1c8ebb 100644
--- a/libc/include/sys/fsuid.h
+++ b/libc/include/sys/fsuid.h
@@ -26,17 +26,36 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_FSUID_H_
-#define _SYS_FSUID_H_
+#pragma once
+
+/**
+ * @file sys/fsuid.h
+ * @brief Set UID/GID for filesystem checks.
+ */
#include <sys/cdefs.h>
#include <sys/types.h>
__BEGIN_DECLS
+/**
+ * [setfsuid(2)](http://man7.org/linux/man-pages/man2/setfsuid.2.html) sets the UID used for
+ * filesystem checks.
+ *
+ * Returns the previous UID.
+ *
+ * Available since API level 21.
+ */
int setfsuid(uid_t __uid) __INTRODUCED_IN(21);
+
+/**
+ * [setfsgid(2)](http://man7.org/linux/man-pages/man2/setfsgid.2.html) sets the GID used for
+ * filesystem checks.
+ *
+ * Returns the previous GID.
+ *
+ * Available since API level 21.
+ */
int setfsgid(gid_t __gid) __INTRODUCED_IN(21);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/ioctl.h b/libc/include/sys/ioctl.h
index b48b7f9..178de4a 100644
--- a/libc/include/sys/ioctl.h
+++ b/libc/include/sys/ioctl.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_IOCTL_H_
-#define _SYS_IOCTL_H_
+#pragma once
+
+/**
+ * @file sys/ioctl.h
+ * @brief The ioctl() function.
+ */
#include <sys/cdefs.h>
#include <linux/ioctl.h>
@@ -39,5 +43,3 @@
#include <linux/tty.h>
#include <bits/ioctl.h>
-
-#endif
diff --git a/libc/include/sys/ipc.h b/libc/include/sys/ipc.h
index dee7c8a..c81ec1a 100644
--- a/libc/include/sys/ipc.h
+++ b/libc/include/sys/ipc.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_IPC_H
-#define _SYS_IPC_H
+#pragma once
+
+/**
+ * @file sys/ipc.h
+ * @brief System V IPC.
+ */
#include <sys/cdefs.h>
#include <sys/types.h>
@@ -42,8 +46,12 @@
__BEGIN_DECLS
+/**
+ * [ftok(3)](http://man7.org/linux/man-pages/man3/ftok.3.html) converts a path and id to a
+ * System V IPC key.
+ *
+ * Returns a key on success, and returns -1 and sets `errno` on failure.
+ */
key_t ftok(const char* __path, int __id);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/klog.h b/libc/include/sys/klog.h
index ed746fc..b33d11b 100644
--- a/libc/include/sys/klog.h
+++ b/libc/include/sys/klog.h
@@ -26,28 +26,46 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_KLOG_H_
-#define _SYS_KLOG_H_
+#pragma once
+
+/**
+ * @file sys/klog.h
+ * @brief
+ */
#include <sys/cdefs.h>
__BEGIN_DECLS
-/* These correspond to the kernel's SYSLOG_ACTION_whatever constants. */
-#define KLOG_CLOSE 0
-#define KLOG_OPEN 1
-#define KLOG_READ 2
-#define KLOG_READ_ALL 3
-#define KLOG_READ_CLEAR 4
-#define KLOG_CLEAR 5
-#define KLOG_CONSOLE_OFF 6
-#define KLOG_CONSOLE_ON 7
+/** Used with klogctl(). */
+#define KLOG_CLOSE 0
+/** Used with klogctl(). */
+#define KLOG_OPEN 1
+/** Used with klogctl(). */
+#define KLOG_READ 2
+/** Used with klogctl(). */
+#define KLOG_READ_ALL 3
+/** Used with klogctl(). */
+#define KLOG_READ_CLEAR 4
+/** Used with klogctl(). */
+#define KLOG_CLEAR 5
+/** Used with klogctl(). */
+#define KLOG_CONSOLE_OFF 6
+/** Used with klogctl(). */
+#define KLOG_CONSOLE_ON 7
+/** Used with klogctl(). */
#define KLOG_CONSOLE_LEVEL 8
-#define KLOG_SIZE_UNREAD 9
-#define KLOG_SIZE_BUFFER 10
+/** Used with klogctl(). */
+#define KLOG_SIZE_UNREAD 9
+/** Used with klogctl(). */
+#define KLOG_SIZE_BUFFER 10
+/**
+ * [klogctl(2)](http://man7.org/linux/man-pages/man2/syslog.2.html) operates on the kernel log.
+ *
+ * This system call is not available to applications.
+ * Use syslog() or `<android/log.h>` instead.
+ */
int klogctl(int __type, char* __buf, int __buf_size);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/mount.h b/libc/include/sys/mount.h
index c0c084b..4db1ac1 100644
--- a/libc/include/sys/mount.h
+++ b/libc/include/sys/mount.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_MOUNT_H
-#define _SYS_MOUNT_H
+#pragma once
+
+/**
+ * @file sys/mount.h
+ * @brief Mounting and unmounting filesystems.
+ */
#include <sys/cdefs.h>
#include <sys/ioctl.h>
@@ -35,16 +39,38 @@
__BEGIN_DECLS
-/* umount2 flags. */
+/** The umount2() flag to force unmounting. */
#define MNT_FORCE 1
+/** The umount2() flag to lazy unmount. */
#define MNT_DETACH 2
+/** The umount2() flag to mark a mount point as expired. */
#define MNT_EXPIRE 4
+
+/** The umount2() flag to not dereference the mount point path if it's a symbolic link. */
#define UMOUNT_NOFOLLOW 8
+/**
+ * [mount(2)](http://man7.org/linux/man-pages/man2/mount.2.html) mounts the filesystem `source` at
+ * the mount point `target`.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ */
int mount(const char* __source, const char* __target, const char* __fs_type, unsigned long __flags, const void* __data);
+
+/**
+ * [umount(2)](http://man7.org/linux/man-pages/man2/umount.2.html) unmounts the filesystem at
+ * the given mount point.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ */
int umount(const char* __target);
+
+/**
+ * [umount2(2)](http://man7.org/linux/man-pages/man2/umount2.2.html) unmounts the filesystem at
+ * the given mount point, according to the supplied flags.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ */
int umount2(const char* __target, int __flags);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/msg.h b/libc/include/sys/msg.h
index 0273499..e19452c 100644
--- a/libc/include/sys/msg.h
+++ b/libc/include/sys/msg.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_MSG_H_
-#define _SYS_MSG_H_
+#pragma once
+
+/**
+ * @file sys/msg.h
+ * @brief System V message queues. Not useful on Android because it's disallowed by SELinux.
+ */
#include <sys/cdefs.h>
#include <sys/ipc.h>
@@ -41,11 +45,13 @@
typedef __kernel_ulong_t msgqnum_t;
typedef __kernel_ulong_t msglen_t;
+/** Not useful on Android; disallowed by SELinux. */
int msgctl(int __msg_id, int __cmd, struct msqid_ds* __buf) __INTRODUCED_IN(26);
+/** Not useful on Android; disallowed by SELinux. */
int msgget(key_t __key, int __flags) __INTRODUCED_IN(26);
+/** Not useful on Android; disallowed by SELinux. */
ssize_t msgrcv(int __msg_id, void* __msgbuf_ptr, size_t __size, long __type, int __flags) __INTRODUCED_IN(26);
+/** Not useful on Android; disallowed by SELinux. */
int msgsnd(int __msg_id, const void* __msgbuf_ptr, size_t __size, int __flags) __INTRODUCED_IN(26);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/param.h b/libc/include/sys/param.h
index ec50da2..4a83e9d 100644
--- a/libc/include/sys/param.h
+++ b/libc/include/sys/param.h
@@ -26,27 +26,34 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_PARAM_H_
-#define _SYS_PARAM_H_
+#pragma once
+
+/**
+ * @file sys/param.h
+ * @brief Various macros.
+ */
#include <limits.h>
#include <linux/param.h>
#include <sys/cdefs.h>
+/** The unit of `st_blocks` in `struct stat`. */
#define DEV_BSIZE 512
+/** A historical name for PATH_MAX. */
#define MAXPATHLEN PATH_MAX
+
#define MAXSYMLINKS 8
-/* Macros for counting and rounding. */
#ifndef howmany
#define howmany(x, y) (((x)+((y)-1))/(y))
#endif
#define roundup(x, y) ((((x)+((y)-1))/(y))*(y))
-#define powerof2(x) ((((x)-1)&(x))==0)
-/* Macros for min/max. */
+/** Returns true if the argument is a power of two. */
+#define powerof2(x) ((((x)-1)&(x))==0)
+
+/** Returns the lesser of its two arguments. */
#define MIN(a,b) (((a)<(b))?(a):(b))
+/** Returns the greater of its two arguments. */
#define MAX(a,b) (((a)>(b))?(a):(b))
-
-#endif
diff --git a/libc/include/sys/personality.h b/libc/include/sys/personality.h
index 51b5cd7..cea0bf8 100644
--- a/libc/include/sys/personality.h
+++ b/libc/include/sys/personality.h
@@ -26,16 +26,26 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_PERSONALITY_H_
-#define _SYS_PERSONALITY_H_
+#pragma once
+
+/**
+ * @file sys/personality.h
+ * @brief The personality() function.
+ */
#include <sys/cdefs.h>
#include <linux/personality.h>
__BEGIN_DECLS
+/**
+ * [personality(2)](http://man7.org/linux/man-pages/man2/personality.2.html) sets the calling
+ * process' personality.
+ *
+ * Returns the previous persona on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 15.
+ */
int personality(unsigned int __persona) __INTRODUCED_IN(15);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/quota.h b/libc/include/sys/quota.h
index 157c2d9..f8faee7 100644
--- a/libc/include/sys/quota.h
+++ b/libc/include/sys/quota.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_QUOTA_H_
-#define _SYS_QUOTA_H_
+#pragma once
+
+/**
+ * @file sys/quota.h
+ * @brief The quotactl() function.
+ */
#include <sys/cdefs.h>
@@ -40,8 +44,13 @@
__BEGIN_DECLS
+/**
+ * [quotactl(2)](http://man7.org/linux/man-pages/man2/quotactl.2.html) manipulates disk quotas.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 26.
+ */
int quotactl(int __cmd, const char* __special, int __id, char* __addr) __INTRODUCED_IN(26);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/random.h b/libc/include/sys/random.h
index 4b849f3..be52bd9 100644
--- a/libc/include/sys/random.h
+++ b/libc/include/sys/random.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_RANDOM_H_
-#define _SYS_RANDOM_H_
+#pragma once
+
+/**
+ * @file sys/random.h
+ * @brief The getentropy() and getrandom() functions.
+ */
#include <sys/cdefs.h>
#include <sys/types.h>
@@ -36,12 +40,28 @@
__BEGIN_DECLS
-/* See also arc4random_buf in <stdlib.h>, which is available in all API levels. */
-
+/**
+ * [getentropy(3)](http://man7.org/linux/man-pages/man3/getentropy.3.html) fills the given buffer
+ * with random bytes.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 28.
+ *
+ * See also arc4random_buf() which is available in all API levels.
+ */
int getentropy(void* __buffer, size_t __buffer_size) __wur __INTRODUCED_IN(28);
+/**
+ * [getrandom(2)](http://man7.org/linux/man-pages/man2/getrandom.2.html) fills the given buffer
+ * with random bytes.
+ *
+ * Returns the number of bytes copied on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 28.
+ *
+ * See also arc4random_buf() which is available in all API levels.
+ */
ssize_t getrandom(void* __buffer, size_t __buffer_size, unsigned int __flags) __wur __INTRODUCED_IN(28);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/reboot.h b/libc/include/sys/reboot.h
index c0c4860..156d947 100644
--- a/libc/include/sys/reboot.h
+++ b/libc/include/sys/reboot.h
@@ -26,24 +26,35 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_REBOOT_H_
-#define _SYS_REBOOT_H_
+#pragma once
+
+/**
+ * @file sys/reboot.h
+ * @brief The reboot() function.
+ */
#include <sys/cdefs.h>
#include <linux/reboot.h>
__BEGIN_DECLS
-/* use glibc names as well */
+/** The glibc name for the reboot() flag `LINUX_REBOOT_CMD_RESTART`. */
+#define RB_AUTOBOOT LINUX_REBOOT_CMD_RESTART
+/** The glibc name for the reboot() flag `LINUX_REBOOT_CMD_HALT`. */
+#define RB_HALT_SYSTEM LINUX_REBOOT_CMD_HALT
+/** The glibc name for the reboot() flag `LINUX_REBOOT_CMD_CAD_ON`. */
+#define RB_ENABLE_CAD LINUX_REBOOT_CMD_CAD_ON
+/** The glibc name for the reboot() flag `LINUX_REBOOT_CMD_CAD_OFF`. */
+#define RB_DISABLE_CAD LINUX_REBOOT_CMD_CAD_OFF
+/** The glibc name for the reboot() flag `LINUX_REBOOT_CMD_POWER_OFF`. */
+#define RB_POWER_OFF LINUX_REBOOT_CMD_POWER_OFF
-#define RB_AUTOBOOT LINUX_REBOOT_CMD_RESTART
-#define RB_HALT_SYSTEM LINUX_REBOOT_CMD_HALT
-#define RB_ENABLE_CAD LINUX_REBOOT_CMD_CAD_ON
-#define RB_DISABLE_CAD LINUX_REBOOT_CMD_CAD_OFF
-#define RB_POWER_OFF LINUX_REBOOT_CMD_POWER_OFF
-
+/**
+ * [reboot(2)](http://man7.org/linux/man-pages/man2/reboot.2.html) reboots the device.
+ *
+ * Does not return on successful reboot, returns 0 if CAD was successfully enabled/disabled,
+ * and returns -1 and sets `errno` on failure.
+ */
int reboot(int __cmd);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/sendfile.h b/libc/include/sys/sendfile.h
index 97432c0..60bbde8 100644
--- a/libc/include/sys/sendfile.h
+++ b/libc/include/sys/sendfile.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_SENDFILE_H_
-#define _SYS_SENDFILE_H_
+#pragma once
+
+/**
+ * @file sys/sendfile.h
+ * @brief The sendfile() function.
+ */
#include <sys/cdefs.h>
#include <sys/types.h>
@@ -38,10 +42,21 @@
#if defined(__USE_FILE_OFFSET64)
ssize_t sendfile(int __out_fd, int __in_fd, off_t* __offset, size_t __count) __RENAME(sendfile64) __INTRODUCED_IN(21);
#else
+/**
+ * [sendfile(2)](http://man7.org/linux/man-pages/man2/sendfile.2.html) copies data directly
+ * between two file descriptors.
+ *
+ * Returns the number of bytes copied on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 21.
+ */
ssize_t sendfile(int __out_fd, int __in_fd, off_t* __offset, size_t __count);
#endif
+
+/**
+ * Like sendfile() but allows using a 64-bit offset
+ * even from a 32-bit process without `__FILE_OFFSET_BITS=64`.
+ */
ssize_t sendfile64(int __out_fd, int __in_fd, off64_t* __offset, size_t __count) __INTRODUCED_IN(21);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/shm.h b/libc/include/sys/shm.h
index 4723eba..a3f84d3 100644
--- a/libc/include/sys/shm.h
+++ b/libc/include/sys/shm.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_SHM_H_
-#define _SYS_SHM_H_
+#pragma once
+
+/**
+ * @file sys/shm.h
+ * @brief System V shared memory. Not useful on Android because it's disallowed by SELinux.
+ */
#include <sys/cdefs.h>
#include <sys/ipc.h>
@@ -42,11 +46,13 @@
typedef unsigned long shmatt_t;
+/** Not useful on Android; disallowed by SELinux. */
void* shmat(int __shm_id, const void* __addr, int __flags) __INTRODUCED_IN(26);
+/** Not useful on Android; disallowed by SELinux. */
int shmctl(int __shm_id, int __cmd, struct shmid_ds* __buf) __INTRODUCED_IN(26);
+/** Not useful on Android; disallowed by SELinux. */
int shmdt(const void* __addr) __INTRODUCED_IN(26);
+/** Not useful on Android; disallowed by SELinux. */
int shmget(key_t __key, size_t __size, int __flags) __INTRODUCED_IN(26);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/signalfd.h b/libc/include/sys/signalfd.h
index 2337cd7..bd911f7 100644
--- a/libc/include/sys/signalfd.h
+++ b/libc/include/sys/signalfd.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_SIGNALFD_H_
-#define _SYS_SIGNALFD_H_
+#pragma once
+
+/**
+ * @file sys/signalfd.h
+ * @brief File-descriptor based signal interface.
+ */
#include <sys/cdefs.h>
@@ -36,9 +40,19 @@
__BEGIN_DECLS
+/**
+ * [signalfd(2)](http://man7.org/linux/man-pages/man2/signalfd.2.html) creates/manipulates a
+ * file descriptor for reading signal events.
+ *
+ * Returns the file descriptor on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 18.
+ */
int signalfd(int __fd, const sigset_t* __mask, int __flags) __INTRODUCED_IN(18);
+
+/**
+ * Like signalfd() but allows setting a signal mask with RT signals even from a 32-bit process.
+ */
int signalfd64(int __fd, const sigset64_t* __mask, int __flags) __INTRODUCED_IN(28);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/swap.h b/libc/include/sys/swap.h
index 8a30cce..467b98c 100644
--- a/libc/include/sys/swap.h
+++ b/libc/include/sys/swap.h
@@ -26,21 +26,47 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_SWAP_H_
-#define _SYS_SWAP_H_
+#pragma once
+
+/**
+ * @file sys/swap.h
+ * @brief Swap control.
+ */
#include <sys/cdefs.h>
__BEGIN_DECLS
+/** swapon() flag to discard pages. */
#define SWAP_FLAG_DISCARD 0x10000
+
+/**
+ * swapon() flag to give this swap area a non-default priority.
+ * The priority is also encoded in the flags:
+ * `(priority << SWAP_FLAG_PRIO_SHIFT) & SWAP_FLAG_PRIO_MASK`.
+ */
#define SWAP_FLAG_PREFER 0x8000
+/** See SWAP_FLAG_PREFER. */
#define SWAP_FLAG_PRIO_MASK 0x7fff
+/** See SWAP_FLAG_PREFER. */
#define SWAP_FLAG_PRIO_SHIFT 0
+/**
+ * [swapon(2)](http://man7.org/linux/man-pages/man2/swapon.2.html) enables swapping.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 19.
+ */
int swapon(const char* __path, int __flags) __INTRODUCED_IN(19);
+
+/**
+ * [swapoff(2)](http://man7.org/linux/man-pages/man2/swapoff.2.html) disables swapping.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 19.
+ */
int swapoff(const char* __path) __INTRODUCED_IN(19);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/sysinfo.h b/libc/include/sys/sysinfo.h
index 6da02ee..4ecf986 100644
--- a/libc/include/sys/sysinfo.h
+++ b/libc/include/sys/sysinfo.h
@@ -26,20 +26,63 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_SYSINFO_H_
-#define _SYS_SYSINFO_H_
+#pragma once
+
+/**
+ * @file sys/sysinfo.h
+ * @brief System information.
+ */
#include <sys/cdefs.h>
#include <linux/kernel.h>
__BEGIN_DECLS
+/**
+ * [sysinfo(2)](http://man7.org/linux/man-pages/man2/sysinfo.2.html) queries system information.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ */
int sysinfo(struct sysinfo* __info);
+
+/**
+ * [get_nprocs_conf(3)](http://man7.org/linux/man-pages/man3/get_nprocs_conf.3.html) returns
+ * the total number of processors in the system.
+ *
+ * Available since API level 23.
+ *
+ * See also sysconf().
+ */
int get_nprocs_conf(void) __INTRODUCED_IN(23);
+
+/**
+ * [get_nprocs(3)](http://man7.org/linux/man-pages/man3/get_nprocs.3.html) returns
+ * the number of processors in the system that are currently on-line.
+ *
+ * Available since API level 23.
+ *
+ * See also sysconf().
+ */
int get_nprocs(void) __INTRODUCED_IN(23);
+
+/**
+ * [get_phys_pages(3)](http://man7.org/linux/man-pages/man3/get_phys_pages.3.html) returns
+ * the total number of physical pages in the system.
+ *
+ * Available since API level 23.
+ *
+ * See also sysconf().
+ */
long get_phys_pages(void) __INTRODUCED_IN(23);
+
+/**
+ * [get_avphys_pages(3)](http://man7.org/linux/man-pages/man3/get_avphys_pages.3.html) returns
+ * the number of physical pages in the system that are currently available.
+ *
+ * Available since API level 23.
+ *
+ * See also sysconf().
+ */
long get_avphys_pages(void) __INTRODUCED_IN(23);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/sysmacros.h b/libc/include/sys/sysmacros.h
index 592cc5e..64cf289 100644
--- a/libc/include/sys/sysmacros.h
+++ b/libc/include/sys/sysmacros.h
@@ -26,21 +26,26 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_SYSMACROS_H_
-#define _SYS_SYSMACROS_H_
+#pragma once
+
+/**
+ * @file sys/sysmacros.h
+ * @brief Major/minor device number macros.
+ */
#include <sys/cdefs.h>
+/** Combines `major` and `minor` into a device number. */
#define makedev(__major, __minor) \
( \
(((__major) & 0xfffff000ULL) << 32) | (((__major) & 0xfffULL) << 8) | \
(((__minor) & 0xffffff00ULL) << 12) | (((__minor) & 0xffULL)) \
)
+/** Extracts the major part of a device number. */
#define major(__dev) \
((unsigned) ((((unsigned long long) (__dev) >> 32) & 0xfffff000) | (((__dev) >> 8) & 0xfff)))
+/** Extracts the minor part of a device number. */
#define minor(__dev) \
((unsigned) ((((__dev) >> 12) & 0xffffff00) | ((__dev) & 0xff)))
-
-#endif /* _SYS_SYSMACROS_H_ */
diff --git a/libc/include/sys/timerfd.h b/libc/include/sys/timerfd.h
index 7bf675b..b89941b 100644
--- a/libc/include/sys/timerfd.h
+++ b/libc/include/sys/timerfd.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_TIMERFD_H_
-#define _SYS_TIMERFD_H_
+#pragma once
+
+/**
+ * @file sys/timerfd.h
+ * @brief Timer file descriptors.
+ */
#include <fcntl.h> /* For O_CLOEXEC and O_NONBLOCK. */
#include <time.h>
@@ -36,16 +40,44 @@
__BEGIN_DECLS
-#define TFD_TIMER_ABSTIME (1 << 0)
-#define TFD_TIMER_CANCEL_ON_SET (1 << 1)
-
+/** The timerfd_create() flag for a close-on-exec file descriptor. */
#define TFD_CLOEXEC O_CLOEXEC
+/** The timerfd_create() flag for a non-blocking file descriptor. */
#define TFD_NONBLOCK O_NONBLOCK
+/**
+ * [timerfd_create(2)](http://man7.org/linux/man-pages/man2/timerfd_create.2.html) creates a
+ * timer file descriptor.
+ *
+ * Returns the new file descriptor on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 19.
+ */
int timerfd_create(clockid_t __clock, int __flags) __INTRODUCED_IN(19);
+
+/** The timerfd_settime() flag to use absolute rather than relative times. */
+#define TFD_TIMER_ABSTIME (1 << 0)
+/** The timerfd_settime() flag to cancel an absolute timer if the realtime clock changes. */
+#define TFD_TIMER_CANCEL_ON_SET (1 << 1)
+
+/**
+ * [timerfd_settime(2)](http://man7.org/linux/man-pages/man2/timerfd_settime.2.html) starts or
+ * stops a timer.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 19.
+ */
int timerfd_settime(int __fd, int __flags, const struct itimerspec* __new_value, struct itimerspec* __old_value) __INTRODUCED_IN(19);
+
+/**
+ * [timerfd_gettime(2)](http://man7.org/linux/man-pages/man2/timerfd_gettime.2.html) queries the
+ * current timer settings.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 19.
+ */
int timerfd_gettime(int __fd, struct itimerspec* __current_value) __INTRODUCED_IN(19);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/times.h b/libc/include/sys/times.h
index 3c8a4ef..25d03e3 100644
--- a/libc/include/sys/times.h
+++ b/libc/include/sys/times.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_TIMES_H_
-#define _SYS_TIMES_H_
+#pragma once
+
+/**
+ * @file sys/times.h
+ * @brief The times() function.
+ */
#include <sys/cdefs.h>
#include <sys/types.h>
@@ -35,8 +39,13 @@
__BEGIN_DECLS
+/**
+ * [times(2)](http://man7.org/linux/man-pages/man2/times.2.html) fills a buffer with the
+ * calling process' CPU usage.
+ *
+ * Returns a (possibly overflowed) absolute time on success,
+ * and returns -1 and sets `errno` on failure.
+ */
clock_t times(struct tms* __buf);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/timex.h b/libc/include/sys/timex.h
index 74c8611..52db5dc 100644
--- a/libc/include/sys/timex.h
+++ b/libc/include/sys/timex.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_TIMEX_H_
-#define _SYS_TIMEX_H_
+#pragma once
+
+/**
+ * @file sys/timex.h
+ * @brief Kernel clock tuning.
+ */
#include <sys/cdefs.h>
#include <sys/types.h>
@@ -35,9 +39,22 @@
__BEGIN_DECLS
+/**
+ * [adjtimex(2)](http://man7.org/linux/man-pages/man2/adjtimex.2.html) adjusts the kernel clock.
+ *
+ * Returns the clock state on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 24.
+ */
int adjtimex(struct timex* __buf) __INTRODUCED_IN(24);
+
+/**
+ * clock_adjtime adjusts a specific kernel clock.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 24.
+ */
int clock_adjtime(clockid_t __clock, struct timex* __tx) __INTRODUCED_IN(24);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/un.h b/libc/include/sys/un.h
index 03ef5e4..83c1d17 100644
--- a/libc/include/sys/un.h
+++ b/libc/include/sys/un.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_UN_H_
-#define _SYS_UN_H_
+#pragma once
+
+/**
+ * @file sys/un.h
+ * @brief Unix domain sockets.
+ */
#include <bits/sa_family_t.h>
#include <linux/un.h>
@@ -35,7 +39,6 @@
#if defined(__USE_BSD) || defined(__USE_GNU)
#include <string.h>
+/** Returns the actual length of the given `sockaddr_un`. */
#define SUN_LEN(__ptr) (offsetof(struct sockaddr_un, sun_path) + strlen((__ptr)->sun_path))
#endif
-
-#endif
diff --git a/libc/include/sys/utsname.h b/libc/include/sys/utsname.h
index 2420fb4..1fa3187 100644
--- a/libc/include/sys/utsname.h
+++ b/libc/include/sys/utsname.h
@@ -26,26 +26,42 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_UTSNAME_H_
-#define _SYS_UTSNAME_H_
+#pragma once
+
+/**
+ * @file sys/utsname.h
+ * @brief The uname() function.
+ */
#include <sys/cdefs.h>
__BEGIN_DECLS
+/** The maximum length of any field in `struct utsname`. */
#define SYS_NMLN 65
+/** The information returned by uname(). */
struct utsname {
+ /** The OS name. "Linux" on Android. */
char sysname[SYS_NMLN];
+ /** The name on the network. Typically "localhost" on Android. */
char nodename[SYS_NMLN];
+ /** The OS release. Typically something like "4.4.115-g442ad7fba0d" on Android. */
char release[SYS_NMLN];
+ /** The OS version. Typically something like "#1 SMP PREEMPT" on Android. */
char version[SYS_NMLN];
+ /** The hardware architecture. Typically "aarch64" on Android. */
char machine[SYS_NMLN];
+ /** The domain name set by setdomainname(). Typically "localdomain" on Android. */
char domainname[SYS_NMLN];
};
+/**
+ * [uname(2)](http://man7.org/linux/man-pages/man2/uname.2.html) returns information
+ * about the kernel.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ */
int uname(struct utsname* __buf);
__END_DECLS
-
-#endif