| .\" 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> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .\" 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 kernel 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 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| shmctl \- System V shared memory control |
| .SH SYNOPSIS |
| .nf |
| .ad l |
| .B #include <sys/ipc.h> |
| .B #include <sys/shm.h> |
| .PP |
| .BI "int shmctl(int " shmid ", int " cmd ", struct shmid_ds *" buf ); |
| .ad b |
| .fi |
| .SH DESCRIPTION |
| .BR shmctl () |
| performs the control operation specified by |
| .I cmd |
| on the System\ V shared memory segment whose identifier is given in |
| .IR shmid . |
| .PP |
| The |
| .I buf |
| argument is a pointer to a \fIshmid_ds\fP structure, |
| defined in \fI<sys/shm.h>\fP as follows: |
| .PP |
| .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 |
| .PP |
| 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 () |
| .BR 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. |
| .PP |
| The |
| .I ipc_perm |
| structure is defined as follows |
| (the highlighted fields are settable using |
| .BR IPC_SET ): |
| .PP |
| .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 |
| .PP |
| 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 |
| .PP |
| 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.) |
| .PP |
| Valid values for |
| .I cmd |
| 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 |
| .IR /proc/sysvipc/shm |
| to obtain the same information). |
| .PP |
| The caller can prevent or allow swapping of a shared |
| memory segment with the following \fIcmd\fP 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. |
| .PP |
| In kernels before 2.6.10, only a privileged process |
| could employ |
| .B SHM_LOCK |
| and |
| .BR SHM_UNLOCK . |
| Since kernel 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 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 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. |
| .PP |
| 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 cmd |
| 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 |
| \fIshmid\fP is not a valid identifier, or \fIcmd\fP |
| is not a valid command. |
| 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 |
| (In kernels since 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 (in kernels before 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 CONFORMING TO |
| POSIX.1-2001, POSIX.1-2008, SVr4. |
| .\" SVr4 documents additional error conditions EINVAL, |
| .\" ENOENT, ENOSPC, ENOMEM, EEXIST. Neither SVr4 nor SVID documents |
| .\" an EIDRM error condition. |
| .SH NOTES |
| The inclusion of |
| .I <sys/ipc.h> |
| isn't required on Linux or by any version of POSIX. |
| However, |
| some old implementations required the inclusion of this header file, |
| and the SVID also documented its inclusion. |
| Applications intended to be portable to such old systems may need |
| to include this header file. |
| .\" Like Linux, the FreeBSD man pages still document |
| .\" the inclusion of this header file. |
| .PP |
| 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. |
| .PP |
| 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. |
| .PP |
| 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 cmd .) |
| .SH SEE ALSO |
| .BR mlock (2), |
| .BR setrlimit (2), |
| .BR shmget (2), |
| .BR shmop (2), |
| .BR capabilities (7), |
| .BR sysvipc (7) |