From 100d1b33f088fd38f69129afff7f9c2a1e084a57 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 24 May 2024 06:52:24 +0200 Subject: Merging upstream version 6.8. Signed-off-by: Daniel Baumann --- man2/semget.2 | 434 ---------------------------------------------------------- 1 file changed, 434 deletions(-) delete mode 100644 man2/semget.2 (limited to 'man2/semget.2') diff --git a/man2/semget.2 b/man2/semget.2 deleted file mode 100644 index 50813ba..0000000 --- a/man2/semget.2 +++ /dev/null @@ -1,434 +0,0 @@ -.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) -.\" and Copyright (C) 2020 Michael Kerrisk -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.\" Modified Tue Oct 22 17:54:56 1996 by Eric S. Raymond -.\" Modified 1 Jan 2002, Martin Schulze -.\" Modified 4 Jan 2002, Michael Kerrisk -.\" Modified, 27 May 2004, Michael Kerrisk -.\" Added notes on capability requirements -.\" Modified, 11 Nov 2004, Michael Kerrisk -.\" 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.7" -.SH NAME -semget \- get a System V semaphore set identifier -.SH LIBRARY -Standard C library -.RI ( libc ", " \-lc ) -.SH SYNOPSIS -.nf -.B #include -.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 -#include -#include -#include -#include -\& -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) -- cgit v1.2.3