diff options
Diffstat (limited to 'posix_users/semaphore.rst')
| -rw-r--r-- | posix_users/semaphore.rst | 426 |
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. - |