Start documenting libc.
Bug: N/A
Test: N/A
Change-Id: I17345cb72a5ffc3af1688cf5874589cfb1e1fea0
diff --git a/libc/include/alloca.h b/libc/include/alloca.h
index 0508d31..e05dea6 100644
--- a/libc/include/alloca.h
+++ b/libc/include/alloca.h
@@ -26,12 +26,21 @@
* SUCH DAMAGE.
*/
-#ifndef _ALLOCA_H
-#define _ALLOCA_H
+#pragma once
+
+/**
+ * @file alloca.h
+ * @brief Allocate space on the stack.
+ */
#include <sys/cdefs.h>
+/**
+ * [alloca(3)](http://man7.org/linux/man-pages/man3/alloca.3.html) allocates space on the stack.
+ *
+ * New code should not use alloca because it cannot report failure.
+ * Use regular heap allocation instead.
+ *
+ * @return a pointer to the space on success, but has undefined behavior on failure.
+ */
#define alloca(size) __builtin_alloca(size)
-
-#endif /* _ALLOCA_H */
-
diff --git a/libc/include/android/dlext.h b/libc/include/android/dlext.h
index d0200c4..431e5ce 100644
--- a/libc/include/android/dlext.h
+++ b/libc/include/android/dlext.h
@@ -178,6 +178,8 @@
* Opens the given library. The `__filename` and `__flags` arguments are
* the same as for [dlopen(3)](http://man7.org/linux/man-pages/man3/dlopen.3.html),
* with the Android-specific flags supplied via the `flags` member of `__info`.
+ *
+ * Available since API level 21.
*/
void* android_dlopen_ext(const char* __filename, int __flags, const android_dlextinfo* __info)
__INTRODUCED_IN(21);
diff --git a/libc/include/ar.h b/libc/include/ar.h
index 413f767..e79fa49 100644
--- a/libc/include/ar.h
+++ b/libc/include/ar.h
@@ -1,6 +1,3 @@
-/* $OpenBSD: ar.h,v 1.3 2003/06/02 19:34:12 millert Exp $ */
-/* $NetBSD: ar.h,v 1.4 1994/10/26 00:55:43 cgd Exp $ */
-
/*-
* Copyright (c) 1991, 1993
* The Regents of the University of California. All rights reserved.
@@ -40,29 +37,36 @@
* @(#)ar.h 8.2 (Berkeley) 1/21/94
*/
-#ifndef _AR_H_
-#define _AR_H_
+#pragma once
+
+/**
+ * @file ar.h
+ * @brief Constants for reading/writing `.a` files.
+ */
#include <sys/cdefs.h>
-/* Pre-4BSD archives had these magic numbers in them. */
-#define OARMAG1 0177555
-#define OARMAG2 0177545
+/** The magic at the beginning of a `.a` file. */
+#define ARMAG "!<arch>\n"
+/** The length of the magic at the beginning of a `.a` file. */
+#define SARMAG 8
-#define ARMAG "!<arch>\n" /* ar "magic number" */
-#define SARMAG 8 /* strlen(ARMAG); */
-
-#define AR_EFMT1 "#1/" /* extended format #1 */
+/** The contents of every `ar_hdr::ar_fmag` field.*/
+#define ARFMAG "`\n"
struct ar_hdr {
- char ar_name[16]; /* name */
- char ar_date[12]; /* modification time */
- char ar_uid[6]; /* user id */
- char ar_gid[6]; /* group id */
- char ar_mode[8]; /* octal file permissions */
- char ar_size[10]; /* size in bytes */
-#define ARFMAG "`\n"
- char ar_fmag[2]; /* consistency check */
+ /* Name. */
+ char ar_name[16];
+ /* Modification time. */
+ char ar_date[12];
+ /** User id. */
+ char ar_uid[6];
+ /** Group id. */
+ char ar_gid[6];
+ /** Octal file permissions. */
+ char ar_mode[8];
+ /** Size in bytes. */
+ char ar_size[10];
+ /** Consistency check. Always contains `ARFMAG`. */
+ char ar_fmag[2];
};
-
-#endif /* !_AR_H_ */
diff --git a/libc/include/assert.h b/libc/include/assert.h
index 7a9d84d..79e7b86 100644
--- a/libc/include/assert.h
+++ b/libc/include/assert.h
@@ -32,7 +32,10 @@
* SUCH DAMAGE.
*/
-/*
+/**
+ * @file assert.h
+ * @brief Assertions.
+ *
* There's no include guard in this file because <assert.h> may usefully be
* included multiple times, with and without NDEBUG defined.
*/
@@ -42,6 +45,7 @@
#undef assert
#undef __assert_no_op
+/** Internal implementation detail. Do not use. */
#define __assert_no_op __BIONIC_CAST(static_cast, void, 0)
#ifdef NDEBUG
@@ -50,6 +54,12 @@
# if defined(__cplusplus) || __STDC_VERSION__ >= 199901L
# define assert(e) ((e) ? __assert_no_op : __assert2(__FILE__, __LINE__, __PRETTY_FUNCTION__, #e))
# else
+/**
+ * assert() aborts the program after logging an error message, if the
+ * expression evaluates to false.
+ *
+ * On Android, the error goes to both stderr and logcat.
+ */
# define assert(e) ((e) ? __assert_no_op : __assert(__FILE__, __LINE__, #e))
# endif
#endif
@@ -60,6 +70,17 @@
#endif
__BEGIN_DECLS
+
+/**
+ * __assert() is called by assert() on failure. Most users want assert()
+ * instead, but this can be useful for reporting other failures.
+ */
void __assert(const char* __file, int __line, const char* __msg) __noreturn;
+
+/**
+ * __assert2() is called by assert() on failure. Most users want assert()
+ * instead, but this can be useful for reporting other failures.
+ */
void __assert2(const char* __file, int __line, const char* __function, const char* __msg) __noreturn;
+
__END_DECLS
diff --git a/libc/include/byteswap.h b/libc/include/byteswap.h
index 0838e6c..0773426 100644
--- a/libc/include/byteswap.h
+++ b/libc/include/byteswap.h
@@ -26,14 +26,30 @@
* SUCH DAMAGE.
*/
-#ifndef _BYTESWAP_H_
-#define _BYTESWAP_H_
+#pragma once
+
+/**
+ * @file byteswap.h
+ * @brief Byte-swapping macros.
+ */
#include <sys/cdefs.h>
#include <sys/endian.h>
+/**
+ * [bswap_16(3)](http://man7.org/linux/man-pages/man3/bswap_16.3.html) swaps the bytes in a
+ * 16-bit value.
+ */
#define bswap_16(x) __swap16(x)
-#define bswap_32(x) __swap32(x)
-#define bswap_64(x) __swap64(x)
-#endif /* _BYTESWAP_H_ */
+/**
+ * [bswap_32(3)](http://man7.org/linux/man-pages/man3/bswap_32.3.html) swaps the bytes in a
+ * 32-bit value.
+ */
+#define bswap_32(x) __swap32(x)
+
+/**
+ * [bswap_64(3)](http://man7.org/linux/man-pages/man3/bswap_64.3.html) swaps the bytes in a
+ * 64-bit value.
+ */
+#define bswap_64(x) __swap64(x)
diff --git a/libc/include/cpio.h b/libc/include/cpio.h
index ceeeb87..c2c20c2 100644
--- a/libc/include/cpio.h
+++ b/libc/include/cpio.h
@@ -26,32 +26,55 @@
* SUCH DAMAGE.
*/
-#ifndef _CPIO_H_
-#define _CPIO_H_
+#pragma once
+
+/**
+ * @file cpio.h
+ * @brief Constants for reading/writing cpio files.
+ */
#include <sys/cdefs.h>
+/** Readable by user mode field bit. */
#define C_IRUSR 0000400
+/** Writable by user mode field bit. */
#define C_IWUSR 0000200
+/** Executable by user mode field bit. */
#define C_IXUSR 0000100
+/** Readable by group mode field bit. */
#define C_IRGRP 0000040
+/** Writable by group mode field bit. */
#define C_IWGRP 0000020
+/** Executable by group mode field bit. */
#define C_IXGRP 0000010
+/** Readable by other mode field bit. */
#define C_IROTH 0000004
+/** Writable by other mode field bit. */
#define C_IWOTH 0000002
+/** Executable by other mode field bit. */
#define C_IXOTH 0000001
+/** Set-UID mode field bit. */
#define C_ISUID 0004000
+/** Set-GID mode field bit. */
#define C_ISGID 0002000
+/** Directory restricted deletion mode field bit. */
#define C_ISVTX 0001000
+/** Directory mode field type. */
#define C_ISDIR 0040000
+/** FIFO mode field type. */
#define C_ISFIFO 0010000
+/** Regular file mode field type. */
#define C_ISREG 0100000
+/** Block special file mode field type. */
#define C_ISBLK 0060000
+/** Character special file mode field type. */
#define C_ISCHR 0020000
+/** Reserved. */
#define C_ISCTG 0110000
+/** Symbolic link mode field type. */
#define C_ISLNK 0120000
+/** Socket mode field type. */
#define C_ISSOCK 0140000
+/** cpio file magic. */
#define MAGIC "070707"
-
-#endif /* _CPIO_H_ */
diff --git a/libc/include/endian.h b/libc/include/endian.h
index 65e2930..ed237b9 100644
--- a/libc/include/endian.h
+++ b/libc/include/endian.h
@@ -1 +1,10 @@
+#pragma once
+
+/*
+ * @file endian.h
+ * @brief Historical alternative to `<sys/endian.h>`.
+ *
+ * New code should use `<sys/endian.h>` directly.
+ */
+
#include <sys/endian.h>
diff --git a/libc/include/err.h b/libc/include/err.h
index a64d01d..e91dac9 100644
--- a/libc/include/err.h
+++ b/libc/include/err.h
@@ -1,6 +1,3 @@
-/* $OpenBSD: err.h,v 1.10 2006/01/06 18:53:04 millert Exp $ */
-/* $NetBSD: err.h,v 1.11 1994/10/26 00:55:52 cgd Exp $ */
-
/*-
* Copyright (c) 1993
* The Regents of the University of California. All rights reserved.
@@ -32,8 +29,12 @@
* @(#)err.h 8.1 (Berkeley) 6/2/93
*/
-#ifndef _ERR_H_
-#define _ERR_H_
+#pragma once
+
+/**
+ * @file err.h
+ * @brief BSD error reporting functions. See `<error.h>` for the GNU equivalent.
+ */
#include <stdarg.h>
#include <sys/cdefs.h>
@@ -41,15 +42,76 @@
__BEGIN_DECLS
+/**
+ * [err(3)](http://man7.org/linux/man-pages/man3/err.3.html) outputs the program name,
+ * the printf()-like formatted message, and the result of strerror() if `errno` is non-zero.
+ *
+ * Calls exit() with `__status`.
+ *
+ * New code should consider error() in `<error.h>`.
+ */
__noreturn void err(int __status, const char* __fmt, ...) __printflike(2, 3);
+
+/**
+ * [verr(3)](http://man7.org/linux/man-pages/man3/verr.3.html) outputs the program name,
+ * the vprintf()-like formatted message, and the result of strerror() if `errno` is non-zero.
+ *
+ * Calls exit() with `__status`.
+ *
+ * New code should consider error() in `<error.h>`.
+ */
__noreturn void verr(int __status, const char* __fmt, va_list __args) __printflike(2, 0);
+
+/**
+ * [errx(3)](http://man7.org/linux/man-pages/man3/errx.3.html) outputs the program name, and
+ * the printf()-like formatted message.
+ *
+ * Calls exit() with `__status`.
+ *
+ * New code should consider error() in `<error.h>`.
+ */
__noreturn void errx(int __status, const char* __fmt, ...) __printflike(2, 3);
+
+/**
+ * [verrx(3)](http://man7.org/linux/man-pages/man3/err.3.html) outputs the program name, and
+ * the vprintf()-like formatted message.
+ *
+ * Calls exit() with `__status`.
+ *
+ * New code should consider error() in `<error.h>`.
+ */
__noreturn void verrx(int __status, const char* __fmt, va_list __args) __printflike(2, 0);
+
+/**
+ * [warn(3)](http://man7.org/linux/man-pages/man3/warn.3.html) outputs the program name,
+ * the printf()-like formatted message, and the result of strerror() if `errno` is non-zero.
+ *
+ * New code should consider error() in `<error.h>`.
+ */
void warn(const char* __fmt, ...) __printflike(1, 2);
+
+/**
+ * [vwarn(3)](http://man7.org/linux/man-pages/man3/vwarn.3.html) outputs the program name,
+ * the vprintf()-like formatted message, and the result of strerror() if `errno` is non-zero.
+ *
+ * New code should consider error() in `<error.h>`.
+ */
void vwarn(const char* __fmt, va_list __args) __printflike(1, 0);
+
+/**
+ * [warnx(3)](http://man7.org/linux/man-pages/man3/warnx.3.html) outputs the program name, and
+ * the printf()-like formatted message.
+ *
+ * New code should consider error() in `<error.h>`.
+ */
void warnx(const char* __fmt, ...) __printflike(1, 2);
+
+/**
+ * [vwarnx(3)](http://man7.org/linux/man-pages/man3/warn.3.html) outputs the program name, and
+ * the vprintf()-like formatted message.
+ *
+ * New code should consider error() in `<error.h>`.
+ */
void vwarnx(const char* __fmt, va_list __args) __printflike(1, 0);
__END_DECLS
-
-#endif /* !_ERR_H_ */
diff --git a/libc/include/errno.h b/libc/include/errno.h
index cbe67fa..b6a4c7e 100644
--- a/libc/include/errno.h
+++ b/libc/include/errno.h
@@ -26,24 +26,37 @@
* SUCH DAMAGE.
*/
-#ifndef _ERRNO_H
-#define _ERRNO_H
+#pragma once
+
+/**
+ * @file errno.h
+ * @brief Standard C error handling.
+ */
#include <sys/cdefs.h>
#include <linux/errno.h>
__BEGIN_DECLS
-/* On Linux, ENOTSUP and EOPNOTSUPP are the same despite POSIX saying they should be distinct. */
#ifndef ENOTSUP
+/** On Linux, ENOTSUP and EOPNOTSUPP are the same despite POSIX saying they should be distinct. */
#define ENOTSUP EOPNOTSUPP
#endif
+/**
+ * Returns the address of the calling thread's `errno` storage.
+ * Non-portable and should not be used directly. Use `errno` instead.
+ *
+ * @private
+ */
int* __errno(void) __attribute_const__;
+
+/**
+ * [errno(3)](http://man7.org/linux/man-pages/man3/errno.3.html) is the last error on the calling
+ * thread.
+ */
#define errno (*__errno())
__END_DECLS
#include <android/legacy_errno_inlines.h>
-
-#endif /* _ERRNO_H */
diff --git a/libc/include/error.h b/libc/include/error.h
index d612994..036a831 100644
--- a/libc/include/error.h
+++ b/libc/include/error.h
@@ -26,21 +26,60 @@
* SUCH DAMAGE.
*/
-#ifndef _ERROR_H
-#define _ERROR_H 1
+#pragma once
+
+/**
+ * @file error.h
+ * @brief GNU error reporting functions.
+ */
#include <sys/cdefs.h>
__BEGIN_DECLS
+/**
+ * [error_print_progname(3)](http://man7.org/linux/man-pages/man3/error_print_progname.3.html) is
+ * a function pointer that, if non-null, is called by error() instead of prefixing errors with the
+ * program name.
+ *
+ * Available since API level 23.
+ */
extern void (*error_print_progname)(void) __INTRODUCED_IN(23);
+
+/**
+ * [error_message_count(3)](http://man7.org/linux/man-pages/man3/error_message_count.3.html) is
+ * a global count of the number of calls to error() and error_at_line().
+ *
+ * Available since API level 23.
+ */
extern unsigned int error_message_count __INTRODUCED_IN(23);
+
+/**
+ * [error_one_per_line(3)](http://man7.org/linux/man-pages/man3/error_one_per_line.3.html) is
+ * a global flag that if non-zero disables printing multiple errors with the same filename and
+ * line number.
+ *
+ * Available since API level 23.
+ */
extern int error_one_per_line __INTRODUCED_IN(23);
+/**
+ * [error(3)](http://man7.org/linux/man-pages/man3/error.3.html) formats the given printf()-like
+ * error message, preceded by the program name. Calls exit if `__status` is non-zero, and appends
+ * the result of strerror() if `__errno` is non-zero.
+ *
+ * Available since API level 23.
+ */
void error(int __status, int __errno, const char* __fmt, ...) __printflike(3, 4) __INTRODUCED_IN(23);
-void error_at_line(int __status, int __errno, const char* __filename, unsigned int __line_number, const char* __fmt, ...)
- __printflike(5, 6) __INTRODUCED_IN(23);
+
+/**
+ * [error_at_line(3)](http://man7.org/linux/man-pages/man3/error_at_line.3.html) formats the given
+ * printf()-like error message, preceded by the program name and the given filename and line number.
+ * Calls exit if `__status` is non-zero, and appends the result of strerror() if `__errno` is
+ * non-zero.
+ *
+ * Available since API level 23.
+ */
+void error_at_line(int __status, int __errno, const char* __filename, unsigned int __line_number, const char* __fmt, ...) __printflike(5, 6) __INTRODUCED_IN(23);
__END_DECLS
-
-#endif
diff --git a/libc/include/features.h b/libc/include/features.h
index a279c7f..a915fe7 100644
--- a/libc/include/features.h
+++ b/libc/include/features.h
@@ -26,10 +26,11 @@
* SUCH DAMAGE.
*/
-#ifndef _FEATURES_H_
-#define _FEATURES_H_
+#pragma once
-/* Our <features.h> macro fun is all in <sys/cdefs.h>. */
+/**
+ * @file features.h
+ * @brief Synonym for `<sys/cdefs.h>` for source compatibility with glibc.
+ */
+
#include <sys/cdefs.h>
-
-#endif /* _FEATURES_H_ */
diff --git a/libc/include/fnmatch.h b/libc/include/fnmatch.h
index 3fcc665..1788a27 100644
--- a/libc/include/fnmatch.h
+++ b/libc/include/fnmatch.h
@@ -26,27 +26,45 @@
* SUCH DAMAGE.
*/
-#ifndef _FNMATCH_H
-#define _FNMATCH_H
+#pragma once
+
+/**
+ * @file fnmatch.h
+ * @brief Filename matching.
+ */
#include <sys/cdefs.h>
__BEGIN_DECLS
-#define FNM_NOMATCH 1 /* Match failed. */
-#define FNM_NOSYS 2 /* Function not supported (unused). */
+/** Returned by fnmatch() if matching failed. */
+#define FNM_NOMATCH 1
-#define FNM_NOESCAPE 0x01 /* Disable backslash escaping. */
-#define FNM_PATHNAME 0x02 /* Slash must be matched by slash. */
-#define FNM_PERIOD 0x04 /* Period must be matched by period. */
-#define FNM_LEADING_DIR 0x08 /* Ignore /<tail> after Imatch. */
-#define FNM_CASEFOLD 0x10 /* Case insensitive search. */
+/** Returned by fnmatch() if the function is not supported. This is never returned on Android. */
+#define FNM_NOSYS 2
+/** fnmatch() flag to disable backslash escaping. */
+#define FNM_NOESCAPE 0x01
+/** fnmatch() flag to ensure that slashes must be matched by slashes. */
+#define FNM_PATHNAME 0x02
+/** fnmatch() flag to ensure that periods must be matched by periods. */
+#define FNM_PERIOD 0x04
+/** fnmatch() flag to ignore /... after a match. */
+#define FNM_LEADING_DIR 0x08
+/** fnmatch() flag for a case-insensitive search. */
+#define FNM_CASEFOLD 0x10
+
+/** Synonym for `FNM_CASEFOLD`: case-insensitive search. */
#define FNM_IGNORECASE FNM_CASEFOLD
+/** Synonym for `FNM_PATHNAME`: slashes must be matched by slashes. */
#define FNM_FILE_NAME FNM_PATHNAME
-int fnmatch(const char* __pattern, const char* __string, int __flags);
+/**
+ * [fnmatch(3)](http://man7.org/linux/man-pages/man3/fnmatch.3.html) matches `__string` against
+ * the shell wildcard `__pattern`.
+ *
+ * Returns 0 on success, and returns `FNM_NOMATCH` on failure.
+ */
+int fnmatch(const char* _Nonnull __pattern, const char* _Nonnull __string, int __flags);
__END_DECLS
-
-#endif
diff --git a/libc/include/iconv.h b/libc/include/iconv.h
index df8fa6d..ec4bdea 100644
--- a/libc/include/iconv.h
+++ b/libc/include/iconv.h
@@ -26,21 +26,58 @@
* SUCH DAMAGE.
*/
-#ifndef _ICONV_H_
-#define _ICONV_H_
+#pragma once
+
+/**
+ * @file iconv.h
+ * @brief Character encoding conversion.
+ */
#include <sys/cdefs.h>
#include <sys/types.h>
__BEGIN_DECLS
+/* If we just use void* in the typedef, the compiler exposes that in error messages. */
struct __iconv_t;
+
+/**
+ * The `iconv_t` type that represents an instance of a converter.
+ */
typedef struct __iconv_t* iconv_t;
+/**
+ * [iconv_open(3)](http://man7.org/linux/man-pages/man3/iconv_open.3.html) allocates a new converter
+ * from `__src_encoding` to `__dst_encoding`.
+ *
+ * Returns a new `iconv_t` on success and returns `((iconv_t) -1)` and sets `errno` on failure.
+ *
+ * Available since API level 28.
+ */
iconv_t iconv_open(const char* __src_encoding, const char* __dst_encoding) __INTRODUCED_IN(28);
+
+/**
+ * [iconv(3)](http://man7.org/linux/man-pages/man3/iconv.3.html) converts characters from one
+ * encoding to another.
+ *
+ * Android supports the `utf8`, `ascii`, `usascii`, `utf16be`, `utf16le`, `utf32be`, `utf32le`,
+ * and `wchart` encodings. Android also supports the GNU `//IGNORE` and `//TRANSLIT` extensions.
+ *
+ * Returns the number of characters converted on success and returns `((size_t) -1)` and
+ * sets `errno` on failure.
+ *
+ * Available since API level 28.
+ */
size_t iconv(iconv_t __converter, char** __src_buf, size_t* __src_bytes_left, char** __dst_buf, size_t* __dst_bytes_left) __INTRODUCED_IN(28);
+
+/**
+ * [iconv_close(3)](http://man7.org/linux/man-pages/man3/iconv_close.3.html) deallocates a converter
+ * returned by iconv_open().
+ *
+ * Returns 0 on success and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 28.
+ */
int iconv_close(iconv_t __converter) __INTRODUCED_IN(28);
__END_DECLS
-
-#endif
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
diff --git a/libc/include/lastlog.h b/libc/include/lastlog.h
index 4f46106..ef1b032 100644
--- a/libc/include/lastlog.h
+++ b/libc/include/lastlog.h
@@ -1,2 +1,10 @@
-/* This is a BSD synonym for <utmp.h> that's also provided by glibc. */
+#pragma once
+
+/**
+ * @file lastlog.h
+ * @brief Historical alternative to `<utmp.h>`.
+ *
+ * New code should use `<utmp.h>` directly.
+ */
+
#include <utmp.h>
diff --git a/libc/include/libgen.h b/libc/include/libgen.h
index 5fa9089..b910790 100644
--- a/libc/include/libgen.h
+++ b/libc/include/libgen.h
@@ -26,34 +26,52 @@
* SUCH DAMAGE.
*/
-#ifndef _LIBGEN_H
-#define _LIBGEN_H
+#pragma once
+
+/**
+ * @file libgen.h
+ * @brief POSIX basename() and dirname().
+ *
+ * This file contains the POSIX basename() and dirname(). See `<string.h>` for the GNU basename().
+ */
#include <sys/cdefs.h>
#include <sys/types.h>
__BEGIN_DECLS
-/*
- * Including <string.h> will get you the GNU basename, unless <libgen.h> is
- * included, either before or after including <string.h>.
+/**
+ * [basename(3)](http://man7.org/linux/man-pages/man3/basename.3.html)
+ * returns the final component of the given path.
*
- * Note that this has the wrong argument cv-qualifiers, but doesn't modify its
- * input and uses thread-local storage for the result if necessary.
+ * See `<string.h>` for the GNU basename(). Including `<libgen.h>`,
+ * either before or after including <string.h>, will override the GNU variant.
+ *
+ * Note that Android's cv-qualifiers differ from POSIX; Android's implementation doesn't
+ * modify its input and uses thread-local storage for the result if necessary.
*/
char* __posix_basename(const char* __path) __RENAME(basename);
+/**
+ * This macro ensures that callers get the POSIX basename() if they include this header,
+ * no matter what order `<libgen.h>` and `<string.h>` are included in.
+ */
#define basename __posix_basename
-/* This has the wrong argument cv-qualifiers, but doesn't modify its input and uses thread-local storage for the result if necessary. */
+/**
+ * [dirname(3)](http://man7.org/linux/man-pages/man3/dirname.3.html)
+ * returns all but the final component of the given path.
+ *
+ * Note that Android's cv-qualifiers differ from POSIX; Android's implementation doesn't
+ * modify its input and uses thread-local storage for the result if necessary.
+ */
char* dirname(const char* __path);
#if !defined(__LP64__)
-/* These non-standard functions are not needed on Android; basename and dirname use thread-local storage. */
+/** Deprecated. Use dirname() instead. */
int dirname_r(const char* __path, char* __buf, size_t __n);
+/** Deprecated. Use basename() instead. */
int basename_r(const char* __path, char* __buf, size_t __n);
#endif
__END_DECLS
-
-#endif
diff --git a/libc/include/malloc.h b/libc/include/malloc.h
index f7adfbb..7144224 100644
--- a/libc/include/malloc.h
+++ b/libc/include/malloc.h
@@ -14,8 +14,16 @@
* limitations under the License.
*/
-#ifndef LIBC_INCLUDE_MALLOC_H_
-#define LIBC_INCLUDE_MALLOC_H_
+#pragma once
+
+/**
+ * @file malloc.h
+ * @brief Heap memory allocation.
+ *
+ * [Debugging Native Memory Use](https://source.android.com/devices/tech/debug/native-memory)
+ * is the canonical source for documentation on Android's heap debugging
+ * features.
+ */
#include <sys/cdefs.h>
#include <stddef.h>
@@ -30,35 +38,96 @@
#define __BIONIC_ALLOC_SIZE(...) __attribute__((__alloc_size__(__VA_ARGS__)))
#endif
+/**
+ * [malloc(3)](http://man7.org/linux/man-pages/man3/malloc.3.html) allocates
+ * memory on the heap.
+ *
+ * Returns a pointer to the allocated memory on success and returns a null
+ * pointer and sets `errno` on failure.
+ */
void* malloc(size_t __byte_count) __mallocfunc __BIONIC_ALLOC_SIZE(1) __wur;
+
+/**
+ * [calloc(3)](http://man7.org/linux/man-pages/man3/calloc.3.html) allocates
+ * and clears memory on the heap.
+ *
+ * Returns a pointer to the allocated memory on success and returns a null
+ * pointer and sets `errno` on failure.
+ */
void* calloc(size_t __item_count, size_t __item_size) __mallocfunc __BIONIC_ALLOC_SIZE(1,2) __wur;
+
+/**
+ * [realloc(3)](http://man7.org/linux/man-pages/man3/realloc.3.html) resizes
+ * allocated memory on the heap.
+ *
+ * Returns a pointer (which may be different from `__ptr`) to the resized
+ * memory on success and returns a null pointer and sets `errno` on failure.
+ */
void* realloc(void* __ptr, size_t __byte_count) __BIONIC_ALLOC_SIZE(2) __wur;
+
+/**
+ * [free(3)](http://man7.org/linux/man-pages/man3/free.3.html) deallocates
+ * memory on the heap.
+ */
void free(void* __ptr);
+/**
+ * [memalign(3)](http://man7.org/linux/man-pages/man3/memalign.3.html) allocates
+ * memory on the heap with the required alignment.
+ *
+ * Returns a pointer to the allocated memory on success and returns a null
+ * pointer and sets `errno` on failure.
+ *
+ * See also posix_memalign().
+ */
void* memalign(size_t __alignment, size_t __byte_count) __mallocfunc __BIONIC_ALLOC_SIZE(2) __wur;
+
+/**
+ * [malloc_usable_size(3)](http://man7.org/linux/man-pages/man3/malloc_usable_size.3.html)
+ * returns the actual size of the given heap block.
+ *
+ * Available since API level 17.
+ */
size_t malloc_usable_size(const void* __ptr) __INTRODUCED_IN(17);
#ifndef STRUCT_MALLINFO_DECLARED
#define STRUCT_MALLINFO_DECLARED 1
struct mallinfo {
- size_t arena; /* Total number of non-mmapped bytes currently allocated from OS. */
- size_t ordblks; /* Number of free chunks. */
- size_t smblks; /* (Unused.) */
- size_t hblks; /* (Unused.) */
- size_t hblkhd; /* Total number of bytes in mmapped regions. */
- size_t usmblks; /* Maximum total allocated space; greater than total if trimming has occurred. */
- size_t fsmblks; /* (Unused.) */
- size_t uordblks; /* Total allocated space (normal or mmapped.) */
- size_t fordblks; /* Total free space. */
- size_t keepcost; /* Upper bound on number of bytes releasable by malloc_trim. */
+ /** Total number of non-mmapped bytes currently allocated from OS. */
+ size_t arena;
+ /** Number of free chunks. */
+ size_t ordblks;
+ /** (Unused.) */
+ size_t smblks;
+ /** (Unused.) */
+ size_t hblks;
+ /** Total number of bytes in mmapped regions. */
+ size_t hblkhd;
+ /** Maximum total allocated space; greater than total if trimming has occurred. */
+ size_t usmblks;
+ /** (Unused.) */
+ size_t fsmblks;
+ /** Total allocated space (normal or mmapped.) */
+ size_t uordblks;
+ /** Total free space. */
+ size_t fordblks;
+ /** Upper bound on number of bytes releasable by a trim operation. */
+ size_t keepcost;
};
-#endif /* STRUCT_MALLINFO_DECLARED */
+#endif
+/**
+ * [mallinfo(3)](http://man7.org/linux/man-pages/man3/mallinfo.3.html) returns
+ * information about the current state of the heap.
+ */
struct mallinfo mallinfo(void);
-/*
- * XML structure for malloc_info(3) is in the following format:
+/**
+ * [malloc_info(3)](http://man7.org/linux/man-pages/man3/malloc_info.3.html)
+ * writes information about the current state of the heap to the given stream.
*
+ * The XML structure for malloc_info() is as follows:
+ * ```
* <malloc version="jemalloc-1">
* <heap nr="INT">
* <allocated-large>INT</allocated-large>
@@ -74,21 +143,67 @@
* </heap>
* <!-- more heaps -->
* </malloc>
+ * ```
+ *
+ * Available since API level 23.
*/
int malloc_info(int __must_be_zero, FILE* __fp) __INTRODUCED_IN(23);
-/* mallopt options */
+/** mallopt() option to set the decay time. Valid values are 0 and 1. */
#define M_DECAY_TIME -100
+
+/**
+ * [mallopt(3)](http://man7.org/linux/man-pages/man3/mallopt.3.html) modifies
+ * heap behavior. Values of `__option` are the `M_` constants from this header.
+ *
+ * Returns 1 on success, 0 on error.
+ *
+ * Available since API level 26.
+ */
int mallopt(int __option, int __value) __INTRODUCED_IN(26);
-/*
- * Memory Allocation Hooks
+/**
+ * [__malloc_hook(3)](http://man7.org/linux/man-pages/man3/__malloc_hook.3.html)
+ * is called to implement malloc(). By default this points to the system's
+ * implementation.
+ *
+ * Available since API level 28.
+ *
+ * See also: [extra documentation](https://android.googlesource.com/platform/bionic/+/master/libc/malloc_hooks/README.md)
*/
-extern void* (*volatile __malloc_hook)(size_t, const void*) __INTRODUCED_IN(28);
-extern void* (*volatile __realloc_hook)(void*, size_t, const void*) __INTRODUCED_IN(28);
-extern void (*volatile __free_hook)(void*, const void*) __INTRODUCED_IN(28);
-extern void* (*volatile __memalign_hook)(size_t, size_t, const void*) __INTRODUCED_IN(28);
+extern void* (*volatile __malloc_hook)(size_t __byte_count, const void* __caller) __INTRODUCED_IN(28);
+
+/**
+ * [__realloc_hook(3)](http://man7.org/linux/man-pages/man3/__realloc_hook.3.html)
+ * is called to implement realloc(). By default this points to the system's
+ * implementation.
+ *
+ * Available since API level 28.
+ *
+ * See also: [extra documentation](https://android.googlesource.com/platform/bionic/+/master/libc/malloc_hooks/README.md)
+ */
+extern void* (*volatile __realloc_hook)(void* __ptr, size_t __byte_count, const void* __caller) __INTRODUCED_IN(28);
+
+/**
+ * [__free_hook(3)](http://man7.org/linux/man-pages/man3/__free_hook.3.html)
+ * is called to implement free(). By default this points to the system's
+ * implementation.
+ *
+ * Available since API level 28.
+ *
+ * See also: [extra documentation](https://android.googlesource.com/platform/bionic/+/master/libc/malloc_hooks/README.md)
+ */
+extern void (*volatile __free_hook)(void* __ptr, const void* __caller) __INTRODUCED_IN(28);
+
+/**
+ * [__memalign_hook(3)](http://man7.org/linux/man-pages/man3/__memalign_hook.3.html)
+ * is called to implement memalign(). By default this points to the system's
+ * implementation.
+ *
+ * Available since API level 28.
+ *
+ * See also: [extra documentation](https://android.googlesource.com/platform/bionic/+/master/libc/malloc_hooks/README.md)
+ */
+extern void* (*volatile __memalign_hook)(size_t __alignment, size_t __byte_count, const void* __caller) __INTRODUCED_IN(28);
__END_DECLS
-
-#endif /* LIBC_INCLUDE_MALLOC_H_ */
diff --git a/libc/include/memory.h b/libc/include/memory.h
index 3b2f590..c2baef6 100644
--- a/libc/include/memory.h
+++ b/libc/include/memory.h
@@ -1 +1,10 @@
+#pragma once
+
+/**
+ * @file memory.h
+ * @brief Historical alternative to `<string.h>`.
+ *
+ * New code should use `<string.h>` directly.
+ */
+
#include <string.h>
diff --git a/libc/include/nl_types.h b/libc/include/nl_types.h
index b25b7a3..622880a 100644
--- a/libc/include/nl_types.h
+++ b/libc/include/nl_types.h
@@ -26,23 +26,59 @@
* SUCH DAMAGE.
*/
-#ifndef _NL_TYPES_H_
-#define _NL_TYPES_H_
+#pragma once
+
+/**
+ * @file nl_types.h
+ * @brief Message catalogs.
+ *
+ * Android offers a dummy implementation of these functions to ease porting of historical software.
+ */
#include <sys/cdefs.h>
__BEGIN_DECLS
+/**
+ * catopen() flag to use the current locale.
+ */
#define NL_CAT_LOCALE 1
+
+/**
+ * catgets() default set number.
+ */
#define NL_SETD 1
+/** Message catalog type. */
typedef void* nl_catd;
+
+/** The type of the constants in `<langinfo.h>`, used by nl_langinfo(). */
typedef int nl_item;
+/**
+ * [catopen(3)](http://man7.org/linux/man-pages/man3/catopen.3.html) opens a message catalog.
+ *
+ * On Android, this always returns failure: `((nl_catd) -1)`.
+ *
+ * Available since API level 28.
+ */
nl_catd catopen(const char* __name, int __flag) __INTRODUCED_IN(26);
+
+/**
+ * [catgets(3)](http://man7.org/linux/man-pages/man3/catgets.3.html) translates the given message
+ * using the given message catalog.
+ *
+ * On Android, this always returns `__msg`.
+ *
+ * Available since API level 28.
+ */
char* catgets(nl_catd __catalog, int __set_number, int __msg_number, const char* __msg) __INTRODUCED_IN(26);
+
+/**
+ * [catclose(3)](http://man7.org/linux/man-pages/man3/catclose.3.html) closes a message catalog.
+ *
+ * On Android, this always returns -1 with `errno` set to `EBADF`.
+ */
int catclose(nl_catd __catalog) __INTRODUCED_IN(26);
__END_DECLS
-
-#endif
diff --git a/libc/include/paths.h b/libc/include/paths.h
index 922d1ce..dc1c523 100644
--- a/libc/include/paths.h
+++ b/libc/include/paths.h
@@ -29,20 +29,37 @@
* @(#)paths.h 8.1 (Berkeley) 6/2/93
*/
-#ifndef _PATHS_H_
-#define _PATHS_H_
+#pragma once
+
+/**
+ * @file paths.h
+ * @brief Default paths.
+ */
#include <sys/cdefs.h>
#ifndef _PATH_BSHELL
-#define _PATH_BSHELL "/system/bin/sh"
+/** Path to the default system shell. Historically the 'B' was to specify the Bourne shell. */
+#define _PATH_BSHELL "/system/bin/sh"
#endif
-#define _PATH_CONSOLE "/dev/console"
-#define _PATH_DEFPATH "/sbin:/system/sbin:/system/bin:/system/xbin:/odm/bin:/vendor/bin:/vendor/xbin"
-#define _PATH_DEV "/dev/"
-#define _PATH_DEVNULL "/dev/null"
-#define _PATH_KLOG "/proc/kmsg"
-#define _PATH_MOUNTED "/proc/mounts"
-#define _PATH_TTY "/dev/tty"
-#endif /* !_PATHS_H_ */
+/** Path to the system console. */
+#define _PATH_CONSOLE "/dev/console"
+
+/** Default shell search path. */
+#define _PATH_DEFPATH "/sbin:/system/sbin:/system/bin:/system/xbin:/odm/bin:/vendor/bin:/vendor/xbin"
+
+/** Path to the directory containing device files. */
+#define _PATH_DEV "/dev/"
+
+/** Path to `/dev/null`. */
+#define _PATH_DEVNULL "/dev/null"
+
+/** Path to the kernel log. */
+#define _PATH_KLOG "/proc/kmsg"
+
+/** Path to `/proc/mounts` for setmntent(). */
+#define _PATH_MOUNTED "/proc/mounts"
+
+/** Path to the calling process' tty. */
+#define _PATH_TTY "/dev/tty"
diff --git a/libc/include/poll.h b/libc/include/poll.h
index 6a8f757..13b7385 100644
--- a/libc/include/poll.h
+++ b/libc/include/poll.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _POLL_H_
-#define _POLL_H_
+#pragma once
+
+/**
+ * @file poll.h
+ * @brief Wait for events on a set of file descriptors.
+ */
#include <sys/cdefs.h>
#include <linux/poll.h>
@@ -36,16 +40,38 @@
__BEGIN_DECLS
+/** The type of a file descriptor count, used by poll() and ppoll(). */
typedef unsigned int nfds_t;
-int poll(struct pollfd* __fds, nfds_t __count, int __timeout_ms);
-int ppoll(struct pollfd* __fds, nfds_t __count, const struct timespec* __timeout, const sigset_t* __mask) __INTRODUCED_IN(21);
-int ppoll64(struct pollfd* __fds, nfds_t __count, const struct timespec* __timeout, const sigset64_t* __mask) __INTRODUCED_IN(28);
+/**
+ * [poll(3)](http://man7.org/linux/man-pages/man3/poll.3.html) waits on a set of file descriptors.
+ *
+ * Returns the number of ready file descriptors on success, 0 for timeout,
+ * and returns -1 and sets `errno` on failure.
+ */
+int poll(struct pollfd* _Nonnull __fds, nfds_t __count, int __timeout_ms);
+
+/**
+ * [ppoll(3)](http://man7.org/linux/man-pages/man3/ppoll.3.html) waits on a set of file descriptors
+ * or a signal. Set `__timeout` to null for no timeout. Set `__mask` to null to not set the signal
+ * mask.
+ *
+ * Returns the number of ready file descriptors on success, 0 for timeout,
+ * and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 28.
+ */
+int ppoll(struct pollfd* _Nonnull __fds, nfds_t __count, const struct timespec* _Nullable __timeout, const sigset_t* _Nullable __mask) __INTRODUCED_IN(21);
+
+/**
+ * Like ppoll() but allows setting a signal mask with RT signals even from a 32-bit process.
+ */
+int ppoll64(struct pollfd* _Nonnull __fds, nfds_t __count, const struct timespec* _Nullable __timeout, const sigset64_t* _Nullable __mask) __INTRODUCED_IN(28);
#if defined(__BIONIC_INCLUDE_FORTIFY_HEADERS)
+#define _POLL_H_
#include <bits/fortify/poll.h>
+#undef _POLL_H_
#endif
__END_DECLS
-
-#endif
diff --git a/libc/include/pty.h b/libc/include/pty.h
index cf9ccb9..90d6686 100644
--- a/libc/include/pty.h
+++ b/libc/include/pty.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _PTY_H
-#define _PTY_H
+#pragma once
+
+/**
+ * @file pty.h
+ * @brief Pseudoterminal functions.
+ */
#include <sys/cdefs.h>
@@ -36,9 +40,25 @@
__BEGIN_DECLS
-int openpty(int* __master_fd, int* __slave_fd, char* __slave_name, const struct termios* __termios_ptr, const struct winsize* __winsize_ptr) __INTRODUCED_IN(23);
-int forkpty(int* __master_fd, char* __slave_name, const struct termios* __termios_ptr, const struct winsize* __winsize_ptr) __INTRODUCED_IN(23);
+/**
+ * [openpty(3)](http://man7.org/linux/man-pages/man3/openpty.3.html) finds
+ * a free pseudoterminal and configures it with the given terminal and window
+ * size settings.
+ *
+ * Returns 0 on success and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 23.
+ */
+int openpty(int* _Nonnull __master_fd, int* _Nonnull __slave_fd, char* _Nullable __slave_name, const struct termios* _Nullable __termios_ptr, const struct winsize* _Nullable __winsize_ptr) __INTRODUCED_IN(23);
+
+/**
+ * [forkpty(3)](http://man7.org/linux/man-pages/man3/forkpty.3.html) creates
+ * a new process connected to a pseudoterminal from openpty().
+ *
+ * Returns 0 on success and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 23.
+ */
+int forkpty(int* _Nonnull __master_fd, char* _Nullable __slave_name, const struct termios* _Nullable __termios_ptr, const struct winsize* _Nullable __winsize_ptr) __INTRODUCED_IN(23);
__END_DECLS
-
-#endif
diff --git a/libc/include/stdio_ext.h b/libc/include/stdio_ext.h
index b8aa68d..3aa183d 100644
--- a/libc/include/stdio_ext.h
+++ b/libc/include/stdio_ext.h
@@ -26,32 +26,113 @@
* SUCH DAMAGE.
*/
-#ifndef _STDIO_EXT_H
-#define _STDIO_EXT_H
+#pragma once
+
+/**
+ * @file stdio_ext.h
+ * @brief Extra standard I/O functionality. See also `<stdio.h>`.
+ */
#include <sys/cdefs.h>
#include <stdio.h>
-
__BEGIN_DECLS
+/**
+ * [__fbufsize(3)](http://man7.org/linux/man-pages/man3/__fbufsize.3.html) returns the size of
+ * the stream's buffer.
+ *
+ * Available since API level 23.
+ */
size_t __fbufsize(FILE* __fp) __INTRODUCED_IN(23);
+
+/**
+ * [__freadable(3)](http://man7.org/linux/man-pages/man3/__freadable.3.html) returns non-zero if
+ * the stream allows reading, 0 otherwise.
+ *
+ * Available since API level 23.
+ */
int __freadable(FILE* __fp) __INTRODUCED_IN(23);
+
+/**
+ * [__freading(3)](http://man7.org/linux/man-pages/man3/__freading.3.html) returns non-zero if
+ * the stream's last operation was a read, 0 otherwise.
+ *
+ * Available since API level 28.
+ */
int __freading(FILE* __fp) __INTRODUCED_IN(28);
+
+/**
+ * [__fwritable(3)](http://man7.org/linux/man-pages/man3/__fwritable.3.html) returns non-zero if
+ * the stream allows writing, 0 otherwise.
+ *
+ * Available since API level 23.
+ */
int __fwritable(FILE* __fp) __INTRODUCED_IN(23);
+
+/**
+ * [__fwriting(3)](http://man7.org/linux/man-pages/man3/__fwriting.3.html) returns non-zero if
+ * the stream's last operation was a write, 0 otherwise.
+ *
+ * Available since API level 28.
+ */
int __fwriting(FILE* __fp) __INTRODUCED_IN(28);
+
+/**
+ * [__flbf(3)](http://man7.org/linux/man-pages/man3/__flbf.3.html) returns non-zero if
+ * the stream is line-buffered, 0 otherwise.
+ *
+ * Available since API level 23.
+ */
int __flbf(FILE* __fp) __INTRODUCED_IN(23);
+
+/**
+ * [__fpurge(3)](http://man7.org/linux/man-pages/man3/__fpurge.3.html) discards the contents of
+ * the stream's buffer.
+ *
+ * Available since API level 23.
+ */
void __fpurge(FILE* __fp) __INTRODUCED_IN(23);
+
+/**
+ * [__fpending(3)](http://man7.org/linux/man-pages/man3/__fpending.3.html) returns the number of
+ * bytes in the output buffer.
+ *
+ * Available since API level 23.
+ */
size_t __fpending(FILE* __fp) __INTRODUCED_IN(23);
+
+/**
+ * [_flushlbf(3)](http://man7.org/linux/man-pages/man3/_flushlbf.3.html) flushes all
+ * line-buffered streams.
+ *
+ * Available since API level 23.
+ */
void _flushlbf(void) __INTRODUCED_IN(23);
+/**
+ * `__fseterr` sets the
+ * stream's error flag (as tested by ferror() and cleared by fclearerr()).
+ *
+ * Available since API level 28.
+ */
void __fseterr(FILE* __fp) __INTRODUCED_IN(28);
+/** __fsetlocking() constant to query locking type. */
#define FSETLOCKING_QUERY 0
+/** __fsetlocking() constant to set locking to be maintained by stdio. */
#define FSETLOCKING_INTERNAL 1
+/** __fsetlocking() constant to set locking to be maintained by the caller. */
#define FSETLOCKING_BYCALLER 2
+
+/**
+ * [__fsetlocking(3)](http://man7.org/linux/man-pages/man3/__fsetlocking.3.html) sets the
+ * stream's locking mode to one of the `FSETLOCKING_` types.
+ *
+ * Returns the current locking style, `FSETLOCKING_INTERNAL` or `FSETLOCKING_BYCALLER`.
+ *
+ * Available since API level 23.
+ */
int __fsetlocking(FILE* __fp, int __type) __INTRODUCED_IN(23);
__END_DECLS
-
-#endif /* _STDIO_EXT_H */
diff --git a/libc/include/strings.h b/libc/include/strings.h
index c2e0a5e..ccdac04 100644
--- a/libc/include/strings.h
+++ b/libc/include/strings.h
@@ -36,8 +36,12 @@
* POSSIBILITY OF SUCH DAMAGE.
*/
-#ifndef _STRINGS_H_
-#define _STRINGS_H_
+#pragma once
+
+/**
+ * @file strings.h
+ * @brief Extra string functions.
+ */
#include <sys/types.h>
#include <sys/cdefs.h>
@@ -46,20 +50,28 @@
#include <bits/strcasecmp.h>
__BEGIN_DECLS
+
#if defined(__BIONIC_FORTIFY)
+/** Deprecated. Use memmove() instead. */
#define bcopy(b1, b2, len) (void)(__builtin___memmove_chk((b2), (b1), (len), __bos0(b2)))
+/** Deprecated. Use memset() instead. */
#define bzero(b, len) (void)(__builtin___memset_chk((b), '\0', (len), __bos0(b)))
#else
+/** Deprecated. Use memmove() instead. */
#define bcopy(b1, b2, len) (void)(__builtin_memmove((b2), (b1), (len)))
+/** Deprecated. Use memset() instead. */
#define bzero(b, len) (void)(__builtin_memset((b), '\0', (len)))
#endif
#if !defined(__i386__) || __ANDROID_API__ >= __ANDROID_API_J_MR2__
+/**
+ * [ffs(3)](http://man7.org/linux/man-pages/man3/ffs.3.html) finds the first set bit in `__i`.
+ *
+ * Returns 0 if no bit is set, or the index of the lowest set bit (counting from 1) otherwise.
+ */
int ffs(int __i) __INTRODUCED_IN_X86(18);
#endif
__END_DECLS
#include <android/legacy_strings_inlines.h>
-
-#endif
diff --git a/libc/include/sys/errno.h b/libc/include/sys/errno.h
index 339f4fc..77526a9 100644
--- a/libc/include/sys/errno.h
+++ b/libc/include/sys/errno.h
@@ -1 +1,10 @@
+#pragma once
+
+/**
+ * @file sys/errno.h
+ * @brief Historical synonym for `<errno.h>`.
+ *
+ * New code should use `<errno.h>` directly.
+ */
+
#include <errno.h>
diff --git a/libc/include/sys/fcntl.h b/libc/include/sys/fcntl.h
index cd30455..35e677a 100644
--- a/libc/include/sys/fcntl.h
+++ b/libc/include/sys/fcntl.h
@@ -1 +1,10 @@
+#pragma once
+
+/**
+ * @file sys/fcntl.h
+ * @brief Historical synonym for `<fcntl.h>`.
+ *
+ * New code should use `<fcntl.h>` directly.
+ */
+
#include <fcntl.h>
diff --git a/libc/include/sys/limits.h b/libc/include/sys/limits.h
index 1e189a1..33ccaee 100644
--- a/libc/include/sys/limits.h
+++ b/libc/include/sys/limits.h
@@ -1 +1,10 @@
+#pragma once
+
+/**
+ * @file sys/limits.h
+ * @brief Historical synonym for `<limits.h>`.
+ *
+ * New code should use `<limits.h>` directly.
+ */
+
#include <limits.h>
diff --git a/libc/include/sys/poll.h b/libc/include/sys/poll.h
index 779ec77..0323e37 100644
--- a/libc/include/sys/poll.h
+++ b/libc/include/sys/poll.h
@@ -1 +1,10 @@
+#pragma once
+
+/**
+ * @file sys/poll.h
+ * @brief Historical synonym for `<poll.h>`.
+ *
+ * New code should use `<poll.h>` directly.
+ */
+
#include <poll.h>
diff --git a/libc/include/sys/signal.h b/libc/include/sys/signal.h
index 2e602da..fde0819 100644
--- a/libc/include/sys/signal.h
+++ b/libc/include/sys/signal.h
@@ -1 +1,10 @@
+#pragma once
+
+/**
+ * @file sys/signal.h
+ * @brief Historical synonym for `<signal.h>`.
+ *
+ * New code should use `<signal.h>` directly.
+ */
+
#include <signal.h>
diff --git a/libc/include/sys/sysconf.h b/libc/include/sys/sysconf.h
index eb30faf..060ba7e 100644
--- a/libc/include/sys/sysconf.h
+++ b/libc/include/sys/sysconf.h
@@ -1,6 +1,14 @@
-/*
+#pragma once
+
+/**
+ * @file sys/sysconf.h
+ * @brief Historical synonym for `<sysconf.h>`.
+ *
* This file used to contain the declarations of sysconf and its associated constants.
- * No standard mentions a <sys/sysconf.h>, but there are enough users in vendor (and potential ones
- * in the NDK) to warrant not breaking source compatibility.
+ * No standard mentions a `<sys/sysconf.h>`, but there are enough users in vendor (and
+ * potential NDK users) to warrant not breaking source compatibility.
+ *
+ * New code should use `<sysconf.h>` directly.
*/
+
#include <bits/sysconf.h>
diff --git a/libc/include/sys/syslog.h b/libc/include/sys/syslog.h
index 7761ece..4b89c10 100644
--- a/libc/include/sys/syslog.h
+++ b/libc/include/sys/syslog.h
@@ -1 +1,10 @@
+#pragma once
+
+/**
+ * @file sys/syslog.h
+ * @brief Historical synonym for `<syslog.h>`.
+ *
+ * New code should use `<syslog.h>` directly.
+ */
+
#include <syslog.h>
diff --git a/libc/include/sys/unistd.h b/libc/include/sys/unistd.h
index 1e823fb..eb7694d 100644
--- a/libc/include/sys/unistd.h
+++ b/libc/include/sys/unistd.h
@@ -1 +1,10 @@
+#pragma once
+
+/**
+ * @file sys/unistd.h
+ * @brief Historical synonym for `<unistd.h>`.
+ *
+ * New code should use `<unistd.h>` directly.
+ */
+
#include <unistd.h>
diff --git a/libc/include/syscall.h b/libc/include/syscall.h
index 4c30578..11d9655 100644
--- a/libc/include/syscall.h
+++ b/libc/include/syscall.h
@@ -1 +1,10 @@
+#pragma once
+
+/**
+ * @file syscall.h
+ * @brief Historical alternative to `<sys/syscall.h>`.
+ *
+ * New code should use `<sys/syscall.h>` directly.
+ */
+
#include <sys/syscall.h>
diff --git a/libc/include/sysexits.h b/libc/include/sysexits.h
index 97f5366..b0001e6 100644
--- a/libc/include/sysexits.h
+++ b/libc/include/sysexits.h
@@ -32,90 +32,134 @@
* @(#)sysexits.h 4.8 (Berkeley) 4/3/91
*/
-#ifndef _SYSEXITS_H_
-#define _SYSEXITS_H_
+#pragma once
+
+/**
+ * @file sysexits.h
+ * @brief Exit status codes for system programs.
+ *
+ * This include file attempts to categorize possible error
+ * exit statuses for system programs such as sendmail.
+ */
#include <sys/cdefs.h>
-/*
- * SYSEXITS.H -- Exit status codes for system programs.
- *
- * This include file attempts to categorize possible error
- * exit statuses for system programs, notably delivermail
- * and the Berkeley network.
- *
- * Error numbers begin at EX__BASE to reduce the possibility of
- * clashing with other exit statuses that random programs may
- * already return. The meaning of the codes is approximately
- * as follows:
- *
- * EX_USAGE -- The command was used incorrectly, e.g., with
- * the wrong number of arguments, a bad flag, a bad
- * syntax in a parameter, or whatever.
- * EX_DATAERR -- The input data was incorrect in some way.
- * This should only be used for user's data & not
- * system files.
- * EX_NOINPUT -- An input file (not a system file) did not
- * exist or was not readable. This could also include
- * errors like "No message" to a mailer (if it cared
- * to catch it).
- * EX_NOUSER -- The user specified did not exist. This might
- * be used for mail addresses or remote logins.
- * EX_NOHOST -- The host specified did not exist. This is used
- * in mail addresses or network requests.
- * EX_UNAVAILABLE -- A service is unavailable. This can occur
- * if a support program or file does not exist. This
- * can also be used as a catchall message when something
- * you wanted to do doesn't work, but you don't know
- * why.
- * EX_SOFTWARE -- An internal software error has been detected.
- * This should be limited to non-operating system related
- * errors as possible.
- * EX_OSERR -- An operating system error has been detected.
- * This is intended to be used for such things as "cannot
- * fork", "cannot create pipe", or the like. It includes
- * things like getuid returning a user that does not
- * exist in the passwd file.
- * EX_OSFILE -- Some system file (e.g., /etc/passwd, /var/run/utmp,
- * etc.) does not exist, cannot be opened, or has some
- * sort of error (e.g., syntax error).
- * EX_CANTCREAT -- A (user specified) output file cannot be
- * created.
- * EX_IOERR -- An error occurred while doing I/O on some file.
- * EX_TEMPFAIL -- temporary failure, indicating something that
- * is not really an error. In sendmail, this means
- * that a mailer (e.g.) could not create a connection,
- * and the request should be reattempted later.
- * EX_PROTOCOL -- the remote system returned something that
- * was "not possible" during a protocol exchange.
- * EX_NOPERM -- You did not have sufficient permission to
- * perform the operation. This is not intended for
- * file system problems, which should use EX_NOINPUT or
- * EX_CANTCREAT, but rather for higher level permissions.
- * EX_CONFIG -- Something was found in an unconfigured or
- * misconfigured state.
+/** Successful termination. */
+#define EX_OK 0
+
+/**
+ * Base value for error messages.
+ * Error numbers begin at `EX__BASE` to reduce the possibility of
+ * clashing with other exit statuses that random programs may
+ * already return.
*/
+#define EX__BASE 64
-#define EX_OK 0 /* successful termination */
+/**
+ * Command line usage error.
+ * The command was used incorrectly, such as the wrong number of
+ * arguments, a bad flag, or bad syntax for a parameter.
+ */
+#define EX_USAGE 64
-#define EX__BASE 64 /* base value for error messages */
+/**
+ * Data format error.
+ * The input data was incorrect in some way.
+ * This should only be used for user's data and not for system files.
+ */
+#define EX_DATAERR 65
-#define EX_USAGE 64 /* command line usage error */
-#define EX_DATAERR 65 /* data format error */
-#define EX_NOINPUT 66 /* cannot open input */
-#define EX_NOUSER 67 /* addressee unknown */
-#define EX_NOHOST 68 /* host name unknown */
-#define EX_UNAVAILABLE 69 /* service unavailable */
-#define EX_SOFTWARE 70 /* internal software error */
-#define EX_OSERR 71 /* system error (e.g., can't fork) */
-#define EX_OSFILE 72 /* critical OS file missing */
-#define EX_CANTCREAT 73 /* can't create (user) output file */
-#define EX_IOERR 74 /* input/output error */
-#define EX_TEMPFAIL 75 /* temp failure; user is invited to retry */
-#define EX_PROTOCOL 76 /* remote error in protocol */
-#define EX_NOPERM 77 /* permission denied */
-#define EX_CONFIG 78 /* configuration error */
+/**
+ * Cannot open input.
+ * An input file (not a system file) did not exist or was not readable.
+ * This could also include errors like "No message" to a mailer (if it cared
+ * to catch it).
+ */
+#define EX_NOINPUT 66
-#define EX__MAX 78 /* maximum listed value */
+/**
+ * The specified user did not exist.
+ * This might be used for mail addresses or remote logins.
+ */
+#define EX_NOUSER 67
-#endif /* !_SYSEXITS_H_ */
+/**
+ * The specified host did not exist.
+ * This is used in mail addresses or network requests.
+ */
+#define EX_NOHOST 68
+
+/**
+ * A service is unavailable.
+ * This can occur if a support program or file does not exist.
+ * This can also be used as a catchall message when something
+ * you wanted to do doesn't work, but you don't know why.
+ */
+#define EX_UNAVAILABLE 69
+
+/**
+ * An internal software error has been detected.
+ * This should be limited to non-operating system related errors.
+ */
+#define EX_SOFTWARE 70
+
+/**
+ * An operating system error has been detected.
+ * This is intended to be used for such things as "cannot
+ * fork", "cannot create pipe", or the like. It includes
+ * things like getuid returning a user that does not
+ * exist in the passwd file.
+ */
+#define EX_OSERR 71
+
+/**
+ * Critical OS file error.
+ * A system file (such as /etc/passwd) does not exist, cannot be opened,
+ * or has some other problem (such as a syntax error).
+ */
+#define EX_OSFILE 72
+
+/**
+ * Can't create (user) output file.
+ * A (user specified) output file cannot be created.
+ */
+#define EX_CANTCREAT 73
+
+/**
+ * Input/output error.
+ * An error occurred while doing I/O on some file.
+ */
+#define EX_IOERR 74
+
+/**
+ * Temporary failure; user is invited to retry.
+ * A temporary failure, indicating something that
+ * is not really an error. In sendmail, this might mean
+ * that a mailer could not create a connection,
+ * and the request should be reattempted later.
+ */
+#define EX_TEMPFAIL 75
+
+/**
+ * Remote error in protocol.
+ * The remote system returned something that
+ * was "not possible" during a protocol exchange.
+ */
+#define EX_PROTOCOL 76
+
+/**
+ * Permission denied.
+ * You did not have sufficient permission to perform the operation.
+ * This is not intended for file system problems, which should use EX_NOINPUT or
+ * EX_CANTCREAT, but rather for higher level permissions.
+ */
+#define EX_NOPERM 77
+
+/**
+ * Configuration error.
+ * Something was found in an unconfigured or misconfigured state.
+ */
+#define EX_CONFIG 78
+
+/** Maximum listed value. */
+#define EX__MAX 78
diff --git a/libc/include/syslog.h b/libc/include/syslog.h
index fff565e..45de253 100644
--- a/libc/include/syslog.h
+++ b/libc/include/syslog.h
@@ -26,8 +26,7 @@
* SUCH DAMAGE.
*/
-#ifndef _SYSLOG_H
-#define _SYSLOG_H
+#pragma once
#include <stdio.h>
#include <sys/cdefs.h>
@@ -35,63 +34,128 @@
__BEGIN_DECLS
-/* Priorities are translated to Android log priorities as shown. */
-#define LOG_EMERG 0 /* ERROR */
-#define LOG_ALERT 1 /* ERROR */
-#define LOG_CRIT 2 /* ERROR */
-#define LOG_ERR 3 /* ERROR */
-#define LOG_WARNING 4 /* WARN */
-#define LOG_NOTICE 5 /* INFO */
-#define LOG_INFO 6 /* INFO */
-#define LOG_DEBUG 7 /* DEBUG */
+/** Corresponds to the Android ERROR log priority. */
+#define LOG_EMERG 0
+/** Corresponds to the Android ERROR log priority. */
+#define LOG_ALERT 1
+/** Corresponds to the Android ERROR log priority. */
+#define LOG_CRIT 2
+/** Corresponds to the Android ERROR log priority. */
+#define LOG_ERR 3
+/** Corresponds to the Android WARN log priority. */
+#define LOG_WARNING 4
+/** Corresponds to the Android INFO log priority. */
+#define LOG_NOTICE 5
+/** Corresponds to the Android INFO log priority. */
+#define LOG_INFO 6
+/** Corresponds to the Android DEBUG log priority. */
+#define LOG_DEBUG 7
#define LOG_PRIMASK 7
#define LOG_PRI(x) ((x) & LOG_PRIMASK)
#define LOG_MAKEPRI(fac, pri) ((fac) | (pri))
-/* Facilities are currently ignored on Android. */
+/** Currently ignored on Android. */
#define LOG_KERN (0<<3)
+/** Currently ignored on Android. */
#define LOG_USER (1<<3)
+/** Currently ignored on Android. */
#define LOG_MAIL (2<<3)
+/** Currently ignored on Android. */
#define LOG_DAEMON (3<<3)
+/** Currently ignored on Android. */
#define LOG_AUTH (4<<3)
+/** Currently ignored on Android. */
#define LOG_SYSLOG (5<<3)
+/** Currently ignored on Android. */
#define LOG_LPR (6<<3)
+/** Currently ignored on Android. */
#define LOG_NEWS (7<<3)
+/** Currently ignored on Android. */
#define LOG_UUCP (8<<3)
+/** Currently ignored on Android. */
#define LOG_CRON (9<<3)
+/** Currently ignored on Android. */
#define LOG_AUTHPRIV (10<<3)
+/** Currently ignored on Android. */
#define LOG_FTP (11<<3)
+/** Currently ignored on Android. */
#define LOG_LOCAL0 (16<<3)
+/** Currently ignored on Android. */
#define LOG_LOCAL1 (17<<3)
+/** Currently ignored on Android. */
#define LOG_LOCAL2 (18<<3)
+/** Currently ignored on Android. */
#define LOG_LOCAL3 (19<<3)
+/** Currently ignored on Android. */
#define LOG_LOCAL4 (20<<3)
+/** Currently ignored on Android. */
#define LOG_LOCAL5 (21<<3)
+/** Currently ignored on Android. */
#define LOG_LOCAL6 (22<<3)
+/** Currently ignored on Android. */
#define LOG_LOCAL7 (23<<3)
#define LOG_NFACILITIES 24
#define LOG_FACMASK 0x3f8
#define LOG_FAC(x) (((x) >> 3) & (LOG_FACMASK >> 3))
+/**
+ * Converts a log priority into a mask enabling that single priority,
+ * for use with setlogmask().
+ */
#define LOG_MASK(pri) (1 << (pri))
+
+/**
+ * Converts a log priority into a mask enabling that priority and all lower
+ * priorities, for use with setlogmask().
+ */
#define LOG_UPTO(pri) ((1 << ((pri)+1)) - 1)
-/* openlog(3) flags are currently ignored on Android. */
+/** openlog() options are currently ignored on Android. */
#define LOG_PID 0x01
+/** openlog() options are currently ignored on Android. */
#define LOG_CONS 0x02
+/** openlog() options are currently ignored on Android. */
#define LOG_ODELAY 0x04
+/** openlog() options are currently ignored on Android. */
#define LOG_NDELAY 0x08
+/** openlog() options are currently ignored on Android. */
#define LOG_NOWAIT 0x10
+/** openlog() options are currently ignored on Android. */
#define LOG_PERROR 0x20
+/**
+ * [closelog(3)](http://man7.org/linux/man-pages/man3/closelog.3.html) does
+ * nothing on Android.
+ */
void closelog(void);
+
+/**
+ * [openlog(3)](http://man7.org/linux/man-pages/man3/openlog.3.html) sets
+ * the log tag to `__prefix`. On Android, the other two arguments are ignored.
+ */
void openlog(const char* __prefix, int __option, int __facility);
+
+/**
+ * [setlogmask(3)](http://man7.org/linux/man-pages/man3/setlogmask.3.html)
+ * sets which log priorities will actually be logged. See `LOG_MASK` and
+ * `LOG_UPTO`.
+ */
int setlogmask(int __mask);
+
+/**
+ * [syslog(3)](http://man7.org/linux/man-pages/man3/syslog.3.html) formats
+ * the printf()-like message and logs it with the given priority, unless
+ * suppressed by setlogmask(). On Android, the output goes to logcat.
+ */
void syslog(int __priority, const char* __fmt, ...) __printflike(2, 3);
+
+/**
+ * [vsyslog(3)](http://man7.org/linux/man-pages/man3/vsyslog.3.html) formats
+ * the vprintf()-like message and logs it with the given priority, unless
+ * suppressed by setlogmask(). On Android, the output goes to logcat.
+ */
void vsyslog(int __priority, const char* __fmt, va_list __args) __printflike(2, 0);
__END_DECLS
-
-#endif /* _SYSLOG_H */
diff --git a/libc/include/tar.h b/libc/include/tar.h
index a5d7a36..9d0c3ba 100644
--- a/libc/include/tar.h
+++ b/libc/include/tar.h
@@ -26,37 +26,64 @@
* SUCH DAMAGE.
*/
-#ifndef _TAR_H_
-#define _TAR_H_
+#pragma once
+
+/**
+ * @file tar.h
+ * @brief Constants for reading/writing `.tar` files.
+ */
#include <sys/cdefs.h>
+/** `.tar` file magic. (Includes the NUL.) */
#define TMAGIC "ustar"
+/** `.tar` file magic length in bytes. */
#define TMAGLEN 6
+/** `.tar` file version. (Does not include the NUL.) */
#define TVERSION "00"
+/** `.tar` file version length in bytes. */
#define TVERSLEN 2
+/** Regular file type flag. */
#define REGTYPE '0'
+/** Alternate regular file type flag. */
#define AREGTYPE '\0'
+/** Link type flag. */
#define LNKTYPE '1'
+/** Symbolic link type flag. */
#define SYMTYPE '2'
+/** Character special file type flag. */
#define CHRTYPE '3'
+/** Block special file type flag. */
#define BLKTYPE '4'
+/** Directory type flag. */
#define DIRTYPE '5'
+/** FIFO special file type flag. */
#define FIFOTYPE '6'
+/** Reserved type flag. */
#define CONTTYPE '7'
+/** Set-UID mode field bit. */
#define TSUID 04000
+/** Set-GID mode field bit. */
#define TSGID 02000
+/** Directory restricted deletion mode field bit. */
#define TSVTX 01000
+/** Readable by user mode field bit. */
#define TUREAD 00400
+/** Writable by user mode field bit. */
#define TUWRITE 00200
+/** Executable by user mode field bit. */
#define TUEXEC 00100
+/** Readable by group mode field bit. */
#define TGREAD 00040
+/** Writable by group mode field bit. */
#define TGWRITE 00020
+/** Executable by group mode field bit. */
#define TGEXEC 00010
+/** Readable by other mode field bit. */
#define TOREAD 00004
+/** Writable by other mode field bit. */
#define TOWRITE 00002
+/** Executable by other mode field bit. */
#define TOEXEC 00001
-
-#endif /* _TAR_H_ */
diff --git a/libc/include/termio.h b/libc/include/termio.h
index 9e26956..9ba3ce8 100644
--- a/libc/include/termio.h
+++ b/libc/include/termio.h
@@ -1 +1,10 @@
+#pragma once
+
+/**
+ * @file termio.h
+ * @brief Historical alternative to `<termios.h>`.
+ *
+ * New code should use `<termios.h>` directly.
+ */
+
#include <termios.h>
diff --git a/libc/include/termios.h b/libc/include/termios.h
index 3eaab00..0fd5c95 100644
--- a/libc/include/termios.h
+++ b/libc/include/termios.h
@@ -25,8 +25,13 @@
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
*/
-#ifndef _TERMIOS_H_
-#define _TERMIOS_H_
+
+#pragma once
+
+/**
+ * @file termios.h
+ * @brief General terminal interfaces.
+ */
#include <sys/cdefs.h>
#include <sys/ioctl.h>
@@ -36,24 +41,112 @@
__BEGIN_DECLS
#if __ANDROID_API__ >= __ANDROID_API_L__
-// Implemented as static inlines before 21.
+// This file is implemented as static inlines before API level 21.
+
+/**
+ * [cfgetispeed(3)](http://man7.org/linux/man-pages/man3/cfgetispeed.3.html)
+ * returns the terminal input baud rate.
+ */
speed_t cfgetispeed(const struct termios* __t) __INTRODUCED_IN(21);
+
+/**
+ * [cfgetospeed(3)](http://man7.org/linux/man-pages/man3/cfgetospeed.3.html)
+ * returns the terminal output baud rate.
+ */
speed_t cfgetospeed(const struct termios* __t) __INTRODUCED_IN(21);
+
+/**
+ * [cfmakeraw(3)](http://man7.org/linux/man-pages/man3/cfmakeraw.3.html)
+ * configures the terminal for "raw" mode.
+ */
void cfmakeraw(struct termios* __t) __INTRODUCED_IN(21);
+
+/**
+ * [cfsetspeed(3)](http://man7.org/linux/man-pages/man3/cfsetspeed.3.html)
+ * sets the terminal input and output baud rate.
+ *
+ * Returns 0 on success and returns -1 and sets `errno` on failure.
+ */
int cfsetspeed(struct termios* __t, speed_t __speed) __INTRODUCED_IN(21);
+
+/**
+ * [cfsetispeed(3)](http://man7.org/linux/man-pages/man3/cfsetispeed.3.html)
+ * sets the terminal input baud rate.
+ *
+ * Returns 0 on success and returns -1 and sets `errno` on failure.
+ */
int cfsetispeed(struct termios* __t, speed_t __speed) __INTRODUCED_IN(21);
+
+/**
+ * [cfsetospeed(3)](http://man7.org/linux/man-pages/man3/cfsetospeed.3.html)
+ * sets the terminal output baud rate.
+ *
+ * Returns 0 on success and returns -1 and sets `errno` on failure.
+ */
int cfsetospeed(struct termios* __t, speed_t __speed) __INTRODUCED_IN(21);
+
+/**
+ * [tcdrain(3)](http://man7.org/linux/man-pages/man3/tcdrain.3.html)
+ * waits until all output has been written.
+ *
+ * Returns 0 on success and returns -1 and sets `errno` on failure.
+ */
int tcdrain(int __fd) __INTRODUCED_IN(21);
+
+/**
+ * [tcflow(3)](http://man7.org/linux/man-pages/man3/tcflow.3.html)
+ * suspends (`TCOOFF`) or resumes (`TCOON`) output, or transmits a
+ * stop (`TCIOFF`) or start (`TCION`) to suspend or resume input.
+ *
+ * Returns 0 on success and returns -1 and sets `errno` on failure.
+ */
int tcflow(int __fd, int __action) __INTRODUCED_IN(21);
+
+/**
+ * [tcflush(3)](http://man7.org/linux/man-pages/man3/tcflush.3.html)
+ * discards pending input (`TCIFLUSH`), output (`TCOFLUSH`), or
+ * both (`TCIOFLUSH`). (In `<stdio.h>` terminology, this is a purge rather
+ * than a flush.)
+ *
+ * Returns 0 on success and returns -1 and sets `errno` on failure.
+ */
int tcflush(int __fd, int __queue) __INTRODUCED_IN(21);
+
+/**
+ * [tcgetattr(3)](http://man7.org/linux/man-pages/man3/tcgetattr.3.html)
+ * reads the configuration of the given terminal.
+ *
+ * Returns 0 on success and returns -1 and sets `errno` on failure.
+ */
int tcgetattr(int __fd, struct termios* __t) __INTRODUCED_IN(21);
+
+/**
+ * [tcgetsid(3)](http://man7.org/linux/man-pages/man3/tcgetsid.3.html)
+ * returns the session id corresponding to the given fd.
+ *
+ * Returns a non-negative session id on success and
+ * returns -1 and sets `errno` on failure.
+ */
pid_t tcgetsid(int __fd) __INTRODUCED_IN(21);
+
+/**
+ * [tcsendbreak(3)](http://man7.org/linux/man-pages/man3/tcsendbreak.3.html)
+ * sends a break.
+ *
+ * Returns 0 on success and returns -1 and sets `errno` on failure.
+ */
int tcsendbreak(int __fd, int __duration) __INTRODUCED_IN(21);
+
+/**
+ * [tcsetattr(3)](http://man7.org/linux/man-pages/man3/tcsetattr.3.html)
+ * writes the configuration of the given terminal.
+ *
+ * Returns 0 on success and returns -1 and sets `errno` on failure.
+ */
int tcsetattr(int __fd, int __optional_actions, const struct termios* __t) __INTRODUCED_IN(21);
+
#endif
__END_DECLS
#include <android/legacy_termios_inlines.h>
-
-#endif
diff --git a/libc/include/uchar.h b/libc/include/uchar.h
index e59d6a9..90af651 100644
--- a/libc/include/uchar.h
+++ b/libc/include/uchar.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _UCHAR_H_
-#define _UCHAR_H_
+#pragma once
+
+/**
+ * @file uchar.h
+ * @brief Unicode functions.
+ */
#include <stddef.h>
#include <sys/cdefs.h>
@@ -36,18 +40,54 @@
__BEGIN_DECLS
#if !defined(__cplusplus)
+/** The UTF-16 character type. */
typedef __CHAR16_TYPE__ char16_t;
+/** The UTF-32 character type. */
typedef __CHAR32_TYPE__ char32_t;
#endif
+/** On Android, char16_t is UTF-16. */
#define __STD_UTF_16__ 1
+
+/** On Android, char32_t is UTF-32. */
#define __STD_UTF_32__ 1
-size_t c16rtomb(char* __buf, char16_t __ch16, mbstate_t* __ps) __INTRODUCED_IN(21);
-size_t c32rtomb(char* __buf, char32_t __ch32, mbstate_t* __ps) __INTRODUCED_IN(21);
-size_t mbrtoc16(char16_t* __ch16, const char* __s, size_t __n, mbstate_t* __ps) __INTRODUCED_IN(21);
-size_t mbrtoc32(char32_t* __ch32, const char* __s, size_t __n, mbstate_t* __ps) __INTRODUCED_IN(21);
+/**
+ * [c16rtomb(3)](http://man7.org/linux/man-pages/man3/c16rtomb.3.html) converts a single UTF-16
+ * character to UTF-8.
+ *
+ * Returns the number of bytes written to `__buf` on success, and returns -1 and sets `errno`
+ * on failure.
+ *
+ * Available since API level 21.
+ */
+size_t c16rtomb(char* _Nullable __buf, char16_t __ch16, mbstate_t* _Nullable __ps) __INTRODUCED_IN(21);
+
+/**
+ * [c32rtomb(3)](http://man7.org/linux/man-pages/man3/c32rtomb.3.html) converts a single UTF-32
+ * character to UTF-8.
+ *
+ * Returns the number of bytes written to `__buf` on success, and returns -1 and sets `errno`
+ * on failure.
+ *
+ * Available since API level 21.
+ */
+size_t c32rtomb(char* _Nullable __buf, char32_t __ch32, mbstate_t* _Nullable __ps) __INTRODUCED_IN(21);
+
+/**
+ * [mbrtoc16(3)](http://man7.org/linux/man-pages/man3/mbrtoc16.3.html) converts the next UTF-8
+ * sequence to a UTF-16 code point.
+ *
+ * Available since API level 21.
+ */
+size_t mbrtoc16(char16_t* _Nullable __ch16, const char* _Nullable __s, size_t __n, mbstate_t* _Nullable __ps) __INTRODUCED_IN(21);
+
+/**
+ * [mbrtoc32(3)](http://man7.org/linux/man-pages/man3/mbrtoc32.3.html) converts the next UTF-8
+ * sequence to a UTF-32 code point.
+ *
+ * Available since API level 21.
+ */
+size_t mbrtoc32(char32_t* _Nullable __ch32, const char* _Nullable __s, size_t __n, mbstate_t* _Nullable __ps) __INTRODUCED_IN(21);
__END_DECLS
-
-#endif
diff --git a/libc/include/ucontext.h b/libc/include/ucontext.h
index 73c2166..99201d2 100644
--- a/libc/include/ucontext.h
+++ b/libc/include/ucontext.h
@@ -1 +1,10 @@
+#pragma once
+
+/**
+ * @file ucontext.h
+ * @brief Historical alternative to `<sys/ucontext.h>`.
+ *
+ * New code should use `<sys/ucontext.h>` directly.
+ */
+
#include <sys/ucontext.h>
diff --git a/libc/include/utime.h b/libc/include/utime.h
index be6b894..4d181a8 100644
--- a/libc/include/utime.h
+++ b/libc/include/utime.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _UTIME_H_
-#define _UTIME_H_
+#pragma once
+
+/**
+ * @file utime.h
+ * @brief Historical access/modification time functionality.
+ */
#include <sys/cdefs.h>
#include <sys/types.h>
@@ -35,8 +39,14 @@
__BEGIN_DECLS
-int utime(const char* __filename, const struct utimbuf* __times);
+/**
+ * [utime(2)](http://man7.org/linux/man-pages/man2/utime.2.html) changes the access and
+ * modification time of `__filename`. If `__times` is null, the current time is used.
+ *
+ * New code should prefer utimensat().
+ *
+ * Returns 0 on success and returns -1 and sets `errno` on failure.
+ */
+int utime(const char* _Nonnull __filename, const struct utimbuf* _Nullable __times);
__END_DECLS
-
-#endif
diff --git a/libc/include/wait.h b/libc/include/wait.h
index d01b811..e375daa 100644
--- a/libc/include/wait.h
+++ b/libc/include/wait.h
@@ -1 +1,10 @@
+#pragma once
+
+/**
+ * @file wait.h
+ * @brief Historical alternative to `<sys/wait.h>`.
+ *
+ * New code should use `<sys/wait.h>` directly.
+ */
+
#include <sys/wait.h>
diff --git a/libc/include/xlocale.h b/libc/include/xlocale.h
index 559d24d..d04a711 100644
--- a/libc/include/xlocale.h
+++ b/libc/include/xlocale.h
@@ -26,13 +26,24 @@
* SUCH DAMAGE.
*/
-#ifndef _XLOCALE_H_
-#define _XLOCALE_H_
+#pragma once
+
+/**
+ * @file xlocale.h
+ * @brief `locale_t` definition.
+ *
+ * Most users will want `<locale.h>` instead. `<xlocale.h>` is used by the C
+ * library itself to export the `locale_t` type without exporting the
+ * `<locale.h>` functions in other headers that export locale-sensitive
+ * functions (such as `<string.h>`).
+ */
#include <sys/cdefs.h>
-/* If we just use void* here, GCC exposes that in error messages. */
+/* If we just use void* in the typedef, the compiler exposes that in error messages. */
struct __locale_t;
-typedef struct __locale_t* locale_t;
-#endif /* _XLOCALE_H_ */
+/**
+ * The `locale_t` type that represents a locale.
+ */
+typedef struct __locale_t* locale_t;