summaryrefslogtreecommitdiffstats
path: root/posix_users/semaphore.rst
diff options
context:
space:
mode:
authorChris Johns <chrisj@rtems.org>2016-02-26 18:22:07 +1100
committerAmar Takhar <verm@darkbeer.org>2016-05-02 20:51:26 -0400
commitfa70fd20878e402610c263f129266593d31a0376 (patch)
treec609d33c7047b975cfe8e0ac0df020fb26dae255 /posix_users/semaphore.rst
parent238bf991f236b10fb544b4efad80bed0fb6aa394 (diff)
downloadrtems-docs-fa70fd20878e402610c263f129266593d31a0376.tar.bz2
POSIX User clean up.
Diffstat (limited to 'posix_users/semaphore.rst')
-rw-r--r--posix_users/semaphore.rst426
1 files changed, 232 insertions, 194 deletions
diff --git a/posix_users/semaphore.rst b/posix_users/semaphore.rst
index 47628df..71b1684 100644
--- a/posix_users/semaphore.rst
+++ b/posix_users/semaphore.rst
@@ -1,3 +1,7 @@
+.. COMMENT: COPYRIGHT (c) 1989-2008.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
Semaphore Manager
#################
@@ -9,25 +13,25 @@ semaphores. This manager is based on the POSIX 1003.1 standard.
The directives provided by the semaphore manager are:
-- ``sem_init`` - Initialize an unnamed semaphore
+- sem_init_ - Initialize an unnamed semaphore
-- ``sem_destroy`` - Destroy an unnamed semaphore
+- sem_destroy_ - Destroy an unnamed semaphore
-- ``sem_open`` - Open a named semaphore
+- sem_open_ - Open a named semaphore
-- ``sem_close`` - Close a named semaphore
+- sem_close_ - Close a named semaphore
-- ``sem_unlink`` - Remove a named semaphore
+- sem_unlink_ - Remove a named semaphore
-- ``sem_wait`` - Lock a semaphore
+- sem_wait_ - Lock a semaphore
-- ``sem_trywait`` - Lock a semaphore
+- sem_trywait_ - Lock a semaphore
-- ``sem_timedwait`` - Wait on a Semaphore for a Specified Time
+- sem_timedwait_ - Wait on a Semaphore for a Specified Time
-- ``sem_post`` - Unlock a semaphore
+- sem_post_ - Unlock a semaphore
-- ``sem_getvalue`` - Get the value of a semeaphore
+- sem_getvalue_ - Get the value of a semeaphore
Background
==========
@@ -51,7 +55,8 @@ semaphore, the tasks will be placed in the queue.
The ``sem_t`` structure is used to represent semaphores. It is passed as an
argument to the semaphore directives and is defined as follows:
-.. code:: c
+
+.. code-block:: c
typedef int sem_t;
@@ -71,17 +76,19 @@ Creating a semaphore with a limit on the count of 1 effectively restricts the
semaphore to being a binary semaphore. When the binary semaphore is available,
the count is 1. When the binary semaphore is unavailable, the count is 0.
-Since this does not result in a true binary semaphore, advanced binary features like the Priority Inheritance and Priority Ceiling Protocols are not available.
+Since this does not result in a true binary semaphore, advanced binary features
+like the Priority Inheritance and Priority Ceiling Protocols are not available.
There is currently no text in this section.
Directives
==========
-This section details the semaphore manager's directives.
-A subsection is dedicated to each of this manager's directives
-and describes the calling sequence, related constants, usage,
-and status codes.
+This section details the semaphore manager's directives. A subsection is
+dedicated to each of this manager's directives and describes the calling
+sequence, related constants, usage, and status codes.
+
+.. _sem_init:
sem_init - Initialize an unnamed semaphore
------------------------------------------
@@ -90,45 +97,47 @@ sem_init - Initialize an unnamed semaphore
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
int sem_init(
- sem_t \*sem,
- int pshared,
- unsigned int value
+ sem_t *sem,
+ int pshared,
+ unsigned int value
);
**STATUS CODES:**
-*EINVAL*
- The value argument exceeds SEM_VALUE_MAX
+.. list-table::
+ :class: rtems-table
-*ENOSPC*
- A resource required to initialize the semaphore has been exhausted
- The limit on semaphores (SEM_VALUE_MAX) has been reached
-
-*ENOSYS*
- The function sem_init is not supported by this implementation
-
-*EPERM*
- The process lacks appropriate privileges to initialize the semaphore
+ * - ``EINVAL``
+ - The value argument exceeds ``SEM_VALUE_MAX``
+ * - ``ENOSPC``
+ - A resource required to initialize the semaphore has been exhausted The
+ limit on semaphores (``SEM_VALUE_MAX``) has been reached
+ * - ``ENOSYS``
+ - The function sem_init is not supported by this implementation
+ * - ``EPERM``
+ - The process lacks appropriate privileges to initialize the semaphore
**DESCRIPTION:**
-The sem_init function is used to initialize the unnamed semaphore referred to
-by "sem". The value of the initialized semaphore is the parameter "value". The
-semaphore remains valid until it is destroyed.
+The ``sem_init`` function is used to initialize the unnamed semaphore referred
+to by ``sem``. The value of the initialized semaphore is the parameter
+``value``. The semaphore remains valid until it is destroyed.
-ADD MORE HERE XXX
+.. COMMENT: ADD MORE HERE XXX
**NOTES:**
If the functions completes successfully, it shall return a value of zero.
-Otherwise, it shall return a value of -1 and set "errno" to specify the error
+otherwise, it shall return a value of -1 and set ``errno`` to specify the error
that occurred.
Multiprocessing is currently not supported in this implementation.
+.. _sem_destroy:
+
sem_destroy - Destroy an unnamed semaphore
------------------------------------------
.. index:: sem_destroy
@@ -136,37 +145,40 @@ sem_destroy - Destroy an unnamed semaphore
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
int sem_destroy(
- sem_t \*sem
+ sem_t *sem
);
**STATUS CODES:**
-*EINVAL*
- The value argument exceeds SEM_VALUE_MAX
+.. list-table::
+ :class: rtems-table
-*ENOSYS*
- The function sem_init is not supported by this implementation
-
-*EBUSY*
- There are currently processes blocked on the semaphore
+ * - ``EINVAL``
+ - The value argument exceeds ``SEM_VALUE_MAX``
+ * - ``ENOSYS``
+ - The function ``sem_init`` is not supported by this implementation
+ * - ``EBUSY``
+ - There are currently processes blocked on the semaphore
**DESCRIPTION:**
-The sem_destroy function is used to destroy an unnamed semaphore refered to by
-"sem". sem_destroy can only be used on a semaphore that was created using
-sem_init.
+The ``sem_destroy`` function is used to destroy an unnamed semaphore refered to
+by ``sem``. ``sem_destroy`` can only be used on a semaphore that was created
+using sem_init.
**NOTES:**
If the functions completes successfully, it shall return a value of zero.
-Otherwise, it shall return a value of -1 and set "errno" to specify the error
+Otherwise, it shall return a value of -1 and set ``errno`` to specify the error
that occurred.
Multiprocessing is currently not supported in this implementation.
+.. _sem_open:
+
sem_open - Open a named semaphore
---------------------------------
.. index:: sem_open
@@ -174,66 +186,70 @@ sem_open - Open a named semaphore
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
int sem_open(
- const char \*name,
- int oflag
+ const char *name,
+ int oflag
);
**ARGUMENTS:**
The following flag bit may be set in oflag:
-``O_CREAT`` - Creates the semaphore if it does not already exist. If O_CREAT
-is set and the semaphore already exists then O_CREAT has no effect. Otherwise,
-sem_open() creates a semaphore. The O_CREAT flag requires the third and fourth
-argument: mode and value of type mode_t and unsigned int, respectively.
+.. list-table::
+ :class: rtems-table
-``O_EXCL`` - If O_EXCL and O_CREAT are set, all call to sem_open() shall fail
-if the semaphore name exists
+ * - ``O_CREAT``
+ - Creates the semaphore if it does not already exist. If ``O_CREAT`` is set
+ and the semaphore already exists then ``O_CREAT`` has no
+ effect. Otherwise, ``sem_open()`` creates a semaphore. The ``O_CREAT``
+ flag requires the third and fourth argument: mode and value of type
+ ``mode_t`` and ``unsigned int``, respectively.
+ * - ``O_EXCL``
+ - If ``O_EXCL`` and ``O_CREAT`` are set, all call to ``sem_open()`` shall
+ fail if the semaphore name exists
**STATUS CODES:**
-*EACCES*
- Valid name specified but oflag permissions are denied, or the semaphore name
- specified does not exist and permission to create the named semaphore is denied.
-
-*EEXIST*
- O_CREAT and O_EXCL are set and the named semaphore already exists.
-
-*EINTR*
- The sem_open() operation was interrupted by a signal.
-
-*EINVAL*
- The sem_open() operation is not supported for the given name.
-
-*EMFILE*
- Too many semaphore descriptors or file descriptors in use by this process.
-
-*ENAMETOOLONG*
- The length of the name exceed PATH_MAX or name component is longer than NAME_MAX
- while POSIX_NO_TRUNC is in effect.
-
-*ENOENT*
- O_CREAT is not set and the named semaphore does not exist.
-
-*ENOSPC*
- There is insufficient space for the creation of a new named semaphore.
-
-*ENOSYS*
- The function sem_open() is not supported by this implementation.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EACCES``
+ - Valid name specified but oflag permissions are denied, or the semaphore
+ name specified does not exist and permission to create the named semaphore
+ is denied.
+ * - ``EEXIST``
+ - ``O_CREAT`` and ``O_EXCL`` are set and the named semaphore already exists.
+ * - ``EINTR``
+ - The ``sem_open()`` operation was interrupted by a signal.
+ * - ``EINVAL``
+ - The ``sem_open()`` operation is not supported for the given name.
+ * - ``EMFILE``
+ - Too many semaphore descriptors or file descriptors in use by this process.
+ * - ``ENAMETOOLONG``
+ - The length of the name exceed ``PATH_MAX`` or name component is longer
+ than ``NAME_MAX`` while ``POSIX_NO_TRUNC`` is in effect.
+ * - ``ENOENT``
+ - ``O_CREAT`` is not set and the named semaphore does not exist.
+ * - ``ENOSPC``
+ - There is insufficient space for the creation of a new named semaphore.
+ * - ``ENOSYS``
+ - The function ``sem_open()`` is not supported by this implementation.
**DESCRIPTION:**
-The sem_open() function establishes a connection between a specified semaphore and
-a process. After a call to sem_open with a specified semaphore name, a process
-can reference to semaphore by the associated name using the address returned by
-the call. The oflag arguments listed above control the state of the semaphore by
-determining if the semaphore is created or accessed by a call to sem_open().
+The ``sem_open()`` function establishes a connection between a specified
+semaphore and a process. After a call to sem_open with a specified semaphore
+name, a process can reference to semaphore by the associated name using the
+address returned by the call. The oflag arguments listed above control the
+state of the semaphore by determining if the semaphore is created or accessed
+by a call to ``sem_open()``.
**NOTES:**
+.. _sem_close:
+
sem_close - Close a named semaphore
-----------------------------------
.. index:: sem_close
@@ -241,30 +257,34 @@ sem_close - Close a named semaphore
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
int sem_close(
- sem_t \*sem_close
+ sem_t *sem_close
);
**STATUS CODES:**
-*EACCES*
- The semaphore argument is not a valid semaphore descriptor.
+.. list-table::
+ :class: rtems-table
-*ENOSYS*
- The function sem_close is not supported by this implementation.
+ * - ``EACCES``
+ - The semaphore argument is not a valid semaphore descriptor.
+ * - ``ENOSYS``
+ - The function ``sem_close`` is not supported by this implementation.
**DESCRIPTION:**
-The sem_close() function is used to indicate that the calling process is finished
-using the named semaphore indicated by sem. The function sem_close deallocates
-any system resources that were previously allocated by a sem_open system call. If
-sem_close() completes successfully it returns a 1, otherwise a value of -1 is
-return and errno is set.
+The ``sem_close()`` function is used to indicate that the calling process is
+finished using the named semaphore indicated by ``sem``. The function
+``sem_close`` deallocates any system resources that were previously allocated
+by a ``sem_open`` system call. If ``sem_close()`` completes successfully it
+returns a 1, otherwise a value of -1 is return and ``errno`` is set.
**NOTES:**
+.. _sem_unlink:
+
sem_unlink - Unlink a semaphore
-------------------------------
.. index:: sem_unlink
@@ -272,43 +292,46 @@ sem_unlink - Unlink a semaphore
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
int sem_unlink(
- const char \*name
+ const char *name
);
**STATUS CODES:**
-*EACCESS*
- Permission is denied to unlink a semaphore.
-
-*ENAMETOOLONG*
- The length of the strong name exceed NAME_MAX while POSIX_NO_TRUNC is in effect.
-
-*ENOENT*
- The name of the semaphore does not exist.
-
-*ENOSPC*
- There is insufficient space for the creation of a new named semaphore.
-
-*ENOSYS*
- The function sem_unlink is not supported by this implementation.
+.. list-table::
+ :class: rtems-table
+
+ * - ``EACCESS``
+ - Permission is denied to unlink a semaphore.
+ * - ``ENAMETOOLONG``
+ - The length of the strong name exceed ``NAME_MAX`` while ``POSIX_NO_TRUNC``
+ is in effect.
+ * - ``ENOENT``
+ - The name of the semaphore does not exist.
+ * - ``ENOSPC``
+ - There is insufficient space for the creation of a new named semaphore.
+ * - ``ENOSYS``
+ - The function ``sem_unlink`` is not supported by this implementation.
**DESCRIPTION:**
-The sem_unlink() function shall remove the semaphore name by the string name. If
-a process is currently accessing the name semaphore, the sem_unlink command has
-no effect. If one or more processes have the semaphore open when the sem_unlink
-function is called, the destruction of semaphores shall be postponed until all
-reference to semaphore are destroyed by calls to sem_close, _exit(), or exec.
-After all references have been destroyed, it returns immediately.
+The ``sem_unlink()`` function shall remove the semaphore name by the string
+name. If a process is currently accessing the name semaphore, the
+``sem_unlink`` command has no effect. If one or more processes have the
+semaphore open when the ``sem_unlink`` function is called, the destruction of
+semaphores shall be postponed until all reference to semaphore are destroyed by
+calls to ``sem_close``, ``_exit()``, or ``exec``. After all references have
+been destroyed, it returns immediately.
If the termination is successful, the function shall return 0. Otherwise, a -1
-is returned and the errno is set.
+is returned and the ``errno`` is set.
**NOTES:**
+.. _sem_wait:
+
sem_wait - Wait on a Semaphore
------------------------------
.. index:: sem_wait
@@ -316,16 +339,19 @@ sem_wait - Wait on a Semaphore
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
int sem_wait(
- sem_t \*sem
+ sem_t *sem
);
**STATUS CODES:**
-*EINVAL*
- The "sem" argument does not refer to a valid semaphore
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The ``sem`` argument does not refer to a valid semaphore
**DESCRIPTION:**
@@ -336,13 +362,15 @@ value is zero), then the function will block until the semaphore becomes
available. It will then successfully lock the semaphore. The semaphore
remains locked until released by a ``sem_post()`` call.
-If the call is unsuccessful, then the function returns -1 and sets errno to the
-appropriate error code.
+If the call is unsuccessful, then the function returns -1 and sets ``errno`` to
+the appropriate error code.
**NOTES:**
Multiprocessing is not supported in this implementation.
+.. _sem_trywait:
+
sem_trywait - Non-blocking Wait on a Semaphore
----------------------------------------------
.. index:: sem_trywait
@@ -350,36 +378,41 @@ sem_trywait - Non-blocking Wait on a Semaphore
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
int sem_trywait(
- sem_t \*sem
+ sem_t *sem
);
**STATUS CODES:**
-*EAGAIN*
- The semaphore is not available (i.e., the semaphore value is zero), so the
- semaphore could not be locked.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The ``sem`` argument does not refewr to a valid semaphore
+ * - ``EAGAIN``
+ - The semaphore is not available (i.e., the semaphore value is zero), so the
+ semaphore could not be locked.
+ * - ``EINVAL``
+ - The ``sem`` argument does not refewr to a valid semaphore
**DESCRIPTION:**
This function attempts to lock a semaphore specified by ``sem``. If the
-semaphore is available, then the semaphore is locked (i.e., the semaphore
-value is decremented) and the function returns a value of 0. The semaphore
-remains locked until released by a ``sem_post()`` call. If the semaphore
-is unavailable (i.e., the semaphore value is zero), then the function will
-return a value of -1 immediately and set ``errno`` to EAGAIN.
+semaphore is available, then the semaphore is locked (i.e., the semaphore value
+is decremented) and the function returns a value of 0. The semaphore remains
+locked until released by a ``sem_post()`` call. If the semaphore is unavailable
+(i.e., the semaphore value is zero), then the function will return a value
+of -1 immediately and set ``errno`` to ``EAGAIN``.
-If the call is unsuccessful, then the function returns -1 and sets``errno`` to the appropriate error code.
+If the call is unsuccessful, then the function returns -1 and sets ``errno`` to
+the appropriate error code.
**NOTES:**
Multiprocessing is not supported in this implementation.
+.. _sem_timedwait:
+
sem_timedwait - Wait on a Semaphore for a Specified Time
--------------------------------------------------------
.. index:: sem_timedwait
@@ -387,40 +420,45 @@ sem_timedwait - Wait on a Semaphore for a Specified Time
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
int sem_timedwait(
- sem_t \*sem,
- const struct timespec \*abstime
+ sem_t *sem,
+ const struct timespec *abstime
);
**STATUS CODES:**
-*EAGAIN*
- The semaphore is not available (i.e., the semaphore value is zero), so the
- semaphore could not be locked.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The ``sem`` argument does not refewr to a valid semaphore
+ * - ``EAGAIN``
+ - The semaphore is not available (i.e., the semaphore value is zero), so the
+ semaphore could not be locked.
+ * - ``EINVAL``
+ - The ``sem`` argument does not refewr to a valid semaphore
**DESCRIPTION:**
-This function attemtps to lock a semaphore specified by ``sem``,
-and will wait for the semaphore until the absolute time specified by``abstime``. If the semaphore is available, then the semaphore is
-locked (i.e., the semaphore value is decremented) and the function
-returns a value of 0. The semaphore remains locked until released by
-a ``sem_post()`` call. If the semaphore is unavailable, then the
-function will wait for the semaphore to become available for the amount
-of time specified by ``timeout``.
-
-If the semaphore does not become available within the interval specified by``timeout``, then the function returns -1 and sets ``errno`` to EAGAIN.
-If any other error occurs, the function returns -1 and sets ``errno`` to
-the appropriate error code.
+This function attemtps to lock a semaphore specified by ``sem``, and will wait
+for the semaphore until the absolute time specified by ``abstime``. If the
+semaphore is available, then the semaphore is locked (i.e., the semaphore value
+is decremented) and the function returns a value of 0. The semaphore remains
+locked until released by a ``sem_post()`` call. If the semaphore is
+unavailable, then the function will wait for the semaphore to become available
+for the amount of time specified by ``timeout``.
+
+If the semaphore does not become available within the interval specified by
+``timeout``, then the function returns -1 and sets ``errno`` to ``EAGAIN``. If
+any other error occurs, the function returns -1 and sets ``errno`` to the
+appropriate error code.
**NOTES:**
Multiprocessing is not supported in this implementation.
+.. _sem_post:
+
sem_post - Unlock a Semaphore
-----------------------------
.. index:: sem_post
@@ -428,25 +466,28 @@ sem_post - Unlock a Semaphore
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
int sem_post(
- sem_t \*sem
+ sem_t *sem
);
**STATUS CODES:**
-*EINVAL*
- The ``sem`` argument does not refer to a valid semaphore
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The ``sem`` argument does not refer to a valid semaphore
**DESCRIPTION:**
-This function attempts to release the semaphore specified by ``sem``. If
-other tasks are waiting on the semaphore, then one of those tasks (which one
-depends on the scheduler being used) is allowed to lock the semaphore and
-return from its ``sem_wait()``, ``sem_trywait()``, or``sem_timedwait()`` call. If there are no other tasks waiting on the
-semaphore, then the semaphore value is simply incremented. ``sem_post()``
-returns 0 upon successful completion.
+This function attempts to release the semaphore specified by ``sem``. If other
+tasks are waiting on the semaphore, then one of those tasks (which one depends
+on the scheduler being used) is allowed to lock the semaphore and return from
+its ``sem_wait()``, ``sem_trywait()``, or ``sem_timedwait()`` call. If there
+are no other tasks waiting on the semaphore, then the semaphore value is simply
+incremented. ``sem_post()`` returns 0 upon successful completion.
If an error occurs, the function returns -1 and sets ``errno`` to the
appropriate error code.
@@ -455,6 +496,8 @@ appropriate error code.
Multiprocessing is not supported in this implementation.
+.. _sem_getvalue:
+
sem_getvalue - Get the value of a semaphore
-------------------------------------------
.. index:: sem_getvalue
@@ -462,42 +505,37 @@ sem_getvalue - Get the value of a semaphore
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
int sem_getvalue(
- sem_t \*sem,
- int \*sval
+ sem_t *sem,
+ int *sval
);
**STATUS CODES:**
-*EINVAL*
- The "sem" argument does not refer to a valid semaphore
+.. list-table::
+ :class: rtems-table
-*ENOSYS*
- The function sem_getvalue is not supported by this implementation
+ * - ``EINVAL``
+ - The ``sem`` argument does not refer to a valid semaphore
+ * - ``ENOSYS``
+ - The function ``sem_getvalue`` is not supported by this implementation
**DESCRIPTION:**
-The sem_getvalue functions sets the location referenced by the "sval" argument
-to the value of the semaphore without affecting the state of the semaphore. The
-updated value represents a semaphore value that occurred at some point during
-the call, but is not necessarily the actual value of the semaphore when it
-returns to the calling process.
+The ``sem_getvalue`` functions sets the location referenced by the ``sval``
+argument to the value of the semaphore without affecting the state of the
+semaphore. The updated value represents a semaphore value that occurred at some
+point during the call, but is not necessarily the actual value of the semaphore
+when it returns to the calling process.
-If "sem" is locked, the value returned by sem_getvalue will be zero or a
+If ``sem`` is locked, the value returned by ``sem_getvalue`` will be zero or a
negative number whose absolute value is the number of processes waiting for the
semaphore at some point during the call.
**NOTES:**
If the functions completes successfully, it shall return a value of zero.
-Otherwise, it shall return a value of -1 and set "errno" to specify the error
+Otherwise, it shall return a value of -1 and set ``errno`` to specify the error
that occurred.
-
-.. COMMENT: COPYRIGHT (c) 1989-2008.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-