Merging upstream version 6.8.

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

1 files changed, 508 insertions, 0 deletions

diff --git a/man/man2/shmop.2 b/man/man2/shmop.2
new file mode 100644
index 0000000..1cb835e
--- /dev/null
+++ b/man/man2/shmop.2
@@ -0,0 +1,508 @@
+.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
+.\" and Copyright 2020 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" Modified Sun Nov 28 17:06:19 1993, Rik Faith (faith@cs.unc.edu)
+.\"          with material from Luigi P. Bai (lpb@softint.com)
+.\" Portions Copyright 1993 Luigi P. Bai
+.\" Modified Tue Oct 22 22:04:23 1996 by Eric S. Raymond <esr@thyrsus.com>
+.\" Modified, 5 Jan 2002, Michael Kerrisk <mtk.manpages@gmail.com>
+.\" Modified, 19 Sep 2002, Michael Kerrisk <mtk.manpages@gmail.com>
+.\"	Added SHM_REMAP flag description
+.\" 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
+.\"	Changed wording and placement of sentence regarding attachment
+.\"		of segments marked for destruction
+.\"
+.TH SHMOP 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+shmat, shmdt \- System V shared memory operations
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/shm.h>
+.P
+.BI "void *shmat(int " shmid ", const void *_Nullable " shmaddr ", \
+int " shmflg );
+.BI "int shmdt(const void *" shmaddr );
+.fi
+.SH DESCRIPTION
+.SS shmat()
+.BR shmat ()
+attaches the System\ V shared memory segment identified by
+.I shmid
+to the address space of the calling process.
+The attaching address is specified by
+.I shmaddr
+with one of the following criteria:
+.IP \[bu] 3
+If
+.I shmaddr
+is NULL,
+the system chooses a suitable (unused) page-aligned address to attach
+the segment.
+.IP \[bu]
+If
+.I shmaddr
+isn't NULL
+and
+.B SHM_RND
+is specified in
+.IR shmflg ,
+the attach occurs at the address equal to
+.I shmaddr
+rounded down to the nearest multiple of
+.BR SHMLBA .
+.IP \[bu]
+Otherwise,
+.I shmaddr
+must be a page-aligned address at which the attach occurs.
+.P
+In addition to
+.BR SHM_RND ,
+the following flags may be specified in the
+.I shmflg
+bit-mask argument:
+.TP
+.BR SHM_EXEC " (Linux-specific; since Linux 2.6.9)"
+Allow the contents of the segment to be executed.
+The caller must have execute permission on the segment.
+.TP
+.B SHM_RDONLY
+Attach the segment for read-only access.
+The process must have read permission for the segment.
+If this flag is not specified,
+the segment is attached for read and write access,
+and the process must have read and write permission for the segment.
+There is no notion of a write-only shared memory segment.
+.TP
+.BR SHM_REMAP " (Linux-specific)"
+This flag specifies
+that the mapping of the segment should replace
+any existing mapping in the range starting at
+.I shmaddr
+and continuing for the size of the segment.
+(Normally, an
+.B EINVAL
+error would result if a mapping already exists in this address range.)
+In this case,
+.I shmaddr
+must not be NULL.
+.P
+The
+.BR brk (2)
+value of the calling process is not altered by the attach.
+The segment will automatically be detached at process exit.
+The same segment may be attached as a read and as a read-write
+one, and more than once, in the process's address space.
+.P
+A successful
+.BR shmat ()
+call updates the members of the
+.I shmid_ds
+structure (see
+.BR shmctl (2))
+associated with the shared memory segment as follows:
+.IP \[bu] 3
+.I shm_atime
+is set to the current time.
+.IP \[bu]
+.I shm_lpid
+is set to the process-ID of the calling process.
+.IP \[bu]
+.I shm_nattch
+is incremented by one.
+.\"
+.SS shmdt()
+.BR shmdt ()
+detaches the shared memory segment located at the address specified by
+.I shmaddr
+from the address space of the calling process.
+The to-be-detached segment must be currently
+attached with
+.I shmaddr
+equal to the value returned by the attaching
+.BR shmat ()
+call.
+.P
+On a successful
+.BR shmdt ()
+call, the system updates the members of the
+.I shmid_ds
+structure associated with the shared memory segment as follows:
+.IP \[bu] 3
+.I shm_dtime
+is set to the current time.
+.IP \[bu]
+.I shm_lpid
+is set to the process-ID of the calling process.
+.IP \[bu]
+.I shm_nattch
+is decremented by one.
+If it becomes 0 and the segment is marked for deletion,
+the segment is deleted.
+.SH RETURN VALUE
+On success,
+.BR shmat ()
+returns the address of the attached shared memory segment; on error,
+.I (void\ *)\ \-1
+is returned, and
+.I errno
+is set to indicate the error.
+.P
+On success,
+.BR shmdt ()
+returns 0; on error \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.BR shmat ()
+can fail with one of the following errors:
+.TP
+.B EACCES
+The calling process does not have the required permissions for
+the requested attach type, and does not have the
+.B CAP_IPC_OWNER
+capability in the user namespace that governs its IPC namespace.
+.TP
+.B EIDRM
+\fIshmid\fP points to a removed identifier.
+.TP
+.B EINVAL
+Invalid
+.I shmid
+value, unaligned (i.e., not page-aligned and \fBSHM_RND\fP was not
+specified) or invalid
+.I shmaddr
+value, or can't attach segment at
+.IR shmaddr ,
+or
+.B SHM_REMAP
+was specified and
+.I shmaddr
+was NULL.
+.TP
+.B ENOMEM
+Could not allocate memory for the descriptor or for the page tables.
+.P
+.BR shmdt ()
+can fail with one of the following errors:
+.TP
+.B EINVAL
+There is no shared memory segment attached at
+.IR shmaddr ;
+or,
+.\" The following since Linux 2.6.17-rc1:
+.I shmaddr
+is not aligned on a page boundary.
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001, SVr4.
+.\" SVr4 documents an additional error condition EMFILE.
+.P
+In SVID 3 (or perhaps earlier),
+the type of the \fIshmaddr\fP argument was changed from
+.I "char\ *"
+into
+.IR "const void\ *" ,
+and the returned type of
+.BR shmat ()
+from
+.I "char\ *"
+into
+.IR "void\ *" .
+.SH NOTES
+After a
+.BR fork (2),
+the child inherits the attached shared memory segments.
+.P
+After an
+.BR execve (2),
+all attached shared memory segments are detached from the process.
+.P
+Upon
+.BR _exit (2),
+all attached shared memory segments are detached from the process.
+.P
+Using
+.BR shmat ()
+with
+.I shmaddr
+equal to NULL
+is the preferred, portable way of attaching a shared memory segment.
+Be aware that the shared memory segment attached in this way
+may be attached at different addresses in different processes.
+Therefore, any pointers maintained within the shared memory must be
+made relative (typically to the starting address of the segment),
+rather than absolute.
+.P
+On Linux, it is possible to attach a shared memory segment even if it
+is already marked to be deleted.
+However, POSIX.1 does not specify this behavior and
+many other implementations do not support it.
+.P
+The following system parameter affects
+.BR shmat ():
+.TP
+.B SHMLBA
+Segment low boundary address multiple.
+When explicitly specifying an attach address in a call to
+.BR shmat (),
+the caller should ensure that the address is a multiple of this value.
+This is necessary on some architectures,
+in order either to ensure good CPU cache performance or to ensure that
+different attaches of the same segment have consistent views
+within the CPU cache.
+.B SHMLBA
+is normally some multiple of the system page size.
+(On many Linux architectures,
+.B SHMLBA
+is the same as the system page size.)
+.P
+The implementation places no intrinsic per-process limit on the
+number of shared memory segments
+.RB ( SHMSEG ).
+.SH EXAMPLES
+The two programs shown below exchange a string using a shared memory segment.
+Further details about the programs are given below.
+First, we show a shell session demonstrating their use.
+.P
+In one terminal window, we run the "reader" program,
+which creates a System V shared memory segment and a System V semaphore set.
+The program prints out the IDs of the created objects,
+and then waits for the semaphore to change value.
+.P
+.in +4n
+.EX
+$ \fB./svshm_string_read\fP
+shmid = 1114194; semid = 15
+.EE
+.in
+.P
+In another terminal window, we run the "writer" program.
+The "writer" program takes three command-line arguments:
+the IDs of the shared memory segment and semaphore set created
+by the "reader", and a string.
+It attaches the existing shared memory segment,
+copies the string to the shared memory, and modifies the semaphore value.
+.P
+.in +4n
+.EX
+$ \fB./svshm_string_write 1114194 15 \[aq]Hello, world\[aq]\fP
+.EE
+.in
+.P
+Returning to the terminal where the "reader" is running,
+we see that the program has ceased waiting on the semaphore
+and has printed the string that was copied into the
+shared memory segment by the writer:
+.P
+.in +4n
+.EX
+Hello, world
+.EE
+.in
+.\"
+.SS Program source: svshm_string.h
+The following header file is included by the "reader" and "writer" programs:
+.P
+.in +4n
+.\" SRC BEGIN (svshm_string.h)
+.EX
+/* svshm_string.h
+\&
+   Licensed under GNU General Public License v2 or later.
+*/
+#ifndef SVSHM_STRING_H
+#define SVSHM_STRING_H
+\&
+#include <stdio.h>
+#include <stdlib.h>
+#include <sys/sem.h>
+\&
+#define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \e
+                        } while (0)
+\&
+union semun {                   /* Used in calls to semctl() */
+    int                 val;
+    struct semid_ds     *buf;
+    unsigned short      *array;
+#if defined(__linux__)
+    struct seminfo      *__buf;
+#endif
+};
+\&
+#define MEM_SIZE 4096
+\&
+#endif  // include guard
+.EE
+.\" SRC END
+.in
+.\"
+.SS Program source: svshm_string_read.c
+The "reader" program creates a shared memory segment and a semaphore set
+containing one semaphore.
+It then attaches the shared memory object into its address space
+and initializes the semaphore value to 1.
+Finally, the program waits for the semaphore value to become 0,
+and afterwards prints the string that has been copied into the
+shared memory segment by the "writer".
+.P
+.in +4n
+.\" SRC BEGIN (svshm_string_read.c)
+.EX
+/* svshm_string_read.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 <sys/shm.h>
+\&
+#include "svshm_string.h"
+\&
+int
+main(void)
+{
+    int            semid, shmid;
+    char           *addr;
+    union semun    arg, dummy;
+    struct sembuf  sop;
+\&
+    /* Create shared memory and semaphore set containing one
+       semaphore. */
+\&
+    shmid = shmget(IPC_PRIVATE, MEM_SIZE, IPC_CREAT | 0600);
+    if (shmid == \-1)
+        errExit("shmget");
+\&
+    semid = semget(IPC_PRIVATE, 1, IPC_CREAT | 0600);
+    if (semid == \-1)
+        errExit("semget");
+\&
+    /* Attach shared memory into our address space. */
+\&
+    addr = shmat(shmid, NULL, SHM_RDONLY);
+    if (addr == (void *) \-1)
+        errExit("shmat");
+\&
+    /* Initialize semaphore 0 in set with value 1. */
+\&
+    arg.val = 1;
+    if (semctl(semid, 0, SETVAL, arg) == \-1)
+        errExit("semctl");
+\&
+    printf("shmid = %d; semid = %d\en", shmid, semid);
+\&
+    /* Wait for semaphore value to become 0. */
+\&
+    sop.sem_num = 0;
+    sop.sem_op = 0;
+    sop.sem_flg = 0;
+\&
+    if (semop(semid, &sop, 1) == \-1)
+        errExit("semop");
+\&
+    /* Print the string from shared memory. */
+\&
+    printf("%s\en", addr);
+\&
+    /* Remove shared memory and semaphore set. */
+\&
+    if (shmctl(shmid, IPC_RMID, NULL) == \-1)
+        errExit("shmctl");
+    if (semctl(semid, 0, IPC_RMID, dummy) == \-1)
+        errExit("semctl");
+\&
+    exit(EXIT_SUCCESS);
+}
+.EE
+.\" SRC END
+.in
+.\"
+.SS Program source: svshm_string_write.c
+The writer program takes three command-line arguments:
+the IDs of the shared memory segment and semaphore set
+that have already been created by the "reader", and a string.
+It attaches the shared memory segment into its address space,
+and then decrements the semaphore value to 0 in order to inform the
+"reader" that it can now examine the contents of the shared memory.
+.P
+.in +4n
+.\" SRC BEGIN (svshm_string_write.c)
+.EX
+/* svshm_string_write.c
+\&
+   Licensed under GNU General Public License v2 or later.
+*/
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/sem.h>
+#include <sys/shm.h>
+\&
+#include "svshm_string.h"
+\&
+int
+main(int argc, char *argv[])
+{
+    int            semid, shmid;
+    char           *addr;
+    size_t         len;
+    struct sembuf  sop;
+\&
+    if (argc != 4) {
+        fprintf(stderr, "Usage: %s shmid semid string\en", argv[0]);
+        exit(EXIT_FAILURE);
+    }
+\&
+    len = strlen(argv[3]) + 1;  /* +1 to include trailing \[aq]\e0\[aq] */
+    if (len > MEM_SIZE) {
+        fprintf(stderr, "String is too big!\en");
+        exit(EXIT_FAILURE);
+    }
+\&
+    /* Get object IDs from command\-line. */
+\&
+    shmid = atoi(argv[1]);
+    semid = atoi(argv[2]);
+\&
+    /* Attach shared memory into our address space and copy string
+       (including trailing null byte) into memory. */
+\&
+    addr = shmat(shmid, NULL, 0);
+    if (addr == (void *) \-1)
+        errExit("shmat");
+\&
+    memcpy(addr, argv[3], len);
+\&
+    /* Decrement semaphore to 0. */
+\&
+    sop.sem_num = 0;
+    sop.sem_op = \-1;
+    sop.sem_flg = 0;
+\&
+    if (semop(semid, &sop, 1) == \-1)
+        errExit("semop");
+\&
+    exit(EXIT_SUCCESS);
+}
+.EE
+.\" SRC END
+.in
+.SH SEE ALSO
+.BR brk (2),
+.BR mmap (2),
+.BR shmctl (2),
+.BR shmget (2),
+.BR capabilities (7),
+.BR shm_overview (7),
+.BR sysvipc (7)