lib/libpthread/sem_open.3

.\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice(s), this list of conditions and the following disclaimer as
.\"    the first lines of this file unmodified other than the possible
.\"    addition of one or more copyright notices.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice(s), this list of conditions and the following disclaimer in
.\"    the documentation and/or other materials provided with the
.\"    distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" $FreeBSD: head/lib/libc/gen/sem_open.3 202133 2010-01-12 01:30:05Z davidxu $
.\"
.Dd June 4, 2014
.Dt SEM_OPEN 3
.Os
.Sh NAME
.Nm sem_open ,
.Nm sem_close ,
.Nm sem_unlink
.Nd named semaphore operations
.Sh LIBRARY
.Lb libpthread
.Sh SYNOPSIS
.In semaphore.h
.Ft "sem_t *"
.Fn sem_open "const char *name" "int oflag" ...
.Ft int
.Fn sem_close "sem_t *sem"
.Ft int
.Fn sem_unlink "const char *name"
.Sh DESCRIPTION
The
.Fn sem_open
function creates or opens the named semaphore specified by
.Fa name .
The returned semaphore may be used in subsequent calls to
.Xr sem_getvalue 3 ,
.Xr sem_wait 3 ,
.Xr sem_trywait 3 ,
.Xr sem_post 3 ,
and
.Fn sem_close .
.Pp
The following bits may be set in the
.Fa oflag
argument:
.Bl -tag -width ".Dv O_CREAT"
.It Dv O_CREAT
Create the semaphore if it does not already exist.
.Pp
The third argument to the call to
.Fn sem_open
must be of type
.Vt mode_t
and specifies the mode for the semaphore.
Only the
.Dv S_IWUSR , S_IWGRP ,
and
.Dv S_IWOTH
bits are examined.
The mode is modified according to the process's file creation
mask; see
.Xr umask 2 .
.Pp
The fourth argument must be an
.Vt "unsigned int"
and specifies the initial value for the semaphore,
and must be no greater than
.Dv SEM_VALUE_MAX .
.It Dv O_EXCL
Create the semaphore if it does not exist.
If the semaphore already exists,
.Fn sem_open
will fail.
This flag is ignored unless
.Dv O_CREAT
is also specified.
.El
.Pp
The
.Fn sem_close
function closes a named semaphore that was opened by a call to
.Fn sem_open .
.Pp
The
.Fn sem_unlink
function removes the semaphore named
.Fa name .
Resources allocated to the semaphore are only deallocated when all
processes that have the semaphore open close it.
.Sh IMPLEMENTATION NOTES
The current implementation uses shared memory mappings of files.
The semaphore files are created at the path pointed to by
.Fa name .
If
.Fa name
is an absolute path,
.Pa /var/run/sem
is prepended to
.Fa name .
The environnment variable
.Ev LIBTHREAD_SEM_PREFIX
can be set to change this value.
.Pp
It is not possible to grant only
.Dq read
permission on a semaphore.
.Sh RETURN VALUES
If successful,
the
.Fn sem_open
function returns the address of the opened semaphore.
If the same
.Fa name
argument is given to multiple calls to
.Fn sem_open
by the same process without an intervening call to
.Fn sem_close ,
the same address is returned each time.
If the semaphore cannot be opened,
.Fn sem_open
returns
.Dv SEM_FAILED
and the global variable
.Va errno
is set to indicate the error.
.Rv -std sem_close sem_unlink
.Sh ERRORS
The
.Fn sem_open
function will fail if:
.Bl -tag -width Er
.It Bq Er EACCES
The semaphore exists and the permissions specified by
.Fa oflag
at the time it was created deny access to this process.
.It Bq Er EACCES
The semaphore does not exist and permission to create it is denied.
.It Bq Er EEXIST
.Dv O_CREAT
and
.Dv O_EXCL
are set but the semaphore already exists.
.It Bq Er EINTR
The call was interrupted by a signal.
.It Bq Er EINVAL
The
.Fn sem_open
operation is not supported for the given
.Fa name .
.It Bq Er EINVAL
The
.Fa value
argument is greater than
.Dv SEM_VALUE_MAX .
.It Bq Er EMFILE
Too many filedescriptors are in use by this process.
.It Bq Er ENAMETOOLONG
The
.Fa name
argument is too long or a pathname component is too long.
.It Bq Er ENFILE
The system limit on semaphores or open files has been reached.
.It Bq Er ENOENT
.Dv O_CREAT
is not set but the named semaphore does not exist.
.It Bq Er ENOSPC
There is not enough space to create the semaphore.
.It Bq Er ENOMEM
There is insufficient memory for the creation of the new named semaphore.
.El
.Pp
The
.Fn sem_close
function will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
The
.Fa sem
argument is not a valid semaphore.
.El
.Pp
The
.Fn sem_unlink
function will fail if:
.Bl -tag -width Er
.It Bq Er EACCES
Permission is denied to unlink the semaphore.
.It Bq Er ENAMETOOLONG
The specified
.Fa name
is too long or a pathname component is too long.
.It Bq Er ENOENT
The named semaphore does not exist.
.El
.Sh SEE ALSO
.Xr close 2 ,
.Xr open 2 ,
.Xr umask 2 ,
.Xr unlink 2 ,
.Xr sem_getvalue 3 ,
.Xr sem_post 3 ,
.Xr sem_trywait 3 ,
.Xr sem_wait 3
.Sh STANDARDS
The
.Fn sem_open ,
.Fn sem_close ,
and
.Fn sem_unlink
functions conform to
.St -p1003.1-96 .
.Sh HISTORY
Support for named semaphores first appeared in
.Dx 3.9 .