diff options
Diffstat (limited to 'man2/semget.2')
-rw-r--r-- | man2/semget.2 | 264 |
1 files changed, 264 insertions, 0 deletions
diff --git a/man2/semget.2 b/man2/semget.2 new file mode 100644 index 000000000..baeaf4825 --- /dev/null +++ b/man2/semget.2 @@ -0,0 +1,264 @@ +.\" 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> +.\" Modified 4 Jan 2002, Michael Kerrisk <mtk16@ext.canterbury.ac.nz> +.\" Modified, 27 May 2004, Michael Kerrisk <mtk16@ext.canterbury.ac.nz> +.\" 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) |