summaryrefslogtreecommitdiffstats
path: root/posix_users/semaphore.rst
diff options
context:
space:
mode:
authorAmar Takhar <amar@rtems.org>2016-01-17 00:55:21 -0500
committerAmar Takhar <verm@darkbeer.org>2016-05-02 20:51:23 -0400
commit1264a8f1089fad85cabb024c930b19b0a36864b4 (patch)
treef95424251f62abd513babf47148828ca402dc893 /posix_users/semaphore.rst
parentec76eca9cc967e0d8990316eee1d1841387f5210 (diff)
downloadrtems-docs-1264a8f1089fad85cabb024c930b19b0a36864b4.tar.bz2
Split document into seperate files by section.
Diffstat (limited to 'posix_users/semaphore.rst')
-rw-r--r--posix_users/semaphore.rst503
1 files changed, 503 insertions, 0 deletions
diff --git a/posix_users/semaphore.rst b/posix_users/semaphore.rst
new file mode 100644
index 0000000..eda5bcd
--- /dev/null
+++ b/posix_users/semaphore.rst
@@ -0,0 +1,503 @@
+Semaphore Manager
+#################
+
+Introduction
+============
+
+The semaphore manager provides functions to allocate, delete, and control
+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_destroy`` - Destroy an unnamed semaphore
+
+- ``sem_open`` - Open a named semaphore
+
+- ``sem_close`` - Close a named semaphore
+
+- ``sem_unlink`` - Remove a named semaphore
+
+- ``sem_wait`` - Lock a semaphore
+
+- ``sem_trywait`` - Lock a semaphore
+
+- ``sem_timedwait`` - Wait on a Semaphore for a Specified Time
+
+- ``sem_post`` - Unlock a semaphore
+
+- ``sem_getvalue`` - Get the value of a semeaphore
+
+Background
+==========
+
+Theory
+------
+
+Semaphores are used for synchronization and mutual exclusion by indicating the
+availability and number of resources. The task (the task which is returning
+resources) notifying other tasks of an event increases the number of resources
+held by the semaphore by one. The task (the task which will obtain resources)
+waiting for the event decreases the number of resources held by the semaphore
+by one. If the number of resources held by a semaphore is insufficient (namely
+0), the task requiring resources will wait until the next time resources are
+returned to the semaphore. If there is more than one task waiting for a
+semaphore, the tasks will be placed in the queue.
+
+"sem_t" Structure
+-----------------
+.. index:: sem_t
+
+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
+
+ typedef int sem_t;
+
+Building a Semaphore Attribute Set
+----------------------------------
+
+Operations
+==========
+
+Using as a Binary Semaphore
+---------------------------
+
+Although POSIX supports mutexes, they are only visible between threads. To work
+between processes, a binary semaphore must be used.
+
+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.
+
+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.
+
+sem_init - Initialize an unnamed semaphore
+------------------------------------------
+.. index:: sem_init
+.. index:: initialize an unnamed semaphore
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+ int sem_init(
+ sem_t \*sem,
+ int pshared,
+ unsigned int value
+ );
+
+**STATUS CODES:**
+
+*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.
+
+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
+that occurred.
+
+Multiprocessing is currently not supported in this implementation.
+
+sem_destroy - Destroy an unnamed semaphore
+------------------------------------------
+.. index:: sem_destroy
+.. index:: destroy an unnamed semaphore
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+ int sem_destroy(
+ sem_t \*sem
+ );
+
+**STATUS CODES:**
+
+*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.
+
+**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
+that occurred.
+
+Multiprocessing is currently not supported in this implementation.
+
+sem_open - Open a named semaphore
+---------------------------------
+.. index:: sem_open
+.. index:: open a named semaphore
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+ int sem_open(
+ 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.
+
+``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.
+
+**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().
+
+**NOTES:**
+
+sem_close - Close a named semaphore
+-----------------------------------
+.. index:: sem_close
+.. index:: close a named semaphore
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+ int sem_close(
+ sem_t \*sem_close
+ );
+
+**STATUS CODES:**
+
+*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.
+
+**NOTES:**
+
+sem_unlink - Unlink a semaphore
+-------------------------------
+.. index:: sem_unlink
+.. index:: unlink a semaphore
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+ int sem_unlink(
+ 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.
+
+**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.
+
+If the termination is successful, the function shall return 0. Otherwise, a -1
+is returned and the errno is set.
+
+**NOTES:**
+
+sem_wait - Wait on a Semaphore
+------------------------------
+.. index:: sem_wait
+.. index:: wait on a semaphore
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+ int sem_wait(
+ sem_t \*sem
+ );
+
+**STATUS CODES:**
+
+*EINVAL*
+ The "sem" argument does not refer 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). If the semaphore is unavailable (i.e., the semaphore
+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.
+
+**NOTES:**
+
+Multiprocessing is not supported in this implementation.
+
+sem_trywait - Non-blocking Wait on a Semaphore
+----------------------------------------------
+.. index:: sem_trywait
+.. index:: non
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+ int sem_trywait(
+ 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.
+
+*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.
+
+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 - Wait on a Semaphore for a Specified Time
+--------------------------------------------------------
+.. index:: sem_timedwait
+.. index:: wait on a semaphore for a specified time
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+ int sem_timedwait(
+ 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.
+
+*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.
+
+**NOTES:**
+
+Multiprocessing is not supported in this implementation.
+
+sem_post - Unlock a Semaphore
+-----------------------------
+.. index:: sem_post
+.. index:: unlock a semaphore
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+ int sem_post(
+ sem_t \*sem
+ );
+
+**STATUS CODES:**
+
+*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.
+
+If an error occurs, the function returns -1 and sets ``errno`` to the
+appropriate error code.
+
+**NOTES:**
+
+Multiprocessing is not supported in this implementation.
+
+sem_getvalue - Get the value of a semaphore
+-------------------------------------------
+.. index:: sem_getvalue
+.. index:: get the value of a semaphore
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+ int sem_getvalue(
+ sem_t \*sem,
+ int \*sval
+ );
+
+**STATUS CODES:**
+
+*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.
+
+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
+that occurred.
+
+.. COMMENT: COPYRIGHT (c) 1989-2008.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+