summaryrefslogtreecommitdiffstats
path: root/man2/shmctl.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/shmctl.2')
-rw-r--r--man2/shmctl.2494
1 files changed, 0 insertions, 494 deletions
diff --git a/man2/shmctl.2 b/man2/shmctl.2
deleted file mode 100644
index 5d5176a..0000000
--- a/man2/shmctl.2
+++ /dev/null
@@ -1,494 +0,0 @@
-'\" t
-.\" Copyright (c) 1993 Luigi P. Bai (lpb@softint.com) July 28, 1993
-.\" and Copyright 1993 Giorgio Ciucci <giorgio@crcc.it>
-.\" and Copyright 2004, 2005 Michael Kerrisk <mtk.manpages@gmail.com>
-.\"
-.\" SPDX-License-Identifier: Linux-man-pages-copyleft
-.\"
-.\" Modified 1993-07-28, Rik Faith <faith@cs.unc.edu>
-.\" Modified 1993-11-28, Giorgio Ciucci <giorgio@crcc.it>
-.\" Modified 1997-01-31, Eric S. Raymond <esr@thyrsus.com>
-.\" Modified 2001-02-18, Andries Brouwer <aeb@cwi.nl>
-.\" Modified 2002-01-05, 2004-05-27, 2004-06-17,
-.\" Michael Kerrisk <mtk.manpages@gmail.com>
-.\" Modified 2004-10-11, aeb
-.\" Modified, Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
-.\" Language and formatting clean-ups
-.\" Updated shmid_ds structure definitions
-.\" Added information on SHM_DEST and SHM_LOCKED flags
-.\" Noted that CAP_IPC_LOCK is not required for SHM_UNLOCK
-.\" since Linux 2.6.9
-.\" Modified, 2004-11-25, mtk, notes on 2.6.9 RLIMIT_MEMLOCK changes
-.\" 2005-04-25, mtk -- noted aberrant Linux behavior w.r.t. new
-.\" attaches to a segment that has already been marked for deletion.
-.\" 2005-08-02, mtk: Added IPC_INFO, SHM_INFO, SHM_STAT descriptions.
-.\" 2018-03-20, dbueso: Added SHM_STAT_ANY description.
-.\"
-.TH shmctl 2 2024-03-03 "Linux man-pages 6.7"
-.SH NAME
-shmctl \- System V shared memory control
-.SH LIBRARY
-Standard C library
-.RI ( libc ", " \-lc )
-.SH SYNOPSIS
-.nf
-.B #include <sys/shm.h>
-.P
-.BI "int shmctl(int " shmid ", int " op ", struct shmid_ds *" buf );
-.fi
-.SH DESCRIPTION
-.BR shmctl ()
-performs the control operation specified by
-.I op
-on the System\ V shared memory segment whose identifier is given in
-.IR shmid .
-.P
-The
-.I buf
-argument is a pointer to a \fIshmid_ds\fP structure,
-defined in \fI<sys/shm.h>\fP as follows:
-.P
-.in +4n
-.EX
-struct shmid_ds {
- struct ipc_perm shm_perm; /* Ownership and permissions */
- size_t shm_segsz; /* Size of segment (bytes) */
- time_t shm_atime; /* Last attach time */
- time_t shm_dtime; /* Last detach time */
- time_t shm_ctime; /* Creation time/time of last
- modification via shmctl() */
- pid_t shm_cpid; /* PID of creator */
- pid_t shm_lpid; /* PID of last shmat(2)/shmdt(2) */
- shmatt_t shm_nattch; /* No. of current attaches */
- ...
-};
-.EE
-.in
-.P
-The fields of the
-.I shmid_ds
-structure are as follows:
-.TP 12
-.I shm_perm
-This is an
-.I ipc_perm
-structure (see below) that specifies the access permissions
-on the shared memory segment.
-.TP
-.I shm_segsz
-Size in bytes of the shared memory segment.
-.TP
-.I shm_atime
-Time of the last
-.BR shmat (2)
-system call that attached this segment.
-.TP
-.I shm_dtime
-Time of the last
-.BR shmdt (2)
-system call that detached tgis segment.
-.TP
-.I shm_ctime
-Time of creation of segment or time of the last
-.BR shmctl ()
-.B IPC_SET
-operation.
-.TP
-.I shm_cpid
-ID of the process that created the shared memory segment.
-.TP
-.I shm_lpid
-ID of the last process that executed a
-.BR shmat (2)
-or
-.BR shmdt (2)
-system call on this segment.
-.TP
-.I shm_nattch
-Number of processes that have this segment attached.
-.P
-The
-.I ipc_perm
-structure is defined as follows
-(the highlighted fields are settable using
-.BR IPC_SET ):
-.P
-.in +4n
-.EX
-struct ipc_perm {
- key_t __key; /* Key supplied to shmget(2) */
- uid_t \fBuid\fP; /* Effective UID of owner */
- gid_t \fBgid\fP; /* Effective GID of owner */
- uid_t cuid; /* Effective UID of creator */
- gid_t cgid; /* Effective GID of creator */
- unsigned short \fBmode\fP; /* \fBPermissions\fP + SHM_DEST and
- SHM_LOCKED flags */
- unsigned short __seq; /* Sequence number */
-};
-.EE
-.in
-.P
-The least significant 9 bits of the
-.I mode
-field of the
-.I ipc_perm
-structure define the access permissions for the shared memory segment.
-The permission bits are as follows:
-.TS
-l l.
-0400 Read by user
-0200 Write by user
-0040 Read by group
-0020 Write by group
-0004 Read by others
-0002 Write by others
-.TE
-.P
-Bits 0100, 0010, and 0001 (the execute bits) are unused by the system.
-(It is not necessary to have execute permission on a segment
-in order to perform a
-.BR shmat (2)
-call with the
-.B SHM_EXEC
-flag.)
-.P
-Valid values for
-.I op
-are:
-.TP
-.B IPC_STAT
-Copy information from the kernel data structure associated with
-.I shmid
-into the
-.I shmid_ds
-structure pointed to by \fIbuf\fP.
-The caller must have read permission on the
-shared memory segment.
-.TP
-.B IPC_SET
-Write the values of some members of the
-.I shmid_ds
-structure pointed to by
-.I buf
-to the kernel data structure associated with this shared memory segment,
-updating also its
-.I shm_ctime
-member.
-.IP
-The following fields are updated:
-\fIshm_perm.uid\fP, \fIshm_perm.gid\fP,
-and (the least significant 9 bits of) \fIshm_perm.mode\fP.
-.IP
-The effective UID of the calling process must match the owner
-.RI ( shm_perm.uid )
-or creator
-.RI ( shm_perm.cuid )
-of the shared memory segment, or the caller must be privileged.
-.TP
-.B IPC_RMID
-Mark the segment to be destroyed.
-The segment will actually be destroyed
-only after the last process detaches it (i.e., when the
-.I shm_nattch
-member of the associated structure
-.I shmid_ds
-is zero).
-The caller must be the owner or creator of the segment, or be privileged.
-The
-.I buf
-argument is ignored.
-.IP
-If a segment has been marked for destruction, then the (nonstandard)
-.B SHM_DEST
-flag of the
-.I shm_perm.mode
-field in the associated data structure retrieved by
-.B IPC_STAT
-will be set.
-.IP
-The caller \fImust\fP ensure that a segment is eventually destroyed;
-otherwise its pages that were faulted in will remain in memory or swap.
-.IP
-See also the description of
-.I /proc/sys/kernel/shm_rmid_forced
-in
-.BR proc (5).
-.TP
-.BR IPC_INFO " (Linux-specific)"
-Return information about system-wide shared memory limits and
-parameters in the structure pointed to by
-.IR buf .
-This structure is of type
-.I shminfo
-(thus, a cast is required),
-defined in
-.I <sys/shm.h>
-if the
-.B _GNU_SOURCE
-feature test macro is defined:
-.IP
-.in +4n
-.EX
-struct shminfo {
- unsigned long shmmax; /* Maximum segment size */
- unsigned long shmmin; /* Minimum segment size;
- always 1 */
- unsigned long shmmni; /* Maximum number of segments */
- unsigned long shmseg; /* Maximum number of segments
- that a process can attach;
- unused within kernel */
- unsigned long shmall; /* Maximum number of pages of
- shared memory, system\-wide */
-};
-.EE
-.in
-.IP
-The
-.IR shmmni ,
-.IR shmmax ,
-and
-.I shmall
-settings can be changed via
-.I /proc
-files of the same name; see
-.BR proc (5)
-for details.
-.TP
-.BR SHM_INFO " (Linux-specific)"
-Return a
-.I shm_info
-structure whose fields contain information
-about system resources consumed by shared memory.
-This structure is defined in
-.I <sys/shm.h>
-if the
-.B _GNU_SOURCE
-feature test macro is defined:
-.IP
-.in +4n
-.EX
-struct shm_info {
- int used_ids; /* # of currently existing
- segments */
- unsigned long shm_tot; /* Total number of shared
- memory pages */
- unsigned long shm_rss; /* # of resident shared
- memory pages */
- unsigned long shm_swp; /* # of swapped shared
- memory pages */
- unsigned long swap_attempts;
- /* Unused since Linux 2.4 */
- unsigned long swap_successes;
- /* Unused since Linux 2.4 */
-};
-.EE
-.in
-.TP
-.BR SHM_STAT " (Linux-specific)"
-Return a
-.I shmid_ds
-structure as for
-.BR IPC_STAT .
-However, the
-.I shmid
-argument is not a segment identifier, but instead an index into
-the kernel's internal array that maintains information about
-all shared memory segments on the system.
-.TP
-.BR SHM_STAT_ANY " (Linux-specific, since Linux 4.17)"
-Return a
-.I shmid_ds
-structure as for
-.BR SHM_STAT .
-However,
-.I shm_perm.mode
-is not checked for read access for
-.IR shmid ,
-meaning that any user can employ this operation (just as any user may read
-.I /proc/sysvipc/shm
-to obtain the same information).
-.P
-The caller can prevent or allow swapping of a shared
-memory segment with the following
-.I op
-values:
-.TP
-.BR SHM_LOCK " (Linux-specific)"
-Prevent swapping of the shared memory segment.
-The caller must fault in
-any pages that are required to be present after locking is enabled.
-If a segment has been locked, then the (nonstandard)
-.B SHM_LOCKED
-flag of the
-.I shm_perm.mode
-field in the associated data structure retrieved by
-.B IPC_STAT
-will be set.
-.TP
-.BR SHM_UNLOCK " (Linux-specific)"
-Unlock the segment, allowing it to be swapped out.
-.P
-Before Linux 2.6.10, only a privileged process
-could employ
-.B SHM_LOCK
-and
-.BR SHM_UNLOCK .
-Since Linux 2.6.10, an unprivileged process can employ these operations
-if its effective UID matches the owner or creator UID of the segment, and
-(for
-.BR SHM_LOCK )
-the amount of memory to be locked falls within the
-.B RLIMIT_MEMLOCK
-resource limit (see
-.BR setrlimit (2)).
-.\" There was some weirdness in Linux 2.6.9: SHM_LOCK and SHM_UNLOCK could
-.\" be applied to a segment, regardless of ownership of the segment.
-.\" This was a botch-up in the move to RLIMIT_MEMLOCK, and was fixed
-.\" in Linux 2.6.10. MTK, May 2005
-.SH RETURN VALUE
-A successful
-.B IPC_INFO
-or
-.B SHM_INFO
-operation returns the index of the highest used entry in the
-kernel's internal array recording information about all
-shared memory segments.
-(This information can be used with repeated
-.B SHM_STAT
-or
-.B SHM_STAT_ANY
-operations to obtain information about all shared memory segments
-on the system.)
-A successful
-.B SHM_STAT
-operation returns the identifier of the shared memory segment
-whose index was given in
-.IR shmid .
-Other operations return 0 on success.
-.P
-On error, \-1 is returned, and
-.I errno
-is set to indicate the error.
-.SH ERRORS
-.TP
-.B EACCES
-\fBIPC_STAT\fP or \fBSHM_STAT\fP is requested and
-\fIshm_perm.mode\fP does not allow read access for
-.IR shmid ,
-and the calling process does not have the
-.B CAP_IPC_OWNER
-capability in the user namespace that governs its IPC namespace.
-.TP
-.B EFAULT
-The argument
-.I op
-has value
-.B IPC_SET
-or
-.B IPC_STAT
-but the address pointed to by
-.I buf
-isn't accessible.
-.TP
-.B EIDRM
-\fIshmid\fP points to a removed identifier.
-.TP
-.B EINVAL
-.I shmid
-is not a valid identifier, or
-.I op
-is not a valid operation.
-Or: for a
-.B SHM_STAT
-or
-.B SHM_STAT_ANY
-operation, the index value specified in
-.I shmid
-referred to an array slot that is currently unused.
-.TP
-.B ENOMEM
-(Since Linux 2.6.9),
-.B SHM_LOCK
-was specified and the size of the to-be-locked segment would mean
-that the total bytes in locked shared memory segments would exceed
-the limit for the real user ID of the calling process.
-This limit is defined by the
-.B RLIMIT_MEMLOCK
-soft resource limit (see
-.BR setrlimit (2)).
-.TP
-.B EOVERFLOW
-\fBIPC_STAT\fP is attempted, and the GID or UID value
-is too large to be stored in the structure pointed to by
-.IR buf .
-.TP
-.B EPERM
-\fBIPC_SET\fP or \fBIPC_RMID\fP is attempted, and the
-effective user ID of the calling process is not that of the creator
-(found in
-.IR shm_perm.cuid ),
-or the owner
-(found in
-.IR shm_perm.uid ),
-and the process was not privileged (Linux: did not have the
-.B CAP_SYS_ADMIN
-capability).
-.IP
-Or (before Linux 2.6.9),
-.B SHM_LOCK
-or
-.B SHM_UNLOCK
-was specified, but the process was not privileged
-(Linux: did not have the
-.B CAP_IPC_LOCK
-capability).
-(Since Linux 2.6.9, this error can also occur if the
-.B RLIMIT_MEMLOCK
-is 0 and the caller is not privileged.)
-.SH VERSIONS
-Linux permits a process to attach
-.RB ( shmat (2))
-a shared memory segment that has already been marked for deletion
-using
-.IR shmctl(IPC_RMID) .
-This feature is not available on other UNIX implementations;
-portable applications should avoid relying on it.
-.SH STANDARDS
-POSIX.1-2008.
-.SH HISTORY
-POSIX.1-2001, SVr4.
-.\" SVr4 documents additional error conditions EINVAL,
-.\" ENOENT, ENOSPC, ENOMEM, EEXIST. Neither SVr4 nor SVID documents
-.\" an EIDRM error condition.
-.P
-Various fields in a \fIstruct shmid_ds\fP were typed as
-.I short
-under Linux 2.2
-and have become
-.I long
-under Linux 2.4.
-To take advantage of this,
-a recompilation under glibc-2.1.91 or later should suffice.
-(The kernel distinguishes old and new calls by an
-.B IPC_64
-flag in
-.IR op .)
-.SH NOTES
-The
-.BR IPC_INFO ,
-.BR SHM_STAT ,
-and
-.B SHM_INFO
-operations are used by the
-.BR ipcs (1)
-program to provide information on allocated resources.
-In the future, these may modified or moved to a
-.I /proc
-filesystem interface.
-.SH SEE ALSO
-.BR mlock (2),
-.BR setrlimit (2),
-.BR shmget (2),
-.BR shmop (2),
-.BR capabilities (7),
-.BR sysvipc (7)