2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
|
|
.\" preserved on all copies.
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
|
|
.\" permission notice identical to this one.
|
|
|
|
.\"
|
|
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
|
|
.\" have taken the same level of care in the production of this manual,
|
|
|
|
.\" which is licensed free of charge, as they might when working
|
|
|
|
.\" professionally.
|
|
|
|
.\"
|
|
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
|
|
.\"
|
|
|
|
.\" Modified Tue Oct 22 17:54:56 1996 by Eric S. Raymond <esr@thyrsus.com>
|
|
|
|
.\" Modified 1 Jan 2002, Martin Schulze <joey@infodrom.org>
|
2004-11-03 14:43:40 +00:00
|
|
|
.\" Modified 4 Jan 2002, Michael Kerrisk <mtk-manpages@gmx.net>
|
|
|
|
.\" Modified, 27 May 2004, Michael Kerrisk <mtk-manpages@gmx.net>
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Added notes on capability requirements
|
|
|
|
.\"
|
|
|
|
.TH SEMGET 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual"
|
|
|
|
.SH NAME
|
|
|
|
semget \- get a semaphore set identifier
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.nf
|
|
|
|
.B
|
|
|
|
#include <sys/types.h>
|
|
|
|
.B
|
|
|
|
#include <sys/ipc.h>
|
|
|
|
.B
|
|
|
|
#include <sys/sem.h>
|
|
|
|
.fi
|
|
|
|
.sp
|
|
|
|
.BI "int semget(key_t " key ,
|
|
|
|
.BI "int " nsems ,
|
|
|
|
.BI "int " semflg );
|
|
|
|
.SH DESCRIPTION
|
|
|
|
This function returns the semaphore set identifier
|
|
|
|
associated with the argument
|
|
|
|
.IR key .
|
|
|
|
A new set of
|
|
|
|
.I nsems
|
|
|
|
semaphores is created if
|
|
|
|
.I key
|
|
|
|
has the value
|
|
|
|
.B IPC_PRIVATE
|
|
|
|
or if no existing semaphore set is associated to
|
|
|
|
.I key
|
|
|
|
and
|
|
|
|
.B IPC_CREAT
|
|
|
|
is asserted in
|
|
|
|
.I semflg
|
|
|
|
(i.e.
|
|
|
|
.IR semflg " &"
|
|
|
|
.B IPC_CREAT
|
|
|
|
isn't zero).
|
|
|
|
.PP
|
|
|
|
The presence in
|
|
|
|
.I semflg
|
|
|
|
of the fields
|
|
|
|
.B IPC_CREAT
|
|
|
|
and
|
|
|
|
.B IPC_EXCL
|
|
|
|
plays the same role, with respect to the existence
|
|
|
|
of the semaphore set, as the presence
|
|
|
|
of
|
|
|
|
.B O_CREAT
|
|
|
|
and
|
|
|
|
.B O_EXCL
|
|
|
|
in the mode argument of the
|
|
|
|
.BR open (2)
|
|
|
|
system call: i.e. the
|
|
|
|
.B semget
|
|
|
|
function fails if
|
|
|
|
.I semflg
|
|
|
|
asserts both
|
|
|
|
.B IPC_CREAT
|
|
|
|
and
|
|
|
|
.B IPC_EXCL
|
|
|
|
and a semaphore set already exists for
|
|
|
|
.IR key .
|
|
|
|
.PP
|
|
|
|
Upon creation, the low-order 9 bits of the argument
|
|
|
|
.I semflg
|
|
|
|
define the access permissions (for owner, group and others)
|
|
|
|
for the semaphore set.
|
|
|
|
These bits have the same format, and the same
|
|
|
|
meaning, as the mode argument in the
|
|
|
|
.BR open (2)
|
|
|
|
or
|
|
|
|
.BR creat (2)
|
|
|
|
system calls (though the execute permissions are
|
|
|
|
not meaningful for semaphores, and write permissions mean permission
|
|
|
|
to alter semaphore values).
|
|
|
|
.PP
|
|
|
|
When creating a new semaphore set,
|
|
|
|
.B semget
|
|
|
|
initializes the semaphore set's associated data structure
|
|
|
|
.B semid_ds
|
|
|
|
as follows:
|
|
|
|
.IP
|
|
|
|
.B sem_perm.cuid
|
|
|
|
and
|
|
|
|
.B sem_perm.uid
|
|
|
|
are set to the effective user\-ID of the calling process.
|
|
|
|
.IP
|
|
|
|
.B sem_perm.cgid
|
|
|
|
and
|
|
|
|
.B sem_perm.gid
|
|
|
|
are set to the effective group\-ID of the calling process.
|
|
|
|
.IP
|
|
|
|
The low-order 9 bits of
|
|
|
|
.B sem_perm.mode
|
|
|
|
are set to the low-order 9 bits of
|
|
|
|
.IR semflg .
|
|
|
|
.IP
|
|
|
|
.B sem_nsems
|
|
|
|
is set to the value of
|
|
|
|
.IR nsems .
|
|
|
|
.IP
|
|
|
|
.B sem_otime
|
|
|
|
is set to 0.
|
|
|
|
.IP
|
|
|
|
.B sem_ctime
|
|
|
|
is set to the current time.
|
|
|
|
.PP
|
|
|
|
The argument
|
|
|
|
.I nsems
|
|
|
|
can be
|
|
|
|
.B 0
|
|
|
|
(a don't care)
|
|
|
|
when a semaphore set is not being created.
|
|
|
|
Otherwise
|
|
|
|
.I nsems
|
|
|
|
must be greater than
|
|
|
|
.B 0
|
|
|
|
and less than or equal to the maximum number of semaphores per semaphore set
|
|
|
|
.RB ( SEMMSL ).
|
|
|
|
.PP
|
|
|
|
If the semaphore set already exists, the access permissions are
|
|
|
|
verified.
|
|
|
|
.\" and a check is made to see if it is marked for destruction.
|
|
|
|
.SH "RETURN VALUE"
|
|
|
|
If successful, the return value will be the semaphore set identifier
|
|
|
|
(a nonnegative integer), otherwise
|
|
|
|
.B \-1
|
|
|
|
is returned, with
|
|
|
|
.I errno
|
|
|
|
indicating the error.
|
|
|
|
.SH ERRORS
|
|
|
|
On failure
|
|
|
|
.I errno
|
|
|
|
will be set to one of the following:
|
|
|
|
.TP 11
|
|
|
|
.B EACCES
|
|
|
|
A semaphore set exists for
|
|
|
|
.IR key ,
|
|
|
|
but the calling process does not have permission to access the set,
|
|
|
|
and does not have the
|
|
|
|
.BR CAP_IPC_OWNER
|
|
|
|
capability.
|
|
|
|
.TP
|
|
|
|
.B EEXIST
|
|
|
|
A semaphore set exists for
|
|
|
|
.B key
|
|
|
|
and
|
|
|
|
.I semflg
|
|
|
|
was asserting both
|
|
|
|
.B IPC_CREAT
|
|
|
|
and
|
|
|
|
.BR IPC_EXCL .
|
|
|
|
.\" .TP
|
|
|
|
.\" .B EIDRM
|
|
|
|
.\" The semaphore set is marked to be deleted.
|
|
|
|
.TP
|
|
|
|
.B EINVAL
|
|
|
|
.IR nsems
|
|
|
|
is less than 0 or greater than the limit on the number
|
|
|
|
of semaphores per semaphore set
|
|
|
|
.RB ( SEMMSL ),
|
|
|
|
or a semaphore set corresponding to
|
|
|
|
.I key
|
|
|
|
already exists, and
|
|
|
|
.I nsems
|
|
|
|
is larger than the number of semaphores in that set.
|
|
|
|
.TP
|
|
|
|
.B ENOENT
|
|
|
|
No semaphore set exists for
|
|
|
|
.I key
|
|
|
|
and
|
|
|
|
.I semflg
|
|
|
|
wasn't asserting
|
|
|
|
.BR IPC_CREAT .
|
|
|
|
.TP
|
|
|
|
.B ENOMEM
|
|
|
|
A semaphore set has to be created but the system has not enough memory for
|
|
|
|
the new data structure.
|
|
|
|
.TP
|
|
|
|
.B ENOSPC
|
|
|
|
A semaphore set has to be created but the system limit for the maximum
|
|
|
|
number of semaphore sets
|
|
|
|
.RB ( SEMMNI ),
|
|
|
|
or the system wide maximum number of semaphores
|
|
|
|
.RB ( SEMMNS ),
|
|
|
|
would be exceeded.
|
|
|
|
.SH NOTES
|
|
|
|
.B IPC_PRIVATE
|
|
|
|
isn't a flag field but a
|
|
|
|
.B key_t
|
|
|
|
type.
|
|
|
|
If this special value is used for
|
|
|
|
.IR key ,
|
|
|
|
the system call ignores everything but the low-order 9 bits of
|
|
|
|
.I semflg
|
|
|
|
and creates a new semaphore set (on success).
|
|
|
|
.PP
|
|
|
|
The followings are limits on semaphore set resources affecting a
|
|
|
|
.B semget
|
|
|
|
call:
|
|
|
|
.TP 11
|
|
|
|
.B SEMMNI
|
|
|
|
System wide maximum number of semaphore sets: policy dependent.
|
|
|
|
.TP
|
|
|
|
.B SEMMSL
|
|
|
|
Maximum number of semaphores per semid: implementation dependent
|
|
|
|
(500 currently).
|
|
|
|
.TP
|
|
|
|
.B SEMMNS
|
|
|
|
System wide maximum number of semaphores: policy dependent.
|
|
|
|
Values greater than
|
|
|
|
.B SEMMSL * SEMMNI
|
|
|
|
makes it irrelevant.
|
|
|
|
.SH BUGS
|
|
|
|
The name choice IPC_PRIVATE was perhaps unfortunate, IPC_NEW
|
|
|
|
would more clearly show its function.
|
|
|
|
.LP
|
|
|
|
The data structure associated with each semaphore in the set
|
|
|
|
isn't initialized by the system call.
|
|
|
|
In order to initialize those data structures, one has to execute a
|
|
|
|
subsequent call to
|
|
|
|
.BR semctl (2)
|
|
|
|
to perform a
|
|
|
|
.B SETVAL
|
|
|
|
or a
|
|
|
|
.B SETALL
|
|
|
|
command on the semaphore set.
|
|
|
|
.SH "CONFORMING TO"
|
|
|
|
SVr4, SVID.
|
|
|
|
SVr4 documents additional error conditions EFBIG, E2BIG, EAGAIN,
|
|
|
|
ERANGE, EFAULT.
|
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR semctl (2),
|
|
|
|
.BR semop (2),
|
|
|
|
.BR ftok (3),
|
|
|
|
.BR ipc (5),
|
|
|
|
.BR capabilities (7)
|