|
Packit |
7cfc04 |
'\" t
|
|
Packit |
7cfc04 |
.\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_START(VERBATIM)
|
|
Packit |
7cfc04 |
.\" Permission is granted to make and distribute verbatim copies of this
|
|
Packit |
7cfc04 |
.\" manual provided the copyright notice and this permission notice are
|
|
Packit |
7cfc04 |
.\" preserved on all copies.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Permission is granted to copy and distribute modified versions of this
|
|
Packit |
7cfc04 |
.\" manual under the conditions for verbatim copying, provided that the
|
|
Packit |
7cfc04 |
.\" entire resulting derived work is distributed under the terms of a
|
|
Packit |
7cfc04 |
.\" permission notice identical to this one.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
Packit |
7cfc04 |
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
Packit |
7cfc04 |
.\" responsibility for errors or omissions, or for damages resulting from
|
|
Packit |
7cfc04 |
.\" the use of the information contained herein. The author(s) may not
|
|
Packit |
7cfc04 |
.\" have taken the same level of care in the production of this manual,
|
|
Packit |
7cfc04 |
.\" which is licensed free of charge, as they might when working
|
|
Packit |
7cfc04 |
.\" professionally.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
Packit |
7cfc04 |
.\" the source, must acknowledge the copyright and authors of this work.
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_END
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.TH SEM_OVERVIEW 7 2017-05-03 "Linux" "Linux Programmer's Manual"
|
|
Packit |
7cfc04 |
.SH NAME
|
|
Packit |
7cfc04 |
sem_overview \- overview of POSIX semaphores
|
|
Packit |
7cfc04 |
.SH DESCRIPTION
|
|
Packit |
7cfc04 |
POSIX semaphores allow processes and threads to synchronize their actions.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
A semaphore is an integer whose value is never allowed to fall below zero.
|
|
Packit |
7cfc04 |
Two operations can be performed on semaphores:
|
|
Packit |
7cfc04 |
increment the semaphore value by one
|
|
Packit |
7cfc04 |
.RB ( sem_post (3));
|
|
Packit |
7cfc04 |
and decrement the semaphore value by one
|
|
Packit |
7cfc04 |
.RB ( sem_wait (3)).
|
|
Packit |
7cfc04 |
If the value of a semaphore is currently zero, then a
|
|
Packit |
7cfc04 |
.BR sem_wait (3)
|
|
Packit |
7cfc04 |
operation will block until the value becomes greater than zero.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
POSIX semaphores come in two forms: named semaphores and
|
|
Packit |
7cfc04 |
unnamed semaphores.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B Named semaphores
|
|
Packit |
7cfc04 |
A named semaphore is identified by a name of the form
|
|
Packit |
7cfc04 |
.IR /somename ;
|
|
Packit |
7cfc04 |
that is, a null-terminated string of up to
|
|
Packit |
7cfc04 |
.BI NAME_MAX \-4
|
|
Packit |
7cfc04 |
(i.e., 251) characters consisting of an initial slash,
|
|
Packit |
7cfc04 |
.\" glibc allows the initial slash to be omitted, and makes
|
|
Packit |
7cfc04 |
.\" multiple initial slashes equivalent to a single slash.
|
|
Packit |
7cfc04 |
.\" This differs from the implementation of POSIX message queues.
|
|
Packit |
7cfc04 |
followed by one or more characters, none of which are slashes.
|
|
Packit |
7cfc04 |
.\" glibc allows subdirectory components in the name, in which
|
|
Packit |
7cfc04 |
.\" case the subdirectory tree must exist under /dev/shm, and
|
|
Packit |
7cfc04 |
.\" the fist subdirectory component must exist as the name
|
|
Packit |
7cfc04 |
.\" sem.name, and all of the subdirectory components must allow the
|
|
Packit |
7cfc04 |
.\" required permissions if a user wants to create a semaphore
|
|
Packit |
7cfc04 |
.\" object in a subdirectory.
|
|
Packit |
7cfc04 |
Two processes can operate on the same named semaphore by passing
|
|
Packit |
7cfc04 |
the same name to
|
|
Packit |
7cfc04 |
.BR sem_open (3).
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.BR sem_open (3)
|
|
Packit |
7cfc04 |
function creates a new named semaphore or opens an existing
|
|
Packit |
7cfc04 |
named semaphore.
|
|
Packit |
7cfc04 |
After the semaphore has been opened, it can be operated on using
|
|
Packit |
7cfc04 |
.BR sem_post (3)
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.BR sem_wait (3).
|
|
Packit |
7cfc04 |
When a process has finished using the semaphore, it can use
|
|
Packit |
7cfc04 |
.BR sem_close (3)
|
|
Packit |
7cfc04 |
to close the semaphore.
|
|
Packit |
7cfc04 |
When all processes have finished using the semaphore,
|
|
Packit |
7cfc04 |
it can be removed from the system using
|
|
Packit |
7cfc04 |
.BR sem_unlink (3).
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B Unnamed semaphores (memory-based semaphores)
|
|
Packit |
7cfc04 |
An unnamed semaphore does not have a name.
|
|
Packit |
7cfc04 |
Instead the semaphore is placed in a region of memory that
|
|
Packit |
7cfc04 |
is shared between multiple threads (a
|
|
Packit |
7cfc04 |
.IR "thread-shared semaphore" )
|
|
Packit |
7cfc04 |
or processes (a
|
|
Packit |
7cfc04 |
.IR "process-shared semaphore" ).
|
|
Packit |
7cfc04 |
A thread-shared semaphore is placed in an area of memory shared
|
|
Packit |
7cfc04 |
between the threads of a process, for example, a global variable.
|
|
Packit |
7cfc04 |
A process-shared semaphore must be placed in a shared memory region
|
|
Packit |
7cfc04 |
(e.g., a System V shared memory segment created using
|
|
Packit |
7cfc04 |
.BR shmget (2),
|
|
Packit |
7cfc04 |
or a POSIX shared memory object built created using
|
|
Packit |
7cfc04 |
.BR shm_open (3)).
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
Before being used, an unnamed semaphore must be initialized using
|
|
Packit |
7cfc04 |
.BR sem_init (3).
|
|
Packit |
7cfc04 |
It can then be operated on using
|
|
Packit |
7cfc04 |
.BR sem_post (3)
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.BR sem_wait (3).
|
|
Packit |
7cfc04 |
When the semaphore is no longer required,
|
|
Packit |
7cfc04 |
and before the memory in which it is located is deallocated,
|
|
Packit |
7cfc04 |
the semaphore should be destroyed using
|
|
Packit |
7cfc04 |
.BR sem_destroy (3).
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The remainder of this section describes some specific details
|
|
Packit |
7cfc04 |
of the Linux implementation of POSIX semaphores.
|
|
Packit |
7cfc04 |
.SS Versions
|
|
Packit |
7cfc04 |
Prior to kernel 2.6, Linux supported only unnamed,
|
|
Packit |
7cfc04 |
thread-shared semaphores.
|
|
Packit |
7cfc04 |
On a system with Linux 2.6 and a glibc that provides the NPTL
|
|
Packit |
7cfc04 |
threading implementation,
|
|
Packit |
7cfc04 |
a complete implementation of POSIX semaphores is provided.
|
|
Packit |
7cfc04 |
.SS Persistence
|
|
Packit |
7cfc04 |
POSIX named semaphores have kernel persistence:
|
|
Packit |
7cfc04 |
if not removed by
|
|
Packit |
7cfc04 |
.BR sem_unlink (3),
|
|
Packit |
7cfc04 |
a semaphore will exist until the system is shut down.
|
|
Packit |
7cfc04 |
.SS Linking
|
|
Packit |
7cfc04 |
Programs using the POSIX semaphores API must be compiled with
|
|
Packit |
7cfc04 |
.I cc \-pthread
|
|
Packit |
7cfc04 |
to link against the real-time library,
|
|
Packit |
7cfc04 |
.IR librt .
|
|
Packit |
7cfc04 |
.SS Accessing named semaphores via the filesystem
|
|
Packit |
7cfc04 |
On Linux, named semaphores are created in a virtual filesystem,
|
|
Packit |
7cfc04 |
normally mounted under
|
|
Packit |
7cfc04 |
.IR /dev/shm ,
|
|
Packit |
7cfc04 |
with names of the form
|
|
Packit |
7cfc04 |
.IR \fBsem.\fPsomename .
|
|
Packit |
7cfc04 |
(This is the reason that semaphore names are limited to
|
|
Packit |
7cfc04 |
.BI NAME_MAX \-4
|
|
Packit |
7cfc04 |
rather than
|
|
Packit |
7cfc04 |
.B NAME_MAX
|
|
Packit |
7cfc04 |
characters.)
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
Since Linux 2.6.19, ACLs can be placed on files under this directory,
|
|
Packit |
7cfc04 |
to control object permissions on a per-user and per-group basis.
|
|
Packit |
7cfc04 |
.SH NOTES
|
|
Packit |
7cfc04 |
System V semaphores
|
|
Packit |
7cfc04 |
.RB ( semget (2),
|
|
Packit |
7cfc04 |
.BR semop (2),
|
|
Packit |
7cfc04 |
etc.) are an older semaphore API.
|
|
Packit |
7cfc04 |
POSIX semaphores provide a simpler, and better designed interface than
|
|
Packit |
7cfc04 |
System V semaphores;
|
|
Packit |
7cfc04 |
on the other hand POSIX semaphores are less widely available
|
|
Packit |
7cfc04 |
(especially on older systems) than System V semaphores.
|
|
Packit |
7cfc04 |
.SH EXAMPLE
|
|
Packit |
7cfc04 |
An example of the use of various POSIX semaphore functions is shown in
|
|
Packit |
7cfc04 |
.BR sem_wait (3).
|
|
Packit |
7cfc04 |
.SH SEE ALSO
|
|
Packit |
7cfc04 |
.BR sem_close (3),
|
|
Packit |
7cfc04 |
.BR sem_destroy (3),
|
|
Packit |
7cfc04 |
.BR sem_getvalue (3),
|
|
Packit |
7cfc04 |
.BR sem_init (3),
|
|
Packit |
7cfc04 |
.BR sem_open (3),
|
|
Packit |
7cfc04 |
.BR sem_post (3),
|
|
Packit |
7cfc04 |
.BR sem_unlink (3),
|
|
Packit |
7cfc04 |
.BR sem_wait (3),
|
|
Packit |
7cfc04 |
.BR pthreads (7),
|
|
Packit |
7cfc04 |
.BR shm_overview (7)
|
|
Packit |
7cfc04 |
.SH COLOPHON
|
|
Packit |
7cfc04 |
This page is part of release 4.15 of the Linux
|
|
Packit |
7cfc04 |
.I man-pages
|
|
Packit |
7cfc04 |
project.
|
|
Packit |
7cfc04 |
A description of the project,
|
|
Packit |
7cfc04 |
information about reporting bugs,
|
|
Packit |
7cfc04 |
and the latest version of this page,
|
|
Packit |
7cfc04 |
can be found at
|
|
Packit |
7cfc04 |
\%https://www.kernel.org/doc/man\-pages/.
|