Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 434 insertions, 0 deletions

diff --git a/man/man2/semget.2 b/man/man2/semget.2
new file mode 100644
index 0000000..9c53462
--- /dev/null
+++ b/man/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 2024-05-02 "Linux man-pages (unreleased)"
+.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)