From d4fd67ce69d395fd4a92db0033cff85eb90e8534 Mon Sep 17 00:00:00 2001
From: Elliott Hughes <enh@google.com>
Date: Wed, 30 Nov 2022 19:53:33 +0000
Subject: [PATCH] Add some missing "Available since" documentation.

Also fix formatting of `errno` in one function.

Test: treehugger
Change-Id: Ibf362bcd36c901dab2a422afe09e0f78011315aa
---
 libc/include/sys/mman.h | 17 +++++++++++++----
 libc/include/unistd.h   |  6 +++---
 2 files changed, 16 insertions(+), 7 deletions(-)

diff --git a/libc/include/sys/mman.h b/libc/include/sys/mman.h
index 9e865a3de..fea93329d 100644
--- a/libc/include/sys/mman.h
+++ b/libc/include/sys/mman.h
@@ -110,6 +110,8 @@ void* mremap(void* __old_addr, size_t __old_size, size_t __new_size, int __flags
  * [mlockall(2)](http://man7.org/linux/man-pages/man2/mlockall.2.html)
  * locks pages (preventing swapping).
  *
+ * Available since API level 17.
+ *
  * Returns 0 on success, and returns -1 and sets `errno` on failure.
  */
 int mlockall(int __flags) __INTRODUCED_IN(17);
@@ -118,6 +120,8 @@ int mlockall(int __flags) __INTRODUCED_IN(17);
  * [munlockall(2)](http://man7.org/linux/man-pages/man2/munlockall.2.html)
  * unlocks pages (allowing swapping).
  *
+ * Available since API level 17.
+ *
  * Returns 0 on success, and returns -1 and sets `errno` on failure.
  */
 int munlockall(void) __INTRODUCED_IN(17);
@@ -134,6 +138,8 @@ int mlock(const void* __addr, size_t __size);
  * [mlock2(2)](http://man7.org/linux/man-pages/man2/mlock.2.html)
  * locks pages (preventing swapping), with optional flags.
  *
+ * Available since API level 30.
+ *
  * Returns 0 on success, and returns -1 and sets `errno` on failure.
  */
 int mlock2(const void* __addr, size_t __size, int __flags) __INTRODUCED_IN(30);
@@ -167,12 +173,12 @@ int madvise(void* __addr, size_t __size, int __advice);
  * works just like madvise(2) but applies to the process specified by the given
  * PID file descriptor.
  *
- * Returns the number of bytes advised on success, and returns -1 and sets `errno` on failure.
- *
  * Available since API level 31. Its sibling process_mrelease() does not have a
  * libc wrapper and should be called using syscall() instead. Given the lack of
  * widespread applicability of this system call and the absence of wrappers in
  * other libcs, it was probably a mistake to have added this wrapper to bionic.
+ *
+ * Returns the number of bytes advised on success, and returns -1 and sets `errno` on failure.
  */
 ssize_t process_madvise(int __pid_fd, const struct iovec* __iov, size_t __count, int __advice, unsigned __flags) __INTRODUCED_IN(31);
 
@@ -182,6 +188,8 @@ ssize_t process_madvise(int __pid_fd, const struct iovec* __iov, size_t __count,
  * [memfd_create(2)](http://man7.org/linux/man-pages/man2/memfd_create.2.html)
  * creates an anonymous file.
  *
+ * Available since API level 30.
+ *
  * Returns an fd on success, and returns -1 and sets `errno` on failure.
  */
 int memfd_create(const char* __name, unsigned __flags) __INTRODUCED_IN(30);
@@ -216,9 +224,10 @@ int memfd_create(const char* __name, unsigned __flags) __INTRODUCED_IN(30);
  * [posix_madvise(3)](http://man7.org/linux/man-pages/man3/posix_madvise.3.html)
  * gives the kernel advice about future usage patterns.
  *
- * Returns 0 on success, and returns a positive error number on failure.
+ * Available since API level 23.
+ * See also madvise() which is available at all API levels.
  *
- * See also madvise() which has been available much longer.
+ * Returns 0 on success, and returns a positive error number on failure.
  */
 int posix_madvise(void* __addr, size_t __size, int __advice) __INTRODUCED_IN(23);
 
diff --git a/libc/include/unistd.h b/libc/include/unistd.h
index b5694b8c3..3efc9a291 100644
--- a/libc/include/unistd.h
+++ b/libc/include/unistd.h
@@ -317,10 +317,10 @@ int setdomainname(const char* __name, size_t __n) __INTRODUCED_IN(26);
  * [copy_file_range(2)](https://man7.org/linux/man-pages/man2/copy_file_range.2.html) copies
  * a range of data from one file descriptor to another.
  *
- * Returns the number of bytes copied on success, and returns -1 and sets  errno
- * on failure.
- *
  * Available since API level 34.
+ *
+ * Returns the number of bytes copied on success, and returns -1 and sets
+ * `errno` on failure.
  */
 ssize_t copy_file_range(int __fd_in, off64_t* __off_in, int __fd_out, off64_t* __off_out, size_t __length, unsigned int __flags) __INTRODUCED_IN(34);