Document the named semaphore functions. This could still use a bit
of polishing.
This commit is contained in:
tjr
parent
5a653c8876
commit
ad1ea71c7a
@ -26,7 +26,7 @@
|
||||
.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.Dd February 15, 2000
|
||||
.Dd January 15, 2003
|
||||
.Dt SEM_OPEN 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
@ -46,36 +46,183 @@
|
||||
.Fn sem_unlink "const char *name"
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Fn sem_open ,
|
||||
.Fn sem_close ,
|
||||
and
|
||||
.Fn sem_unlink
|
||||
functions are not supported by this implementation.
|
||||
.Sh RETURN VALUES
|
||||
.Fn sem_open
|
||||
returns SEM_FAILED and sets
|
||||
.Va errno
|
||||
to indicate an error.
|
||||
.Fn sem_close
|
||||
function creates or opens the named semaphore specified by
|
||||
.Fa name .
|
||||
The returned semaphore may be used in subsequent calls to
|
||||
.Fn sem_getvalue ,
|
||||
.Fn sem_wait ,
|
||||
.Fn sem_trywait ,
|
||||
.Fn sem_post
|
||||
and
|
||||
.Fn sem_unlink
|
||||
return -1 and set
|
||||
.Va errno
|
||||
to indicate an error.
|
||||
.Sh ERRORS
|
||||
.Fn sem_open ,
|
||||
.Fn sem_close ,
|
||||
.Fn sem_close .
|
||||
.Pp
|
||||
The following bits may be 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 ,
|
||||
.Dv S_IWGRP ,
|
||||
and
|
||||
.Fn sem_unlink
|
||||
will fail:
|
||||
.Bl -tag -width Er
|
||||
.It Bq Er ENOSYS
|
||||
Function not supported by this implementation.
|
||||
.Dv S_IWOTH
|
||||
bits are examined;
|
||||
it is not possible to grant only
|
||||
.Dq read
|
||||
permission on a semaphore.
|
||||
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 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.
|
||||
.Pp
|
||||
.Rv -std sem_close
|
||||
.Pp
|
||||
.Rv -std 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 the this process.
|
||||
.It Bq Er EACCES
|
||||
The semaphore does not exist, but 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 .
|
||||
.\"FreeBSD never returns EMFILE
|
||||
.\".It Bq Er EMFILE
|
||||
.\"Too many semaphores are in use by this process.
|
||||
.It Bq Er ENAMETOOLONG
|
||||
The
|
||||
.Fa name
|
||||
argument is too long.
|
||||
.It Bq Er ENFILE
|
||||
The system limit on semaphores has been reached.
|
||||
.It Bq Er ENOENT
|
||||
.Dv O_CREAT
|
||||
is set but the named semaphore does not exist.
|
||||
.It Bq Er ENOSPC
|
||||
There is not enough space to create the 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.
|
||||
.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_wait 3 ,
|
||||
.Xr sem_trywait 3 ,
|
||||
.Xr sem_post 3 ,
|
||||
.Xr sem 4
|
||||
.Sh STANDARDS
|
||||
The
|
||||
.Fn sem_open ,
|
||||
.Fn sem_close ,
|
||||
and
|
||||
.Fn sem_unlink
|
||||
conform to
|
||||
functions conform to
|
||||
.St -p1003.1-96 .
|
||||
.Sh HISTORY
|
||||
Support for named semaphores first appeared in
|
||||
.Fx 5.0 .
|
||||
.Sh BUGS
|
||||
This implementation places strict requirements on the value of
|
||||
.Fa name :
|
||||
it must begin with a slash
|
||||
.Pq Ql / ,
|
||||
contain no other slash characters,
|
||||
and be less than 14 characters in length not including the terminating null.
|
||||
|
||||
@ -26,7 +26,7 @@
|
||||
.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.Dd February 15, 2000
|
||||
.Dd January 15, 2003
|
||||
.Dt SEM_OPEN 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
@ -46,36 +46,183 @@
|
||||
.Fn sem_unlink "const char *name"
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Fn sem_open ,
|
||||
.Fn sem_close ,
|
||||
and
|
||||
.Fn sem_unlink
|
||||
functions are not supported by this implementation.
|
||||
.Sh RETURN VALUES
|
||||
.Fn sem_open
|
||||
returns SEM_FAILED and sets
|
||||
.Va errno
|
||||
to indicate an error.
|
||||
.Fn sem_close
|
||||
function creates or opens the named semaphore specified by
|
||||
.Fa name .
|
||||
The returned semaphore may be used in subsequent calls to
|
||||
.Fn sem_getvalue ,
|
||||
.Fn sem_wait ,
|
||||
.Fn sem_trywait ,
|
||||
.Fn sem_post
|
||||
and
|
||||
.Fn sem_unlink
|
||||
return -1 and set
|
||||
.Va errno
|
||||
to indicate an error.
|
||||
.Sh ERRORS
|
||||
.Fn sem_open ,
|
||||
.Fn sem_close ,
|
||||
.Fn sem_close .
|
||||
.Pp
|
||||
The following bits may be 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 ,
|
||||
.Dv S_IWGRP ,
|
||||
and
|
||||
.Fn sem_unlink
|
||||
will fail:
|
||||
.Bl -tag -width Er
|
||||
.It Bq Er ENOSYS
|
||||
Function not supported by this implementation.
|
||||
.Dv S_IWOTH
|
||||
bits are examined;
|
||||
it is not possible to grant only
|
||||
.Dq read
|
||||
permission on a semaphore.
|
||||
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 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.
|
||||
.Pp
|
||||
.Rv -std sem_close
|
||||
.Pp
|
||||
.Rv -std 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 the this process.
|
||||
.It Bq Er EACCES
|
||||
The semaphore does not exist, but 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 .
|
||||
.\"FreeBSD never returns EMFILE
|
||||
.\".It Bq Er EMFILE
|
||||
.\"Too many semaphores are in use by this process.
|
||||
.It Bq Er ENAMETOOLONG
|
||||
The
|
||||
.Fa name
|
||||
argument is too long.
|
||||
.It Bq Er ENFILE
|
||||
The system limit on semaphores has been reached.
|
||||
.It Bq Er ENOENT
|
||||
.Dv O_CREAT
|
||||
is set but the named semaphore does not exist.
|
||||
.It Bq Er ENOSPC
|
||||
There is not enough space to create the 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.
|
||||
.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_wait 3 ,
|
||||
.Xr sem_trywait 3 ,
|
||||
.Xr sem_post 3 ,
|
||||
.Xr sem 4
|
||||
.Sh STANDARDS
|
||||
The
|
||||
.Fn sem_open ,
|
||||
.Fn sem_close ,
|
||||
and
|
||||
.Fn sem_unlink
|
||||
conform to
|
||||
functions conform to
|
||||
.St -p1003.1-96 .
|
||||
.Sh HISTORY
|
||||
Support for named semaphores first appeared in
|
||||
.Fx 5.0 .
|
||||
.Sh BUGS
|
||||
This implementation places strict requirements on the value of
|
||||
.Fa name :
|
||||
it must begin with a slash
|
||||
.Pq Ql / ,
|
||||
contain no other slash characters,
|
||||
and be less than 14 characters in length not including the terminating null.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user