From 72a62ad88f82fe1ffee50024db4dd0f3fa5806f7 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Thu, 3 Nov 2016 16:58:08 +1100 Subject: Rename all manuals with an _ to have a -. It helps released naming of files. --- posix_users/semaphore.rst | 543 ---------------------------------------------- 1 file changed, 543 deletions(-) delete mode 100644 posix_users/semaphore.rst (limited to 'posix_users/semaphore.rst') diff --git a/posix_users/semaphore.rst b/posix_users/semaphore.rst deleted file mode 100644 index 27fdf51..0000000 --- a/posix_users/semaphore.rst +++ /dev/null @@ -1,543 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -.. COMMENT: COPYRIGHT (c) 1989-2008. -.. COMMENT: On-Line Applications Research Corporation (OAR). -.. COMMENT: All rights reserved. - -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-block:: 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: - -sem_init - Initialize an unnamed semaphore ------------------------------------------- -.. index:: sem_init -.. index:: initialize an unnamed semaphore - -**CALLING SEQUENCE:** - -.. code-block:: c - - int sem_init( - sem_t *sem, - int pshared, - unsigned int value - ); - -**STATUS CODES:** - -.. list-table:: - :class: rtems-table - - * - ``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. - -.. 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 -that occurred. - -Multiprocessing is currently not supported in this implementation. - -.. _sem_destroy: - -sem_destroy - Destroy an unnamed semaphore ------------------------------------------- -.. index:: sem_destroy -.. index:: destroy an unnamed semaphore - -**CALLING SEQUENCE:** - -.. code-block:: c - - int sem_destroy( - sem_t *sem - ); - -**STATUS CODES:** - -.. list-table:: - :class: rtems-table - - * - ``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: - -sem_open - Open a named semaphore ---------------------------------- -.. index:: sem_open -.. index:: open a named semaphore - -**CALLING SEQUENCE:** - -.. code-block:: c - - int sem_open( - const char *name, - int oflag - ); - -**ARGUMENTS:** - -The following flag bit may be set in oflag: - -.. list-table:: - :class: rtems-table - - * - ``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:** - -.. 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()``. - -**NOTES:** - -.. _sem_close: - -sem_close - Close a named semaphore ------------------------------------ -.. index:: sem_close -.. index:: close a named semaphore - -**CALLING SEQUENCE:** - -.. code-block:: c - - int sem_close( - sem_t *sem_close - ); - -**STATUS CODES:** - -.. list-table:: - :class: rtems-table - - * - ``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: - -sem_unlink - Unlink a semaphore -------------------------------- -.. index:: sem_unlink -.. index:: unlink a semaphore - -**CALLING SEQUENCE:** - -.. code-block:: c - - int sem_unlink( - const char *name - ); - -**STATUS CODES:** - -.. 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. - -If the termination is successful, the function shall return 0. Otherwise, a -1 -is returned and the ``errno`` is set. - -**NOTES:** - -.. _sem_wait: - -sem_wait - Wait on a Semaphore ------------------------------- -.. index:: sem_wait -.. index:: wait on a semaphore - -**CALLING SEQUENCE:** - -.. code-block:: c - - int sem_wait( - sem_t *sem - ); - -**STATUS CODES:** - -.. list-table:: - :class: rtems-table - - * - ``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: - -sem_trywait - Non-blocking Wait on a Semaphore ----------------------------------------------- -.. index:: sem_trywait -.. index:: non - -**CALLING SEQUENCE:** - -.. code-block:: c - - int sem_trywait( - sem_t *sem - ); - -**STATUS CODES:** - -.. list-table:: - :class: rtems-table - - * - ``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: - -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-block:: c - - int sem_timedwait( - sem_t *sem, - const struct timespec *abstime - ); - -**STATUS CODES:** - -.. list-table:: - :class: rtems-table - - * - ``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: - -sem_post - Unlock a Semaphore ------------------------------ -.. index:: sem_post -.. index:: unlock a semaphore - -**CALLING SEQUENCE:** - -.. code-block:: c - - int sem_post( - sem_t *sem - ); - -**STATUS CODES:** - -.. 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. - -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: - -sem_getvalue - Get the value of a semaphore -------------------------------------------- -.. index:: sem_getvalue -.. index:: get the value of a semaphore - -**CALLING SEQUENCE:** - -.. code-block:: c - - int sem_getvalue( - sem_t *sem, - int *sval - ); - -**STATUS CODES:** - -.. list-table:: - :class: rtems-table - - * - ``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. -- cgit v1.2.3