diff options
Diffstat (limited to 'man/man2/shmctl.2')
| -rw-r--r-- | man/man2/shmctl.2 | 494 |
1 files changed, 494 insertions, 0 deletions
diff --git a/man/man2/shmctl.2 b/man/man2/shmctl.2 new file mode 100644 index 000000000..986268957 --- /dev/null +++ b/man/man2/shmctl.2 @@ -0,0 +1,494 @@ +'\" 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 (date) "Linux man-pages (unreleased)" +.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) |