diff options
Diffstat (limited to 'upstream/fedora-rawhide/man2/semget.2')
| -rw-r--r-- | upstream/fedora-rawhide/man2/semget.2 | 434 |
1 files changed, 434 insertions, 0 deletions
diff --git a/upstream/fedora-rawhide/man2/semget.2 b/upstream/fedora-rawhide/man2/semget.2 new file mode 100644 index 00000000..b1fcb45a --- /dev/null +++ b/upstream/fedora-rawhide/man2/semget.2 @@ -0,0 +1,434 @@ +.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) +.\" and Copyright (C) 2020 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 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 <mtk.manpages@gmail.com> +.\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com> +.\" Added notes on capability requirements +.\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com> +.\" Language and formatting clean-ups +.\" Added notes on /proc files +.\" Rewrote BUGS note about semget()'s failure to initialize +.\" semaphore values +.\" +.TH semget 2 2023-10-31 "Linux man-pages 6.06" +.SH NAME +semget \- get a System V semaphore set identifier +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/sem.h> +.fi +.P +.BI "int semget(key_t " key , +.BI "int " nsems , +.BI "int " semflg ); +.SH DESCRIPTION +The +.BR semget () +system call returns the System\ V semaphore set identifier +associated with the argument +.IR key . +It may be used either to obtain the identifier of a previously created +semaphore set (when +.I semflg +is zero and +.I key +does not have the value +.BR IPC_PRIVATE ), +or to create a new set. +.P +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 with +.I key +and +.B IPC_CREAT +is specified in +.IR semflg . +.P +If +.I semflg +specifies both +.B IPC_CREAT +and +.B IPC_EXCL +and a semaphore set already exists for +.IR key , +then +.BR semget () +fails with +.I errno +set to +.BR EEXIST . +(This is analogous to the effect of the combination +.B O_CREAT | O_EXCL +for +.BR open (2).) +.P +Upon creation, the least significant 9 bits of the argument +.I semflg +define the permissions (for owner, group, and others) +for the semaphore set. +These bits have the same format, and the same +meaning, as the +.I mode +argument of +.BR open (2) +(though the execute permissions are +not meaningful for semaphores, and write permissions mean permission +to alter semaphore values). +.P +When creating a new semaphore set, +.BR semget () +initializes the set's associated data structure, +.I semid_ds +(see +.BR semctl (2)), +as follows: +.IP \[bu] 3 +.I sem_perm.cuid +and +.I sem_perm.uid +are set to the effective user ID of the calling process. +.IP \[bu] +.I sem_perm.cgid +and +.I sem_perm.gid +are set to the effective group ID of the calling process. +.IP \[bu] +The least significant 9 bits of +.I sem_perm.mode +are set to the least significant 9 bits of +.IR semflg . +.IP \[bu] +.I sem_nsems +is set to the value of +.IR nsems . +.IP \[bu] +.I sem_otime +is set to 0. +.IP \[bu] +.I sem_ctime +is set to the current time. +.P +The argument +.I nsems +can be 0 +(a don't care) +when a semaphore set is not being created. +Otherwise, +.I nsems +must be greater than 0 +and less than or equal to the maximum number of semaphores per semaphore set +.RB ( SEMMSL ). +.P +If the semaphore set already exists, the permissions are +verified. +.\" and a check is made to see if it is marked for destruction. +.SH RETURN VALUE +On success, +.BR semget () +returns the semaphore set identifier (a nonnegative integer). +On failure, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.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 +.B CAP_IPC_OWNER +capability in the user namespace that governs its IPC namespace. +.TP +.B EEXIST +.B IPC_CREAT +and +.B IPC_EXCL +were specified in +.IR semflg , +but a semaphore set already exists for +.IR key . +.\" .TP +.\" .B EIDRM +.\" The semaphore set is marked to be deleted. +.TP +.B EINVAL +.I nsems +is less than 0 or greater than the limit on the number +of semaphores per semaphore set +.RB ( SEMMSL ). +.TP +.B EINVAL +A semaphore set corresponding to +.I key +already exists, but +.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 +did not specify +.BR IPC_CREAT . +.TP +.B ENOMEM +A semaphore set has to be created but the system does not have +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 STANDARDS +POSIX.1-2008. +.SH HISTORY +SVr4, POSIX.1-2001. +.\" SVr4 documents additional error conditions EFBIG, E2BIG, EAGAIN, +.\" ERANGE, EFAULT. +.SH NOTES +.B IPC_PRIVATE +isn't a flag field but a +.I key_t +type. +If this special value is used for +.IR key , +the system call ignores all but the least significant 9 bits of +.I semflg +and creates a new semaphore set (on success). +.\" +.SS Semaphore initialization +The values of the semaphores in a newly created set are indeterminate. +(POSIX.1-2001 and POSIX.1-2008 are explicit on this point, +although POSIX.1-2008 notes that a future version of the standard +may require an implementation to initialize the semaphores to 0.) +Although Linux, like many other implementations, +initializes the semaphore values to 0, +a portable application cannot rely on this: +it should explicitly initialize the semaphores to the desired values. +.\" In truth, every one of the many implementations that I've tested sets +.\" the values to zero, but I suppose there is/was some obscure +.\" implementation out there that does not. +.P +Initialization can be done using +.BR semctl (2) +.B SETVAL +or +.B SETALL +operation. +Where multiple peers do not know who will be the first to +initialize the set, checking for a nonzero +.I sem_otime +in the associated data structure retrieved by a +.BR semctl (2) +.B IPC_STAT +operation can be used to avoid races. +.\" +.SS Semaphore limits +The following limits on semaphore set resources affect the +.BR semget () +call: +.TP +.B SEMMNI +System-wide limit on the number of semaphore sets. +Before Linux 3.19, +the default value for this limit was 128. +Since Linux 3.19, +.\" commit e843e7d2c88b7db107a86bd2c7145dc715c058f4 +the default value is 32,000. +On Linux, this limit can be read and modified via the fourth field of +.IR /proc/sys/kernel/sem . +.\" This /proc file is not available in Linux 2.2 and earlier -- MTK +.TP +.B SEMMSL +Maximum number of semaphores per semaphore ID. +Before Linux 3.19, +the default value for this limit was 250. +Since Linux 3.19, +.\" commit e843e7d2c88b7db107a86bd2c7145dc715c058f4 +the default value is 32,000. +On Linux, this limit can be read and modified via the first field of +.IR /proc/sys/kernel/sem . +.TP +.B SEMMNS +System-wide limit on the number of semaphores: policy dependent +(on Linux, this limit can be read and modified via the second field of +.IR /proc/sys/kernel/sem ). +Note that the number of semaphores system-wide +is also limited by the product of +.B SEMMSL +and +.BR SEMMNI . +.SH BUGS +The name choice +.B IPC_PRIVATE +was perhaps unfortunate, +.B IPC_NEW +would more clearly show its function. +.SH EXAMPLES +The program shown below uses +.BR semget () +to create a new semaphore set or retrieve the ID of an existing set. +It generates the +.I key +for +.BR semget () +using +.BR ftok (3). +The first two command-line arguments are used as the +.I pathname +and +.I proj_id +arguments for +.BR ftok (3). +The third command-line argument is an integer that specifies the +.I nsems +argument for +.BR semget (). +Command-line options can be used to specify the +.B IPC_CREAT +.RI ( \-c ) +and +.B IPC_EXCL +.RI ( \-x ) +flags for the call to +.BR semget (). +The usage of this program is demonstrated below. +.P +We first create two files that will be used to generate keys using +.BR ftok (3), +create two semaphore sets using those files, and then list the sets using +.BR ipcs (1): +.P +.in +4n +.EX +$ \fBtouch mykey mykey2\fP +$ \fB./t_semget \-c mykey p 1\fP +ID = 9 +$ \fB./t_semget \-c mykey2 p 2\fP +ID = 10 +$ \fBipcs \-s\fP +\& +\-\-\-\-\-\- Semaphore Arrays \-\-\-\-\-\-\-\- +key semid owner perms nsems +0x7004136d 9 mtk 600 1 +0x70041368 10 mtk 600 2 +.EE +.in +.P +Next, we demonstrate that when +.BR semctl (2) +is given the same +.I key +(as generated by the same arguments to +.BR ftok (3)), +it returns the ID of the already existing semaphore set: +.P +.in +4n +.EX +$ \fB./t_semget \-c mykey p 1\fP +ID = 9 +.EE +.in +.P +Finally, we demonstrate the kind of collision that can occur when +.BR ftok (3) +is given different +.I pathname +arguments that have the same inode number: +.P +.in +4n +.EX +$ \fBln mykey link\fP +$ \fBls \-i1 link mykey\fP +2233197 link +2233197 mykey +$ \fB./t_semget link p 1\fP # Generates same key as \[aq]mykey\[aq] +ID = 9 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (t_semget.c) +.EX +/* t_semget.c +\& + Licensed under GNU General Public License v2 or later. +*/ +#include <stdio.h> +#include <stdlib.h> +#include <sys/ipc.h> +#include <sys/sem.h> +#include <unistd.h> +\& +static void +usage(const char *pname) +{ + fprintf(stderr, "Usage: %s [\-cx] pathname proj\-id num\-sems\en", + pname); + fprintf(stderr, " \-c Use IPC_CREAT flag\en"); + fprintf(stderr, " \-x Use IPC_EXCL flag\en"); + exit(EXIT_FAILURE); +} +\& +int +main(int argc, char *argv[]) +{ + int semid, nsems, flags, opt; + key_t key; +\& + flags = 0; + while ((opt = getopt(argc, argv, "cx")) != \-1) { + switch (opt) { + case \[aq]c\[aq]: flags |= IPC_CREAT; break; + case \[aq]x\[aq]: flags |= IPC_EXCL; break; + default: usage(argv[0]); + } + } +\& + if (argc != optind + 3) + usage(argv[0]); +\& + key = ftok(argv[optind], argv[optind + 1][0]); + if (key == \-1) { + perror("ftok"); + exit(EXIT_FAILURE); + } +\& + nsems = atoi(argv[optind + 2]); +\& + semid = semget(key, nsems, flags | 0600); + if (semid == \-1) { + perror("semget"); + exit(EXIT_FAILURE); + } +\& + printf("ID = %d\en", semid); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR semctl (2), +.BR semop (2), +.BR ftok (3), +.BR capabilities (7), +.BR sem_overview (7), +.BR sysvipc (7) |