Add documentation for a couple of pthread functions.
These cause great confusion, so explicitly point out that apps can't use
one, and probably want the other.
Bug: https://github.com/android/ndk/issues/1255
Test: N/A
Change-Id: I287e820dc45a8446e3c72c9a2e4007db76828e3b
diff --git a/libc/include/pthread.h b/libc/include/pthread.h
index 8bc897a..22f949b 100644
--- a/libc/include/pthread.h
+++ b/libc/include/pthread.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _PTHREAD_H_
-#define _PTHREAD_H_
+#pragma once
+
+/**
+ * @file pthread.h
+ * @brief POSIX threads.
+ */
#include <limits.h>
#include <bits/pthread_types.h>
@@ -165,8 +169,6 @@
int pthread_getcpuclockid(pthread_t __pthread, clockid_t* __clock);
-int pthread_getschedparam(pthread_t __pthread, int* __policy, struct sched_param* __param);
-
void* pthread_getspecific(pthread_key_t __key);
pid_t pthread_gettid_np(pthread_t __pthread) __INTRODUCED_IN(21);
@@ -283,7 +285,40 @@
/* TODO: this should be __USE_GNU too. */
int pthread_setname_np(pthread_t __pthread, const char* __name);
+/**
+ * [pthread_setschedparam(3)](https://man7.org/linux/man-pages/man3/pthread_setschedparam.3.html)
+ * sets the scheduler policy and parameters of the given thread.
+ *
+ * This call is not useful to applications on Android, because they don't
+ * have permission to set their scheduling policy, and the only priority
+ * for their policy is 0 anyway. If you only need to set your scheduling
+ * priority, see setpriority() instead.
+ *
+ * Returns 0 on success and returns an error number on failure.
+ */
int pthread_setschedparam(pthread_t __pthread, int __policy, const struct sched_param* __param);
+
+/**
+ * [pthread_getschedparam(3)](https://man7.org/linux/man-pages/man3/pthread_getschedparam.3.html)
+ * gets the scheduler policy and parameters of the given thread.
+ *
+ * Returns 0 on success and returns an error number on failure.
+ */
+int pthread_getschedparam(pthread_t __pthread, int* __policy, struct sched_param* __param);
+
+/**
+ * [pthread_setschedprio(3)](https://man7.org/linux/man-pages/man3/pthread_setschedprio.3.html)
+ * sets the scheduler priority of the given thread.
+ *
+ * This call is not useful to applications on Android, because they don't
+ * have permission to set their scheduling policy, and the only priority
+ * for their policy is 0 anyway. If you only need to set your scheduling
+ * priority, see setpriority() instead.
+ *
+ * Returns 0 on success and returns an error number on failure.
+ *
+ * Available since API level 28.
+ */
int pthread_setschedprio(pthread_t __pthread, int __priority) __INTRODUCED_IN(28);
int pthread_setspecific(pthread_key_t __key, const void* __value);
@@ -315,5 +350,3 @@
} while (0); \
__END_DECLS
-
-#endif