From 9c6017778bdc41a9c224c7f606f72195e666e36b Mon Sep 17 00:00:00 2001
From: Elliott Hughes <enh@google.com>
Date: Tue, 28 Aug 2018 12:17:20 -0700
Subject: [PATCH] Document the set*id functions.

In particular, document the fact that they only affect the calling thread
on Android.

Bug: http://b/13134174
Test: ran tests
Change-Id: Ica6af451400d47e24358f59495ded63b2110eb8b
---
 libc/include/unistd.h | 107 ++++++++++++++++++++++++++++++++++++------
 1 file changed, 93 insertions(+), 14 deletions(-)

diff --git a/libc/include/unistd.h b/libc/include/unistd.h
index e0f8b4396..90173aa29 100644
--- a/libc/include/unistd.h
+++ b/libc/include/unistd.h
@@ -26,8 +26,7 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _UNISTD_H_
-#define _UNISTD_H_
+#pragma once
 
 #include <stddef.h>
 #include <sys/cdefs.h>
@@ -102,20 +101,100 @@ int fexecve(int __fd, char* const* __argv, char* const* __envp) __INTRODUCED_IN(
 
 int nice(int __incr);
 
-int setuid(uid_t __uid);
-uid_t getuid(void);
-int seteuid(uid_t __uid);
-uid_t geteuid(void);
-int setgid(gid_t __gid);
-gid_t getgid(void);
+/**
+ * [setegid(2)](http://man7.org/linux/man-pages/man2/setegid.2.html) sets
+ * the effective group ID.
+ *
+ * On Android, this function only affects the calling thread, not all threads
+ * in the process.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ */
 int setegid(gid_t __gid);
+
+/**
+ * [seteuid(2)](http://man7.org/linux/man-pages/man2/seteuid.2.html) sets
+ * the effective user ID.
+ *
+ * On Android, this function only affects the calling thread, not all threads
+ * in the process.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ */
+int seteuid(uid_t __uid);
+
+/**
+ * [setgid(2)](http://man7.org/linux/man-pages/man2/setgid.2.html) sets
+ * the group ID.
+ *
+ * On Android, this function only affects the calling thread, not all threads
+ * in the process.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ */
+int setgid(gid_t __gid);
+
+/**
+ * [setregid(2)](http://man7.org/linux/man-pages/man2/setregid.2.html) sets
+ * the real and effective group IDs (use -1 to leave an ID unchanged).
+ *
+ * On Android, this function only affects the calling thread, not all threads
+ * in the process.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ */
+int setregid(gid_t __rgid, gid_t __egid);
+
+/**
+ * [setresgid(2)](http://man7.org/linux/man-pages/man2/setresgid.2.html) sets
+ * the real, effective, and saved group IDs (use -1 to leave an ID unchanged).
+ *
+ * On Android, this function only affects the calling thread, not all threads
+ * in the process.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ */
+int setresgid(gid_t __rgid, gid_t __egid, gid_t __sgid);
+
+/**
+ * [setresuid(2)](http://man7.org/linux/man-pages/man2/setresuid.2.html) sets
+ * the real, effective, and saved user IDs (use -1 to leave an ID unchanged).
+ *
+ * On Android, this function only affects the calling thread, not all threads
+ * in the process.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ */
+int setresuid(uid_t __ruid, uid_t __euid, uid_t __suid);
+
+/**
+ * [setreuid(2)](http://man7.org/linux/man-pages/man2/setreuid.2.html) sets
+ * the real and effective group IDs (use -1 to leave an ID unchanged).
+ *
+ * On Android, this function only affects the calling thread, not all threads
+ * in the process.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ */
+int setreuid(uid_t __ruid, uid_t __euid);
+
+/**
+ * [setuid(2)](http://man7.org/linux/man-pages/man2/setuid.2.html) sets
+ * the user ID.
+ *
+ * On Android, this function only affects the calling thread, not all threads
+ * in the process.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ */
+int setuid(uid_t __uid);
+
+uid_t getuid(void);
+uid_t geteuid(void);
+gid_t getgid(void);
 gid_t getegid(void);
 int getgroups(int __size, gid_t* __list);
 int setgroups(size_t __size, const gid_t* __list);
-int setreuid(uid_t __ruid, uid_t __euid);
-int setregid(gid_t __rgid, gid_t __egid);
-int setresuid(uid_t __ruid, uid_t __euid, uid_t __suid);
-int setresgid(gid_t __rgid, gid_t __egid, gid_t __sgid);
 int getresuid(uid_t* __ruid, uid_t* __euid, uid_t* __suid);
 int getresgid(gid_t* __rgid, gid_t* __egid, gid_t* __sgid);
 char* getlogin(void);
@@ -239,9 +318,9 @@ int setdomainname(const char* __name, size_t __n) __INTRODUCED_IN(26);
 void swab(const void* __src, void* __dst, ssize_t __byte_count) __INTRODUCED_IN(28);
 
 #if defined(__BIONIC_INCLUDE_FORTIFY_HEADERS)
+#define _UNISTD_H_
 #include <bits/fortify/unistd.h>
+#undef _UNISTD_H_
 #endif
 
 __END_DECLS
-
-#endif