From dd6763a6c677687ad06727af037ed9a7b018c773 Mon Sep 17 00:00:00 2001 From: Elliott Hughes Date: Thu, 4 Oct 2018 16:35:13 -0700 Subject: [PATCH] Another round of documentation. Bug: N/A Test: N/A Change-Id: I1b818fbb36ddd6d084dee56828290c2717a0c9b0 --- libc/include/android/set_abort_message.h | 19 ++++-- libc/include/bits/auxvec.h | 26 ++++---- libc/include/bits/epoll_event.h | 12 ++-- libc/include/bits/fcntl.h | 16 +++-- libc/include/bits/getopt.h | 34 +++++++++-- libc/include/bits/in_addr.h | 12 ++-- libc/include/bits/ioctl.h | 13 ++-- libc/include/bits/ip_mreq_source.h | 13 ++-- libc/include/bits/ip_msfilter.h | 11 ++-- libc/include/bits/lockf.h | 28 +++++++-- libc/include/bits/mbstate_t.h | 14 +++-- libc/include/bits/sa_family_t.h | 11 ++-- libc/include/bits/seek_constants.h | 13 ++-- libc/include/bits/strcasecmp.h | 34 +++++++++-- libc/include/bits/struct_file.h | 6 +- libc/include/bits/timespec.h | 13 ++-- libc/include/bits/wait.h | 45 ++++++++++---- libc/include/bits/wchar_limits.h | 14 +++-- libc/include/ctype.h | 76 +++++++++++++++++++++--- libc/include/getopt.h | 62 ++++++++++++------- libc/include/net/route.h | 5 +- libc/include/netinet/ether.h | 45 ++++++++++++-- libc/include/sys/auxv.h | 19 ++++-- libc/include/sys/capability.h | 23 +++++-- libc/include/sys/eventfd.h | 36 +++++++++-- libc/include/sys/file.h | 16 +++-- libc/include/sys/fsuid.h | 27 +++++++-- libc/include/sys/ioctl.h | 10 ++-- libc/include/sys/ipc.h | 16 +++-- libc/include/sys/klog.h | 48 ++++++++++----- libc/include/sys/mount.h | 36 +++++++++-- libc/include/sys/msg.h | 14 +++-- libc/include/sys/param.h | 21 ++++--- libc/include/sys/personality.h | 18 ++++-- libc/include/sys/quota.h | 17 ++++-- libc/include/sys/random.h | 32 ++++++++-- libc/include/sys/reboot.h | 33 ++++++---- libc/include/sys/sendfile.h | 23 +++++-- libc/include/sys/shm.h | 14 +++-- libc/include/sys/signalfd.h | 22 +++++-- libc/include/sys/swap.h | 34 +++++++++-- libc/include/sys/sysinfo.h | 51 ++++++++++++++-- libc/include/sys/sysmacros.h | 13 ++-- libc/include/sys/timerfd.h | 46 +++++++++++--- libc/include/sys/times.h | 17 ++++-- libc/include/sys/timex.h | 25 ++++++-- libc/include/sys/un.h | 11 ++-- libc/include/sys/utsname.h | 24 ++++++-- 48 files changed, 907 insertions(+), 261 deletions(-) diff --git a/libc/include/android/set_abort_message.h b/libc/include/android/set_abort_message.h index 3dde67360..5d8d8eeed 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 __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 de3cfbb33..4d394776a 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 #include -/* 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 054323cef..b2b4c8715 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 #include +/** The union of possible data types for an `epoll_event`. */ typedef union epoll_data { void* ptr; int fd; @@ -39,6 +44,7 @@ typedef union epoll_data { 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 @@ struct epoll_event { __packed #endif ; - -#endif diff --git a/libc/include/bits/fcntl.h b/libc/include/bits/fcntl.h index e3b0e8cdc..597aa6ee7 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 __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 548144995..0411716a6 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 __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 834c056ea..30eb04b66 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 #include +/** 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 745bbf03a..9ed12926c 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 __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 @@ int ioctl(int __fd, unsigned __request, ...) __overloadable __enable_if(1, "") _ #endif __END_DECLS - -#endif diff --git a/libc/include/bits/ip_mreq_source.h b/libc/include/bits/ip_mreq_source.h index 0eb8d688c..83490a4fa 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 #include +/** + * 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 23c127dbf..cb3350bdc 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 #include +/** The type representing an IPv4 multicast filter. */ struct ip_msfilter { struct in_addr imsf_multiaddr; struct in_addr imsf_interface; @@ -39,5 +44,3 @@ struct ip_msfilter { 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 929c68c7f..58ab03113 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 #include +/** 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 057a2c99c..0f9323d1b 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 +/** + * 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 98ca27f18..df8b695c0 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 +/** 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 34c5866c6..6b8860689 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 594046a24..3994b6893 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 #include @@ -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 08e18a13a..abbd32028 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 __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 @@ struct __sFILE { } __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 df7a7ce4d..0497cfe1f 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 #include @@ -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 a35f789ae..a6a212904 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 #include -#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 ffad6041f..311b02e3b 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 -/* 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 df11cb13f..e91b0e25f 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 #include +/** 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 c5a6106ba..014226a26 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 #include -/* - * 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 9c53875c6..21cd80b6d 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 #include #include #include #include - -#endif diff --git a/libc/include/netinet/ether.h b/libc/include/netinet/ether.h index 3e6a4e355..6268a14ab 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 #include __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 9251390d3..c6519400d 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 @@ -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 637c84419..4cb698f06 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 #include __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 3cfb5e7fa..85f9877ed 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 #include __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 a4200219f..ccdfeea52 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 #include @@ -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 bb7a58d5f..c1c8ebb52 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 #include __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 b48b7f9a6..178de4aca 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 #include @@ -39,5 +43,3 @@ #include #include - -#endif diff --git a/libc/include/sys/ipc.h b/libc/include/sys/ipc.h index dee7c8a9a..c81ec1a5a 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 #include @@ -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 ed746fcc6..b33d11b13 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 __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 `` 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 c0c084b40..4db1ac1a6 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 #include @@ -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 0273499c7..e19452c4e 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 #include @@ -41,11 +45,13 @@ __BEGIN_DECLS 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 ec50da2b9..4a83e9d74 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 #include #include +/** 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 51b5cd791..cea0bf829 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 #include __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 157c2d9cb..f8faee765 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 @@ -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 4b849f375..be52bd9ca 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 #include @@ -36,12 +40,28 @@ __BEGIN_DECLS -/* See also arc4random_buf in , 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 c0c4860ed..156d94779 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 #include __BEGIN_DECLS -/* use glibc names as well */ - -#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 +/** 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 +/** + * [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 97432c04a..60bbde8b8 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 #include @@ -38,10 +42,21 @@ __BEGIN_DECLS #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 4723eba40..a3f84d313 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 #include @@ -42,11 +46,13 @@ __BEGIN_DECLS 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 2337cd773..bd911f784 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 @@ -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 8a30ccef5..467b98c2c 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 __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 6da02ee4e..4ecf986bc 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 #include __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 592cc5e0b..64cf28938 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 +/** 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 7bf675ba7..b89941b1e 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 /* For O_CLOEXEC and O_NONBLOCK. */ #include @@ -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 3c8a4efc1..25d03e388 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 #include @@ -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 74c86118c..52db5dcfc 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 #include @@ -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 03ef5e423..83c1d1744 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 #include @@ -35,7 +39,6 @@ #if defined(__USE_BSD) || defined(__USE_GNU) #include +/** 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 2420fb4c9..1fa31871a 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 __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