1SHMCTL(2) Linux Programmer's Manual SHMCTL(2)
2
6 shmctl - System V shared memory control
7
9 #include <sys/ipc.h>
10 #include <sys/shm.h>
11 int shmctl(int shmid, int cmd, struct shmid_ds *buf);
13
15 shmctl() performs the control operation specified by cmd on the Sys‐
16 tem V shared memory segment whose identifier is given in shmid.
17 The buf argument is a pointer to a shmid_ds structure, defined in
19 <sys/shm.h> as follows:
20 struct shmid_ds {
22 struct ipc_perm shm_perm; /* Ownership and permissions */
23 size_t shm_segsz; /* Size of segment (bytes) */
24 time_t shm_atime; /* Last attach time */
25 time_t shm_dtime; /* Last detach time */
26 time_t shm_ctime; /* Creation time/time of last
27 modification via shmctl() */
28 pid_t shm_cpid; /* PID of creator */
29 pid_t shm_lpid; /* PID of last shmat(2)/shmdt(2) */
30 shmatt_t shm_nattch; /* No. of current attaches */
31 ...
32 };
33 The fields of the shmid_ds structure are as follows:
35 shm_perm This is an ipc_perm structure (see below) that specifies
37 the access permissions on the shared memory segment.
38 shm_segsz Size in bytes of the shared memory segment.
40 shm_atime Time of the last shmat(2) system call that attached this
42 segment.
43 shm_dtime Time of the last shmdt(2) system call that detached tgis
45 segment.
46 shm_ctime Time of creation of segment or time of the last shmctl()
48 IPC_SET operation.
49 shm_cpid ID of the process that created the shared memory segment.
51 shm_lpid ID of the last process that executed a shmat(2) or shmdt(2)
53 system call on this segment.
54 shm_nattch Number of processes that have this segment attached.
56 The ipc_perm structure is defined as follows (the highlighted fields
58 are settable using IPC_SET):
59 struct ipc_perm {
61 key_t __key; /* Key supplied to shmget(2) */
62 uid_t uid; /* Effective UID of owner */
63 gid_t gid; /* Effective GID of owner */
64 uid_t cuid; /* Effective UID of creator */
65 gid_t cgid; /* Effective GID of creator */
66 unsigned short mode; /* Permissions + SHM_DEST and
67 SHM_LOCKED flags */
68 unsigned short __seq; /* Sequence number */
69 };
70 The least significant 9 bits of the mode field of the ipc_perm struc‐
72 ture define the access permissions for the shared memory segment. The
73 permission bits are as follows:
74 0400 Read by user
76 0200 Write by user
77 0040 Read by group
78 0020 Write by group
79 0004 Read by others
80 0002 Write by others
81 Bits 0100, 0010, and 0001 (the execute bits) are unused by the system.
83 (It is not necessary to have execute permission on a segment in order
84 to perform a shmat(2) call with the SHM_EXEC flag.)
85 Valid values for cmd are:
87 IPC_STAT
89 Copy information from the kernel data structure associated with
90 shmid into the shmid_ds structure pointed to by buf. The caller
91 must have read permission on the shared memory segment.
92 IPC_SET
94 Write the values of some members of the shmid_ds structure
95 pointed to by buf to the kernel data structure associated with
96 this shared memory segment, updating also its shm_ctime member.
97 The following fields are updated: shm_perm.uid, shm_perm.gid,
99 and (the least significant 9 bits of) shm_perm.mode.
100 The effective UID of the calling process must match the owner
102 (shm_perm.uid) or creator (shm_perm.cuid) of the shared memory
103 segment, or the caller must be privileged.
104 IPC_RMID
106 Mark the segment to be destroyed. The segment will actually be
107 destroyed only after the last process detaches it (i.e., when
108 the shm_nattch member of the associated structure shmid_ds is
109 zero). The caller must be the owner or creator of the segment,
110 or be privileged. The buf argument is ignored.
111 If a segment has been marked for destruction, then the (nonstan‐
113 dard) SHM_DEST flag of the shm_perm.mode field in the associated
114 data structure retrieved by IPC_STAT will be set.
115 The caller must ensure that a segment is eventually destroyed;
117 otherwise its pages that were faulted in will remain in memory
118 or swap.
119 See also the description of /proc/sys/kernel/shm_rmid_forced in
121 proc(5).
122 IPC_INFO (Linux-specific)
124 Return information about system-wide shared memory limits and
125 parameters in the structure pointed to by buf. This structure
126 is of type shminfo (thus, a cast is required), defined in
127 <sys/shm.h> if the _GNU_SOURCE feature test macro is defined:
128 struct shminfo {
130 unsigned long shmmax; /* Maximum segment size */
131 unsigned long shmmin; /* Minimum segment size;
132 always 1 */
133 unsigned long shmmni; /* Maximum number of segments */
134 unsigned long shmseg; /* Maximum number of segments
135 that a process can attach;
136 unused within kernel */
137 unsigned long shmall; /* Maximum number of pages of
138 shared memory, system-wide */
139 };
140 The shmmni, shmmax, and shmall settings can be changed via /proc
142 files of the same name; see proc(5) for details.
143 SHM_INFO (Linux-specific)
145 Return a shm_info structure whose fields contain information
146 about system resources consumed by shared memory. This struc‐
147 ture is defined in <sys/shm.h> if the _GNU_SOURCE feature test
148 macro is defined:
149 struct shm_info {
151 int used_ids; /* # of currently existing
152 segments */
153 unsigned long shm_tot; /* Total number of shared
154 memory pages */
155 unsigned long shm_rss; /* # of resident shared
156 memory pages */
157 unsigned long shm_swp; /* # of swapped shared
158 memory pages */
159 unsigned long swap_attempts;
160 /* Unused since Linux 2.4 */
161 unsigned long swap_successes;
162 /* Unused since Linux 2.4 */
163 };
164 SHM_STAT (Linux-specific)
166 Return a shmid_ds structure as for IPC_STAT. However, the shmid
167 argument is not a segment identifier, but instead an index into
168 the kernel's internal array that maintains information about all
169 shared memory segments on the system.
170 SHM_STAT_ANY (Linux-specific, since Linux 4.17)
172 Return a shmid_ds structure as for SHM_STAT. However,
173 shm_perm.mode is not checked for read access for shmid, meaning
174 that any user can employ this operation (just as any user may
175 read /proc/sysvipc/shm to obtain the same information).
176 The caller can prevent or allow swapping of a shared memory segment
178 with the following cmd values:
179 SHM_LOCK (Linux-specific)
181 Prevent swapping of the shared memory segment. The caller must
182 fault in any pages that are required to be present after locking
183 is enabled. If a segment has been locked, then the (nonstan‐
184 dard) SHM_LOCKED flag of the shm_perm.mode field in the associ‐
185 ated data structure retrieved by IPC_STAT will be set.
186 SHM_UNLOCK (Linux-specific)
188 Unlock the segment, allowing it to be swapped out.
189 In kernels before 2.6.10, only a privileged process could employ
191 SHM_LOCK and SHM_UNLOCK. Since kernel 2.6.10, an unprivileged process
192 can employ these operations if its effective UID matches the owner or
193 creator UID of the segment, and (for SHM_LOCK) the amount of memory to
194 be locked falls within the RLIMIT_MEMLOCK resource limit (see setr‐
195 limit(2)).
196
198 A successful IPC_INFO or SHM_INFO operation returns the index of the
199 highest used entry in the kernel's internal array recording information
200 about all shared memory segments. (This information can be used with
201 repeated SHM_STAT or SHM_STAT_ANY operations to obtain information
202 about all shared memory segments on the system.) A successful SHM_STAT
203 operation returns the identifier of the shared memory segment whose in‐
204 dex was given in shmid. Other operations return 0 on success.
205 On error, -1 is returned, and errno is set appropriately.
207
209 EACCES IPC_STAT or SHM_STAT is requested and shm_perm.mode does not al‐
210 low read access for shmid, and the calling process does not have
211 the CAP_IPC_OWNER capability in the user namespace that governs
212 its IPC namespace.
213 EFAULT The argument cmd has value IPC_SET or IPC_STAT but the address
215 pointed to by buf isn't accessible.
216 EIDRM shmid points to a removed identifier.
218 EINVAL shmid is not a valid identifier, or cmd is not a valid command.
220 Or: for a SHM_STAT or SHM_STAT_ANY operation, the index value
221 specified in shmid referred to an array slot that is currently
222 unused.
223 ENOMEM (In kernels since 2.6.9), SHM_LOCK was specified and the size of
225 the to-be-locked segment would mean that the total bytes in
226 locked shared memory segments would exceed the limit for the
227 real user ID of the calling process. This limit is defined by
228 the RLIMIT_MEMLOCK soft resource limit (see setrlimit(2)).
229 EOVERFLOW
231 IPC_STAT is attempted, and the GID or UID value is too large to
232 be stored in the structure pointed to by buf.
233 EPERM IPC_SET or IPC_RMID is attempted, and the effective user ID of
235 the calling process is not that of the creator (found in
236 shm_perm.cuid), or the owner (found in shm_perm.uid), and the
237 process was not privileged (Linux: did not have the CAP_SYS_AD‐
238 MIN capability).
239 Or (in kernels before 2.6.9), SHM_LOCK or SHM_UNLOCK was speci‐
241 fied, but the process was not privileged (Linux: did not have
242 the CAP_IPC_LOCK capability). (Since Linux 2.6.9, this error
243 can also occur if the RLIMIT_MEMLOCK is 0 and the caller is not
244 privileged.)
245
247 POSIX.1-2001, POSIX.1-2008, SVr4.
248
250 The inclusion of <sys/types.h> and <sys/ipc.h> isn't required on Linux
251 or by any version of POSIX. However, some old implementations required
252 the inclusion of these header files, and the SVID also documented their
253 inclusion. Applications intended to be portable to such old systems
254 may need to include these header files.
255 The IPC_INFO, SHM_STAT, and SHM_INFO operations are used by the ipcs(1)
257 program to provide information on allocated resources. In the future,
258 these may modified or moved to a /proc filesystem interface.
259 Linux permits a process to attach (shmat(2)) a shared memory segment
261 that has already been marked for deletion using shmctl(IPC_RMID). This
262 feature is not available on other UNIX implementations; portable appli‐
263 cations should avoid relying on it.
264 Various fields in a struct shmid_ds were typed as short under Linux 2.2
266 and have become long under Linux 2.4. To take advantage of this, a re‐
267 compilation under glibc-2.1.91 or later should suffice. (The kernel
268 distinguishes old and new calls by an IPC_64 flag in cmd.)
269
271 mlock(2), setrlimit(2), shmget(2), shmop(2), capabilities(7),
272 sysvipc(7)
273
275 This page is part of release 5.10 of the Linux man-pages project. A
276 description of the project, information about reporting bugs, and the
277 latest version of this page, can be found at
278 https://www.kernel.org/doc/man-pages/.
279Linux 2020-12-21 SHMCTL(2)