Another round of documentation.
Bug: N/A
Test: N/A
Change-Id: I1b818fbb36ddd6d084dee56828290c2717a0c9b0
diff --git a/libc/include/sys/auxv.h b/libc/include/sys/auxv.h
index 9251390..c651940 100644
--- a/libc/include/sys/auxv.h
+++ b/libc/include/sys/auxv.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_AUXV_H_
-#define _SYS_AUXV_H_
+#pragma once
+
+/**
+ * @file sys/auxv.h
+ * @brief The getauxval() function.
+ */
#include <sys/cdefs.h>
@@ -35,8 +39,15 @@
__BEGIN_DECLS
+/**
+ * [getauxval(3)](http://man7.org/linux/man-pages/man2/personality.2.html) returns values from
+ * the ELF auxiliary vector passed by the kernel.
+ *
+ * Returns the corresponding value on success,
+ * and returns 0 and sets `errno` to `ENOENT` on failure.
+ *
+ * Available since API level 18.
+ */
unsigned long int getauxval(unsigned long int __type) __INTRODUCED_IN(18);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/capability.h b/libc/include/sys/capability.h
index 637c844..4cb698f 100644
--- a/libc/include/sys/capability.h
+++ b/libc/include/sys/capability.h
@@ -26,17 +26,32 @@
* SUCH DAMAGE.
*/
-#ifndef _BIONIC_SYS_CAPABILITY_H
-#define _BIONIC_SYS_CAPABILITY_H
+#pragma once
+
+/**
+ * @file sys/capability.h
+ * @brief Capabilities.
+ */
#include <sys/cdefs.h>
#include <linux/capability.h>
__BEGIN_DECLS
+/**
+ * [capget(2)](http://man7.org/linux/man-pages/man2/capget.2.html) gets the calling
+ * thread's capabilities.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ */
int capget(cap_user_header_t __hdr_ptr, cap_user_data_t __data_ptr);
+
+/**
+ * [capset(2)](http://man7.org/linux/man-pages/man2/capset.2.html) sets the calling
+ * thread's capabilities.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ */
int capset(cap_user_header_t __hdr_ptr, const cap_user_data_t __data_ptr);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/eventfd.h b/libc/include/sys/eventfd.h
index 3cfb5e7..85f9877 100644
--- a/libc/include/sys/eventfd.h
+++ b/libc/include/sys/eventfd.h
@@ -26,24 +26,48 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_EVENTFD_H
-#define _SYS_EVENTFD_H
+#pragma once
+
+/**
+ * @file sys/eventfd.h
+ * @brief Event notification file descriptors.
+ */
#include <sys/cdefs.h>
#include <fcntl.h>
__BEGIN_DECLS
+/** The eventfd() flag for a close-on-exec file descriptor. */
#define EFD_CLOEXEC O_CLOEXEC
+/** The eventfd() flag for a non-blocking file descriptor. */
#define EFD_NONBLOCK O_NONBLOCK
-typedef uint64_t eventfd_t;
-
+/**
+ * [eventfd(2)](http://man7.org/linux/man-pages/man2/eventfd.2.html) creates a file descriptor
+ * for event notification.
+ *
+ * Returns a new file descriptor on success, and returns -1 and sets `errno` on failure.
+ */
int eventfd(unsigned int __initial_value, int __flags);
+/** The type used by eventfd_read() and eventfd_write(). */
+typedef uint64_t eventfd_t;
+
+/**
+ * [eventfd_read(3)](http://man7.org/linux/man-pages/man2/eventfd.2.html) is a convenience
+ * wrapper to read an `eventfd_t` from an eventfd file descriptor.
+ *
+ * Returns 0 on success, or returns -1 otherwise.
+ */
int eventfd_read(int __fd, eventfd_t* __value);
+
+/**
+ * [eventfd_write(3)](http://man7.org/linux/man-pages/man2/eventfd.2.html) is a convenience
+ * wrapper to write an `eventfd_t` to an eventfd file descriptor.
+ *
+ * Returns 0 on success, or returns -1 otherwise.
+ */
int eventfd_write(int __fd, eventfd_t __value);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/file.h b/libc/include/sys/file.h
index a420021..ccdfeea 100644
--- a/libc/include/sys/file.h
+++ b/libc/include/sys/file.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_FILE_H_
-#define _SYS_FILE_H_
+#pragma once
+
+/**
+ * @file sys/file.h
+ * @brief The flock() function.
+ */
#include <sys/cdefs.h>
#include <sys/types.h>
@@ -36,8 +40,12 @@
__BEGIN_DECLS
+/**
+ * [flock(2)](http://man7.org/linux/man-pages/man2/flock.2.html) performs
+ * advisory file lock operations.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ */
int flock(int __fd, int __op);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/fsuid.h b/libc/include/sys/fsuid.h
index bb7a58d..c1c8ebb 100644
--- a/libc/include/sys/fsuid.h
+++ b/libc/include/sys/fsuid.h
@@ -26,17 +26,36 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_FSUID_H_
-#define _SYS_FSUID_H_
+#pragma once
+
+/**
+ * @file sys/fsuid.h
+ * @brief Set UID/GID for filesystem checks.
+ */
#include <sys/cdefs.h>
#include <sys/types.h>
__BEGIN_DECLS
+/**
+ * [setfsuid(2)](http://man7.org/linux/man-pages/man2/setfsuid.2.html) sets the UID used for
+ * filesystem checks.
+ *
+ * Returns the previous UID.
+ *
+ * Available since API level 21.
+ */
int setfsuid(uid_t __uid) __INTRODUCED_IN(21);
+
+/**
+ * [setfsgid(2)](http://man7.org/linux/man-pages/man2/setfsgid.2.html) sets the GID used for
+ * filesystem checks.
+ *
+ * Returns the previous GID.
+ *
+ * Available since API level 21.
+ */
int setfsgid(gid_t __gid) __INTRODUCED_IN(21);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/ioctl.h b/libc/include/sys/ioctl.h
index b48b7f9..178de4a 100644
--- a/libc/include/sys/ioctl.h
+++ b/libc/include/sys/ioctl.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_IOCTL_H_
-#define _SYS_IOCTL_H_
+#pragma once
+
+/**
+ * @file sys/ioctl.h
+ * @brief The ioctl() function.
+ */
#include <sys/cdefs.h>
#include <linux/ioctl.h>
@@ -39,5 +43,3 @@
#include <linux/tty.h>
#include <bits/ioctl.h>
-
-#endif
diff --git a/libc/include/sys/ipc.h b/libc/include/sys/ipc.h
index dee7c8a..c81ec1a 100644
--- a/libc/include/sys/ipc.h
+++ b/libc/include/sys/ipc.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_IPC_H
-#define _SYS_IPC_H
+#pragma once
+
+/**
+ * @file sys/ipc.h
+ * @brief System V IPC.
+ */
#include <sys/cdefs.h>
#include <sys/types.h>
@@ -42,8 +46,12 @@
__BEGIN_DECLS
+/**
+ * [ftok(3)](http://man7.org/linux/man-pages/man3/ftok.3.html) converts a path and id to a
+ * System V IPC key.
+ *
+ * Returns a key on success, and returns -1 and sets `errno` on failure.
+ */
key_t ftok(const char* __path, int __id);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/klog.h b/libc/include/sys/klog.h
index ed746fc..b33d11b 100644
--- a/libc/include/sys/klog.h
+++ b/libc/include/sys/klog.h
@@ -26,28 +26,46 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_KLOG_H_
-#define _SYS_KLOG_H_
+#pragma once
+
+/**
+ * @file sys/klog.h
+ * @brief
+ */
#include <sys/cdefs.h>
__BEGIN_DECLS
-/* These correspond to the kernel's SYSLOG_ACTION_whatever constants. */
-#define KLOG_CLOSE 0
-#define KLOG_OPEN 1
-#define KLOG_READ 2
-#define KLOG_READ_ALL 3
-#define KLOG_READ_CLEAR 4
-#define KLOG_CLEAR 5
-#define KLOG_CONSOLE_OFF 6
-#define KLOG_CONSOLE_ON 7
+/** Used with klogctl(). */
+#define KLOG_CLOSE 0
+/** Used with klogctl(). */
+#define KLOG_OPEN 1
+/** Used with klogctl(). */
+#define KLOG_READ 2
+/** Used with klogctl(). */
+#define KLOG_READ_ALL 3
+/** Used with klogctl(). */
+#define KLOG_READ_CLEAR 4
+/** Used with klogctl(). */
+#define KLOG_CLEAR 5
+/** Used with klogctl(). */
+#define KLOG_CONSOLE_OFF 6
+/** Used with klogctl(). */
+#define KLOG_CONSOLE_ON 7
+/** Used with klogctl(). */
#define KLOG_CONSOLE_LEVEL 8
-#define KLOG_SIZE_UNREAD 9
-#define KLOG_SIZE_BUFFER 10
+/** Used with klogctl(). */
+#define KLOG_SIZE_UNREAD 9
+/** Used with klogctl(). */
+#define KLOG_SIZE_BUFFER 10
+/**
+ * [klogctl(2)](http://man7.org/linux/man-pages/man2/syslog.2.html) operates on the kernel log.
+ *
+ * This system call is not available to applications.
+ * Use syslog() or `<android/log.h>` instead.
+ */
int klogctl(int __type, char* __buf, int __buf_size);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/mount.h b/libc/include/sys/mount.h
index c0c084b..4db1ac1 100644
--- a/libc/include/sys/mount.h
+++ b/libc/include/sys/mount.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_MOUNT_H
-#define _SYS_MOUNT_H
+#pragma once
+
+/**
+ * @file sys/mount.h
+ * @brief Mounting and unmounting filesystems.
+ */
#include <sys/cdefs.h>
#include <sys/ioctl.h>
@@ -35,16 +39,38 @@
__BEGIN_DECLS
-/* umount2 flags. */
+/** The umount2() flag to force unmounting. */
#define MNT_FORCE 1
+/** The umount2() flag to lazy unmount. */
#define MNT_DETACH 2
+/** The umount2() flag to mark a mount point as expired. */
#define MNT_EXPIRE 4
+
+/** The umount2() flag to not dereference the mount point path if it's a symbolic link. */
#define UMOUNT_NOFOLLOW 8
+/**
+ * [mount(2)](http://man7.org/linux/man-pages/man2/mount.2.html) mounts the filesystem `source` at
+ * the mount point `target`.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ */
int mount(const char* __source, const char* __target, const char* __fs_type, unsigned long __flags, const void* __data);
+
+/**
+ * [umount(2)](http://man7.org/linux/man-pages/man2/umount.2.html) unmounts the filesystem at
+ * the given mount point.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ */
int umount(const char* __target);
+
+/**
+ * [umount2(2)](http://man7.org/linux/man-pages/man2/umount2.2.html) unmounts the filesystem at
+ * the given mount point, according to the supplied flags.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ */
int umount2(const char* __target, int __flags);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/msg.h b/libc/include/sys/msg.h
index 0273499..e19452c 100644
--- a/libc/include/sys/msg.h
+++ b/libc/include/sys/msg.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_MSG_H_
-#define _SYS_MSG_H_
+#pragma once
+
+/**
+ * @file sys/msg.h
+ * @brief System V message queues. Not useful on Android because it's disallowed by SELinux.
+ */
#include <sys/cdefs.h>
#include <sys/ipc.h>
@@ -41,11 +45,13 @@
typedef __kernel_ulong_t msgqnum_t;
typedef __kernel_ulong_t msglen_t;
+/** Not useful on Android; disallowed by SELinux. */
int msgctl(int __msg_id, int __cmd, struct msqid_ds* __buf) __INTRODUCED_IN(26);
+/** Not useful on Android; disallowed by SELinux. */
int msgget(key_t __key, int __flags) __INTRODUCED_IN(26);
+/** Not useful on Android; disallowed by SELinux. */
ssize_t msgrcv(int __msg_id, void* __msgbuf_ptr, size_t __size, long __type, int __flags) __INTRODUCED_IN(26);
+/** Not useful on Android; disallowed by SELinux. */
int msgsnd(int __msg_id, const void* __msgbuf_ptr, size_t __size, int __flags) __INTRODUCED_IN(26);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/param.h b/libc/include/sys/param.h
index ec50da2..4a83e9d 100644
--- a/libc/include/sys/param.h
+++ b/libc/include/sys/param.h
@@ -26,27 +26,34 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_PARAM_H_
-#define _SYS_PARAM_H_
+#pragma once
+
+/**
+ * @file sys/param.h
+ * @brief Various macros.
+ */
#include <limits.h>
#include <linux/param.h>
#include <sys/cdefs.h>
+/** The unit of `st_blocks` in `struct stat`. */
#define DEV_BSIZE 512
+/** A historical name for PATH_MAX. */
#define MAXPATHLEN PATH_MAX
+
#define MAXSYMLINKS 8
-/* Macros for counting and rounding. */
#ifndef howmany
#define howmany(x, y) (((x)+((y)-1))/(y))
#endif
#define roundup(x, y) ((((x)+((y)-1))/(y))*(y))
-#define powerof2(x) ((((x)-1)&(x))==0)
-/* Macros for min/max. */
+/** Returns true if the argument is a power of two. */
+#define powerof2(x) ((((x)-1)&(x))==0)
+
+/** Returns the lesser of its two arguments. */
#define MIN(a,b) (((a)<(b))?(a):(b))
+/** Returns the greater of its two arguments. */
#define MAX(a,b) (((a)>(b))?(a):(b))
-
-#endif
diff --git a/libc/include/sys/personality.h b/libc/include/sys/personality.h
index 51b5cd7..cea0bf8 100644
--- a/libc/include/sys/personality.h
+++ b/libc/include/sys/personality.h
@@ -26,16 +26,26 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_PERSONALITY_H_
-#define _SYS_PERSONALITY_H_
+#pragma once
+
+/**
+ * @file sys/personality.h
+ * @brief The personality() function.
+ */
#include <sys/cdefs.h>
#include <linux/personality.h>
__BEGIN_DECLS
+/**
+ * [personality(2)](http://man7.org/linux/man-pages/man2/personality.2.html) sets the calling
+ * process' personality.
+ *
+ * Returns the previous persona on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 15.
+ */
int personality(unsigned int __persona) __INTRODUCED_IN(15);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/quota.h b/libc/include/sys/quota.h
index 157c2d9..f8faee7 100644
--- a/libc/include/sys/quota.h
+++ b/libc/include/sys/quota.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_QUOTA_H_
-#define _SYS_QUOTA_H_
+#pragma once
+
+/**
+ * @file sys/quota.h
+ * @brief The quotactl() function.
+ */
#include <sys/cdefs.h>
@@ -40,8 +44,13 @@
__BEGIN_DECLS
+/**
+ * [quotactl(2)](http://man7.org/linux/man-pages/man2/quotactl.2.html) manipulates disk quotas.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 26.
+ */
int quotactl(int __cmd, const char* __special, int __id, char* __addr) __INTRODUCED_IN(26);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/random.h b/libc/include/sys/random.h
index 4b849f3..be52bd9 100644
--- a/libc/include/sys/random.h
+++ b/libc/include/sys/random.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_RANDOM_H_
-#define _SYS_RANDOM_H_
+#pragma once
+
+/**
+ * @file sys/random.h
+ * @brief The getentropy() and getrandom() functions.
+ */
#include <sys/cdefs.h>
#include <sys/types.h>
@@ -36,12 +40,28 @@
__BEGIN_DECLS
-/* See also arc4random_buf in <stdlib.h>, which is available in all API levels. */
-
+/**
+ * [getentropy(3)](http://man7.org/linux/man-pages/man3/getentropy.3.html) fills the given buffer
+ * with random bytes.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 28.
+ *
+ * See also arc4random_buf() which is available in all API levels.
+ */
int getentropy(void* __buffer, size_t __buffer_size) __wur __INTRODUCED_IN(28);
+/**
+ * [getrandom(2)](http://man7.org/linux/man-pages/man2/getrandom.2.html) fills the given buffer
+ * with random bytes.
+ *
+ * Returns the number of bytes copied on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 28.
+ *
+ * See also arc4random_buf() which is available in all API levels.
+ */
ssize_t getrandom(void* __buffer, size_t __buffer_size, unsigned int __flags) __wur __INTRODUCED_IN(28);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/reboot.h b/libc/include/sys/reboot.h
index c0c4860..156d947 100644
--- a/libc/include/sys/reboot.h
+++ b/libc/include/sys/reboot.h
@@ -26,24 +26,35 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_REBOOT_H_
-#define _SYS_REBOOT_H_
+#pragma once
+
+/**
+ * @file sys/reboot.h
+ * @brief The reboot() function.
+ */
#include <sys/cdefs.h>
#include <linux/reboot.h>
__BEGIN_DECLS
-/* use glibc names as well */
+/** The glibc name for the reboot() flag `LINUX_REBOOT_CMD_RESTART`. */
+#define RB_AUTOBOOT LINUX_REBOOT_CMD_RESTART
+/** The glibc name for the reboot() flag `LINUX_REBOOT_CMD_HALT`. */
+#define RB_HALT_SYSTEM LINUX_REBOOT_CMD_HALT
+/** The glibc name for the reboot() flag `LINUX_REBOOT_CMD_CAD_ON`. */
+#define RB_ENABLE_CAD LINUX_REBOOT_CMD_CAD_ON
+/** The glibc name for the reboot() flag `LINUX_REBOOT_CMD_CAD_OFF`. */
+#define RB_DISABLE_CAD LINUX_REBOOT_CMD_CAD_OFF
+/** The glibc name for the reboot() flag `LINUX_REBOOT_CMD_POWER_OFF`. */
+#define RB_POWER_OFF LINUX_REBOOT_CMD_POWER_OFF
-#define RB_AUTOBOOT LINUX_REBOOT_CMD_RESTART
-#define RB_HALT_SYSTEM LINUX_REBOOT_CMD_HALT
-#define RB_ENABLE_CAD LINUX_REBOOT_CMD_CAD_ON
-#define RB_DISABLE_CAD LINUX_REBOOT_CMD_CAD_OFF
-#define RB_POWER_OFF LINUX_REBOOT_CMD_POWER_OFF
-
+/**
+ * [reboot(2)](http://man7.org/linux/man-pages/man2/reboot.2.html) reboots the device.
+ *
+ * Does not return on successful reboot, returns 0 if CAD was successfully enabled/disabled,
+ * and returns -1 and sets `errno` on failure.
+ */
int reboot(int __cmd);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/sendfile.h b/libc/include/sys/sendfile.h
index 97432c0..60bbde8 100644
--- a/libc/include/sys/sendfile.h
+++ b/libc/include/sys/sendfile.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_SENDFILE_H_
-#define _SYS_SENDFILE_H_
+#pragma once
+
+/**
+ * @file sys/sendfile.h
+ * @brief The sendfile() function.
+ */
#include <sys/cdefs.h>
#include <sys/types.h>
@@ -38,10 +42,21 @@
#if defined(__USE_FILE_OFFSET64)
ssize_t sendfile(int __out_fd, int __in_fd, off_t* __offset, size_t __count) __RENAME(sendfile64) __INTRODUCED_IN(21);
#else
+/**
+ * [sendfile(2)](http://man7.org/linux/man-pages/man2/sendfile.2.html) copies data directly
+ * between two file descriptors.
+ *
+ * Returns the number of bytes copied on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 21.
+ */
ssize_t sendfile(int __out_fd, int __in_fd, off_t* __offset, size_t __count);
#endif
+
+/**
+ * Like sendfile() but allows using a 64-bit offset
+ * even from a 32-bit process without `__FILE_OFFSET_BITS=64`.
+ */
ssize_t sendfile64(int __out_fd, int __in_fd, off64_t* __offset, size_t __count) __INTRODUCED_IN(21);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/shm.h b/libc/include/sys/shm.h
index 4723eba..a3f84d3 100644
--- a/libc/include/sys/shm.h
+++ b/libc/include/sys/shm.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_SHM_H_
-#define _SYS_SHM_H_
+#pragma once
+
+/**
+ * @file sys/shm.h
+ * @brief System V shared memory. Not useful on Android because it's disallowed by SELinux.
+ */
#include <sys/cdefs.h>
#include <sys/ipc.h>
@@ -42,11 +46,13 @@
typedef unsigned long shmatt_t;
+/** Not useful on Android; disallowed by SELinux. */
void* shmat(int __shm_id, const void* __addr, int __flags) __INTRODUCED_IN(26);
+/** Not useful on Android; disallowed by SELinux. */
int shmctl(int __shm_id, int __cmd, struct shmid_ds* __buf) __INTRODUCED_IN(26);
+/** Not useful on Android; disallowed by SELinux. */
int shmdt(const void* __addr) __INTRODUCED_IN(26);
+/** Not useful on Android; disallowed by SELinux. */
int shmget(key_t __key, size_t __size, int __flags) __INTRODUCED_IN(26);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/signalfd.h b/libc/include/sys/signalfd.h
index 2337cd7..bd911f7 100644
--- a/libc/include/sys/signalfd.h
+++ b/libc/include/sys/signalfd.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_SIGNALFD_H_
-#define _SYS_SIGNALFD_H_
+#pragma once
+
+/**
+ * @file sys/signalfd.h
+ * @brief File-descriptor based signal interface.
+ */
#include <sys/cdefs.h>
@@ -36,9 +40,19 @@
__BEGIN_DECLS
+/**
+ * [signalfd(2)](http://man7.org/linux/man-pages/man2/signalfd.2.html) creates/manipulates a
+ * file descriptor for reading signal events.
+ *
+ * Returns the file descriptor on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 18.
+ */
int signalfd(int __fd, const sigset_t* __mask, int __flags) __INTRODUCED_IN(18);
+
+/**
+ * Like signalfd() but allows setting a signal mask with RT signals even from a 32-bit process.
+ */
int signalfd64(int __fd, const sigset64_t* __mask, int __flags) __INTRODUCED_IN(28);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/swap.h b/libc/include/sys/swap.h
index 8a30cce..467b98c 100644
--- a/libc/include/sys/swap.h
+++ b/libc/include/sys/swap.h
@@ -26,21 +26,47 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_SWAP_H_
-#define _SYS_SWAP_H_
+#pragma once
+
+/**
+ * @file sys/swap.h
+ * @brief Swap control.
+ */
#include <sys/cdefs.h>
__BEGIN_DECLS
+/** swapon() flag to discard pages. */
#define SWAP_FLAG_DISCARD 0x10000
+
+/**
+ * swapon() flag to give this swap area a non-default priority.
+ * The priority is also encoded in the flags:
+ * `(priority << SWAP_FLAG_PRIO_SHIFT) & SWAP_FLAG_PRIO_MASK`.
+ */
#define SWAP_FLAG_PREFER 0x8000
+/** See SWAP_FLAG_PREFER. */
#define SWAP_FLAG_PRIO_MASK 0x7fff
+/** See SWAP_FLAG_PREFER. */
#define SWAP_FLAG_PRIO_SHIFT 0
+/**
+ * [swapon(2)](http://man7.org/linux/man-pages/man2/swapon.2.html) enables swapping.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 19.
+ */
int swapon(const char* __path, int __flags) __INTRODUCED_IN(19);
+
+/**
+ * [swapoff(2)](http://man7.org/linux/man-pages/man2/swapoff.2.html) disables swapping.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 19.
+ */
int swapoff(const char* __path) __INTRODUCED_IN(19);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/sysinfo.h b/libc/include/sys/sysinfo.h
index 6da02ee..4ecf986 100644
--- a/libc/include/sys/sysinfo.h
+++ b/libc/include/sys/sysinfo.h
@@ -26,20 +26,63 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_SYSINFO_H_
-#define _SYS_SYSINFO_H_
+#pragma once
+
+/**
+ * @file sys/sysinfo.h
+ * @brief System information.
+ */
#include <sys/cdefs.h>
#include <linux/kernel.h>
__BEGIN_DECLS
+/**
+ * [sysinfo(2)](http://man7.org/linux/man-pages/man2/sysinfo.2.html) queries system information.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ */
int sysinfo(struct sysinfo* __info);
+
+/**
+ * [get_nprocs_conf(3)](http://man7.org/linux/man-pages/man3/get_nprocs_conf.3.html) returns
+ * the total number of processors in the system.
+ *
+ * Available since API level 23.
+ *
+ * See also sysconf().
+ */
int get_nprocs_conf(void) __INTRODUCED_IN(23);
+
+/**
+ * [get_nprocs(3)](http://man7.org/linux/man-pages/man3/get_nprocs.3.html) returns
+ * the number of processors in the system that are currently on-line.
+ *
+ * Available since API level 23.
+ *
+ * See also sysconf().
+ */
int get_nprocs(void) __INTRODUCED_IN(23);
+
+/**
+ * [get_phys_pages(3)](http://man7.org/linux/man-pages/man3/get_phys_pages.3.html) returns
+ * the total number of physical pages in the system.
+ *
+ * Available since API level 23.
+ *
+ * See also sysconf().
+ */
long get_phys_pages(void) __INTRODUCED_IN(23);
+
+/**
+ * [get_avphys_pages(3)](http://man7.org/linux/man-pages/man3/get_avphys_pages.3.html) returns
+ * the number of physical pages in the system that are currently available.
+ *
+ * Available since API level 23.
+ *
+ * See also sysconf().
+ */
long get_avphys_pages(void) __INTRODUCED_IN(23);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/sysmacros.h b/libc/include/sys/sysmacros.h
index 592cc5e..64cf289 100644
--- a/libc/include/sys/sysmacros.h
+++ b/libc/include/sys/sysmacros.h
@@ -26,21 +26,26 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_SYSMACROS_H_
-#define _SYS_SYSMACROS_H_
+#pragma once
+
+/**
+ * @file sys/sysmacros.h
+ * @brief Major/minor device number macros.
+ */
#include <sys/cdefs.h>
+/** Combines `major` and `minor` into a device number. */
#define makedev(__major, __minor) \
( \
(((__major) & 0xfffff000ULL) << 32) | (((__major) & 0xfffULL) << 8) | \
(((__minor) & 0xffffff00ULL) << 12) | (((__minor) & 0xffULL)) \
)
+/** Extracts the major part of a device number. */
#define major(__dev) \
((unsigned) ((((unsigned long long) (__dev) >> 32) & 0xfffff000) | (((__dev) >> 8) & 0xfff)))
+/** Extracts the minor part of a device number. */
#define minor(__dev) \
((unsigned) ((((__dev) >> 12) & 0xffffff00) | ((__dev) & 0xff)))
-
-#endif /* _SYS_SYSMACROS_H_ */
diff --git a/libc/include/sys/timerfd.h b/libc/include/sys/timerfd.h
index 7bf675b..b89941b 100644
--- a/libc/include/sys/timerfd.h
+++ b/libc/include/sys/timerfd.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_TIMERFD_H_
-#define _SYS_TIMERFD_H_
+#pragma once
+
+/**
+ * @file sys/timerfd.h
+ * @brief Timer file descriptors.
+ */
#include <fcntl.h> /* For O_CLOEXEC and O_NONBLOCK. */
#include <time.h>
@@ -36,16 +40,44 @@
__BEGIN_DECLS
-#define TFD_TIMER_ABSTIME (1 << 0)
-#define TFD_TIMER_CANCEL_ON_SET (1 << 1)
-
+/** The timerfd_create() flag for a close-on-exec file descriptor. */
#define TFD_CLOEXEC O_CLOEXEC
+/** The timerfd_create() flag for a non-blocking file descriptor. */
#define TFD_NONBLOCK O_NONBLOCK
+/**
+ * [timerfd_create(2)](http://man7.org/linux/man-pages/man2/timerfd_create.2.html) creates a
+ * timer file descriptor.
+ *
+ * Returns the new file descriptor on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 19.
+ */
int timerfd_create(clockid_t __clock, int __flags) __INTRODUCED_IN(19);
+
+/** The timerfd_settime() flag to use absolute rather than relative times. */
+#define TFD_TIMER_ABSTIME (1 << 0)
+/** The timerfd_settime() flag to cancel an absolute timer if the realtime clock changes. */
+#define TFD_TIMER_CANCEL_ON_SET (1 << 1)
+
+/**
+ * [timerfd_settime(2)](http://man7.org/linux/man-pages/man2/timerfd_settime.2.html) starts or
+ * stops a timer.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 19.
+ */
int timerfd_settime(int __fd, int __flags, const struct itimerspec* __new_value, struct itimerspec* __old_value) __INTRODUCED_IN(19);
+
+/**
+ * [timerfd_gettime(2)](http://man7.org/linux/man-pages/man2/timerfd_gettime.2.html) queries the
+ * current timer settings.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 19.
+ */
int timerfd_gettime(int __fd, struct itimerspec* __current_value) __INTRODUCED_IN(19);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/times.h b/libc/include/sys/times.h
index 3c8a4ef..25d03e3 100644
--- a/libc/include/sys/times.h
+++ b/libc/include/sys/times.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_TIMES_H_
-#define _SYS_TIMES_H_
+#pragma once
+
+/**
+ * @file sys/times.h
+ * @brief The times() function.
+ */
#include <sys/cdefs.h>
#include <sys/types.h>
@@ -35,8 +39,13 @@
__BEGIN_DECLS
+/**
+ * [times(2)](http://man7.org/linux/man-pages/man2/times.2.html) fills a buffer with the
+ * calling process' CPU usage.
+ *
+ * Returns a (possibly overflowed) absolute time on success,
+ * and returns -1 and sets `errno` on failure.
+ */
clock_t times(struct tms* __buf);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/timex.h b/libc/include/sys/timex.h
index 74c8611..52db5dc 100644
--- a/libc/include/sys/timex.h
+++ b/libc/include/sys/timex.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_TIMEX_H_
-#define _SYS_TIMEX_H_
+#pragma once
+
+/**
+ * @file sys/timex.h
+ * @brief Kernel clock tuning.
+ */
#include <sys/cdefs.h>
#include <sys/types.h>
@@ -35,9 +39,22 @@
__BEGIN_DECLS
+/**
+ * [adjtimex(2)](http://man7.org/linux/man-pages/man2/adjtimex.2.html) adjusts the kernel clock.
+ *
+ * Returns the clock state on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 24.
+ */
int adjtimex(struct timex* __buf) __INTRODUCED_IN(24);
+
+/**
+ * clock_adjtime adjusts a specific kernel clock.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 24.
+ */
int clock_adjtime(clockid_t __clock, struct timex* __tx) __INTRODUCED_IN(24);
__END_DECLS
-
-#endif
diff --git a/libc/include/sys/un.h b/libc/include/sys/un.h
index 03ef5e4..83c1d17 100644
--- a/libc/include/sys/un.h
+++ b/libc/include/sys/un.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_UN_H_
-#define _SYS_UN_H_
+#pragma once
+
+/**
+ * @file sys/un.h
+ * @brief Unix domain sockets.
+ */
#include <bits/sa_family_t.h>
#include <linux/un.h>
@@ -35,7 +39,6 @@
#if defined(__USE_BSD) || defined(__USE_GNU)
#include <string.h>
+/** Returns the actual length of the given `sockaddr_un`. */
#define SUN_LEN(__ptr) (offsetof(struct sockaddr_un, sun_path) + strlen((__ptr)->sun_path))
#endif
-
-#endif
diff --git a/libc/include/sys/utsname.h b/libc/include/sys/utsname.h
index 2420fb4..1fa3187 100644
--- a/libc/include/sys/utsname.h
+++ b/libc/include/sys/utsname.h
@@ -26,26 +26,42 @@
* SUCH DAMAGE.
*/
-#ifndef _SYS_UTSNAME_H_
-#define _SYS_UTSNAME_H_
+#pragma once
+
+/**
+ * @file sys/utsname.h
+ * @brief The uname() function.
+ */
#include <sys/cdefs.h>
__BEGIN_DECLS
+/** The maximum length of any field in `struct utsname`. */
#define SYS_NMLN 65
+/** The information returned by uname(). */
struct utsname {
+ /** The OS name. "Linux" on Android. */
char sysname[SYS_NMLN];
+ /** The name on the network. Typically "localhost" on Android. */
char nodename[SYS_NMLN];
+ /** The OS release. Typically something like "4.4.115-g442ad7fba0d" on Android. */
char release[SYS_NMLN];
+ /** The OS version. Typically something like "#1 SMP PREEMPT" on Android. */
char version[SYS_NMLN];
+ /** The hardware architecture. Typically "aarch64" on Android. */
char machine[SYS_NMLN];
+ /** The domain name set by setdomainname(). Typically "localdomain" on Android. */
char domainname[SYS_NMLN];
};
+/**
+ * [uname(2)](http://man7.org/linux/man-pages/man2/uname.2.html) returns information
+ * about the kernel.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ */
int uname(struct utsname* __buf);
__END_DECLS
-
-#endif