diff options
Diffstat (limited to 'man2/shmctl.2')
| -rw-r--r-- | man2/shmctl.2 | 494 |
1 files changed, 0 insertions, 494 deletions
diff --git a/man2/shmctl.2 b/man2/shmctl.2 deleted file mode 100644 index 986268957..000000000 --- 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 (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) |