pthread: Implemented POSIX unnamed semaphore

docs/en/api-reference/system/pthread.rst

@@ -98,6 +98,30 @@ Static initializer constant ``PTHREAD_COND_INITIALIZER`` is supported.
 
 .. note:: These functions can be called from tasks created using either pthread or FreeRTOS APIs
 
+Semaphores
+^^^^^^^^^^
+
+In IDF, POSIX *unnamed* semaphores are implemented. The accessible API is described below. It implements `semaphores as specified in the POSIX standard <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/semaphore.h.html>`_, unless specified otherwise.
+
+* `sem_init() <https://pubs.opengroup.org/onlinepubs/9699919799/functions/sem_init.html>`_
+* `sem_destroy() <https://pubs.opengroup.org/onlinepubs/9699919799/functions/sem_destroy.html>`_
+
+  - ``pshared`` is ignored. Semaphores can always be shared between FreeRTOS tasks.
+
+* `sem_post() <https://pubs.opengroup.org/onlinepubs/9699919799/functions/sem_post.html>`_
+
+  - If the semaphore has a value of ``SEM_VALUE_MAX`` already, -1 is returned and ``errno`` is set to ``EAGAIN``.
+
+* `sem_wait() <https://pubs.opengroup.org/onlinepubs/9699919799/functions/sem_wait.html>`_
+* `sem_trywait() <https://pubs.opengroup.org/onlinepubs/9699919799/functions/sem_trywait.html>`_
+* `sem_timedwait() <https://pubs.opengroup.org/onlinepubs/9699919799/functions/sem_timedwait.html>`_
+
+  - The time value passed by abstime will be rounded up to the next FreeRTOS tick. 
+  - The actual timeout will happen after the tick the time was rounded to and before the following tick.
+  - It is possible, though unlikely, that the task is preempted directly after the timeout calculation, delaying the timeout of the following blocking operating system call by the duration of the preemption.
+
+* `sem_getvalue() <https://pubs.opengroup.org/onlinepubs/9699919799/functions/sem_getvalue.html>`_
+
 Read/Write Locks
 ^^^^^^^^^^^^^^^^^^^
 
@@ -160,4 +184,3 @@ API Reference
 -------------
 
 .. include-build-file:: inc/esp_pthread.inc
-