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_cpid ID of the process that created the shared memory segment.
42 shm_lpid ID of the last process that executed a shmat(2) or shmdt(2)
44 system call on this segment.
45 shm_nattch Number of processes that have this segment attached.
47 shm_atime Time of the last shmat(2) system call that attached this
49 segment.
50 shm_dtime Time of the last shmdt(2) system call that detached tgis
52 segment.
53 shm_ctime Time of creation of segment or time of the last shmctl()
55 IPC_SET operation.
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 can be changed: shm_perm.uid, shm_perm.gid,
98 and (the least significant 9 bits of) shm_perm.mode. The effec‐
99 tive UID of the calling process must match the owner
100 (shm_perm.uid) or creator (shm_perm.cuid) of the shared memory
101 segment, or the caller must be privileged.
102 IPC_RMID
104 Mark the segment to be destroyed. The segment will actually be
105 destroyed only after the last process detaches it (i.e., when
106 the shm_nattch member of the associated structure shmid_ds is
107 zero). The caller must be the owner or creator of the segment,
108 or be privileged. The buf argument is ignored.
109 If a segment has been marked for destruction, then the (nonstan‐
111 dard) SHM_DEST flag of the shm_perm.mode field in the associated
112 data structure retrieved by IPC_STAT will be set.
113 The caller must ensure that a segment is eventually destroyed;
115 otherwise its pages that were faulted in will remain in memory
116 or swap.
117 See also the description of /proc/sys/kernel/shm_rmid_forced in
119 proc(5).
120 IPC_INFO (Linux-specific)
122 Return information about system-wide shared memory limits and
123 parameters in the structure pointed to by buf. This structure
124 is of type shminfo (thus, a cast is required), defined in
125 <sys/shm.h> if the _GNU_SOURCE feature test macro is defined:
126 struct shminfo {
128 unsigned long shmmax; /* Maximum segment size */
129 unsigned long shmmin; /* Minimum segment size;
130 always 1 */
131 unsigned long shmmni; /* Maximum number of segments */
132 unsigned long shmseg; /* Maximum number of segments
133 that a process can attach;
134 unused within kernel */
135 unsigned long shmall; /* Maximum number of pages of
136 shared memory, system-wide */
137 };
138 The shmmni, shmmax, and shmall settings can be changed via /proc
140 files of the same name; see proc(5) for details.
141 SHM_INFO (Linux-specific)
143 Return a shm_info structure whose fields contain information
144 about system resources consumed by shared memory. This struc‐
145 ture is defined in <sys/shm.h> if the _GNU_SOURCE feature test
146 macro is defined:
147 struct shm_info {
149 int used_ids; /* # of currently existing
150 segments */
151 unsigned long shm_tot; /* Total number of shared
152 memory pages */
153 unsigned long shm_rss; /* # of resident shared
154 memory pages */
155 unsigned long shm_swp; /* # of swapped shared
156 memory pages */
157 unsigned long swap_attempts;
158 /* Unused since Linux 2.4 */
159 unsigned long swap_successes;
160 /* Unused since Linux 2.4 */
161 };
162 SHM_STAT (Linux-specific)
164 Return a shmid_ds structure as for IPC_STAT. However, the shmid
165 argument is not a segment identifier, but instead an index into
166 the kernel's internal array that maintains information about all
167 shared memory segments on the system.
168 SHM_STAT_ANY (Linux-specific, since Linux 4.17)
170 Return a shmid_ds structure as for SHM_STAT. However,
171 shm_perm.mode is not checked for read access for shmid, meaning
172 that any user can employ this operation (just as any user may
173 read /proc/sysvipc/shm to obtain the same information).
174 The caller can prevent or allow swapping of a shared memory segment
176 with the following cmd values:
177 SHM_LOCK (Linux-specific)
179 Prevent swapping of the shared memory segment. The caller must
180 fault in any pages that are required to be present after locking
181 is enabled. If a segment has been locked, then the (nonstan‐
182 dard) SHM_LOCKED flag of the shm_perm.mode field in the associ‐
183 ated data structure retrieved by IPC_STAT will be set.
184 SHM_UNLOCK (Linux-specific)
186 Unlock the segment, allowing it to be swapped out.
187 In kernels before 2.6.10, only a privileged process could employ
189 SHM_LOCK and SHM_UNLOCK. Since kernel 2.6.10, an unprivileged process
190 can employ these operations if its effective UID matches the owner or
191 creator UID of the segment, and (for SHM_LOCK) the amount of memory to
192 be locked falls within the RLIMIT_MEMLOCK resource limit (see setr‐
193 limit(2)).
194
196 A successful IPC_INFO or SHM_INFO operation returns the index of the
197 highest used entry in the kernel's internal array recording information
198 about all shared memory segments. (This information can be used with
199 repeated SHM_STAT or SHM_STAT_ANY operations to obtain information
200 about all shared memory segments on the system.) A successful SHM_STAT
201 operation returns the identifier of the shared memory segment whose
202 index was given in shmid. Other operations return 0 on success.
203 On error, -1 is returned, and errno is set appropriately.
205
207 EACCES IPC_STAT or SHM_STAT is requested and shm_perm.mode does not
208 allow read access for shmid, and the calling process does not
209 have the CAP_IPC_OWNER capability in the user namespace that
210 governs its IPC namespace.
211 EFAULT The argument cmd has value IPC_SET or IPC_STAT but the address
213 pointed to by buf isn't accessible.
214 EIDRM shmid points to a removed identifier.
216 EINVAL shmid is not a valid identifier, or cmd is not a valid command.
218 Or: for a SHM_STAT or SHM_STAT_ANY operation, the index value
219 specified in shmid referred to an array slot that is currently
220 unused.
221 ENOMEM (In kernels since 2.6.9), SHM_LOCK was specified and the size of
223 the to-be-locked segment would mean that the total bytes in
224 locked shared memory segments would exceed the limit for the
225 real user ID of the calling process. This limit is defined by
226 the RLIMIT_MEMLOCK soft resource limit (see setrlimit(2)).
227 EOVERFLOW
229 IPC_STAT is attempted, and the GID or UID value is too large to
230 be stored in the structure pointed to by buf.
231 EPERM IPC_SET or IPC_RMID is attempted, and the effective user ID of
233 the calling process is not that of the creator (found in
234 shm_perm.cuid), or the owner (found in shm_perm.uid), and the
235 process was not privileged (Linux: did not have the
236 CAP_SYS_ADMIN capability).
237 Or (in kernels before 2.6.9), SHM_LOCK or SHM_UNLOCK was speci‐
239 fied, but the process was not privileged (Linux: did not have
240 the CAP_IPC_LOCK capability). (Since Linux 2.6.9, this error
241 can also occur if the RLIMIT_MEMLOCK is 0 and the caller is not
242 privileged.)
243
245 POSIX.1-2001, POSIX.1-2008, SVr4.
246
248 The inclusion of <sys/types.h> and <sys/ipc.h> isn't required on Linux
249 or by any version of POSIX. However, some old implementations required
250 the inclusion of these header files, and the SVID also documented their
251 inclusion. Applications intended to be portable to such old systems
252 may need to include these header files.
253 The IPC_INFO, SHM_STAT and SHM_INFO operations are used by the ipcs(1)
255 program to provide information on allocated resources. In the future,
256 these may modified or moved to a /proc filesystem interface.
257 Linux permits a process to attach (shmat(2)) a shared memory segment
259 that has already been marked for deletion using shmctl(IPC_RMID). This
260 feature is not available on other UNIX implementations; portable appli‐
261 cations should avoid relying on it.
262 Various fields in a struct shmid_ds were typed as short under Linux 2.2
264 and have become long under Linux 2.4. To take advantage of this, a
265 recompilation under glibc-2.1.91 or later should suffice. (The kernel
266 distinguishes old and new calls by an IPC_64 flag in cmd.)
267
269 mlock(2), setrlimit(2), shmget(2), shmop(2), capabilities(7),
270 sysvipc(7)
271
273 This page is part of release 5.07 of the Linux man-pages project. A
274 description of the project, information about reporting bugs, and the
275 latest version of this page, can be found at
276 https://www.kernel.org/doc/man-pages/.
277Linux 2020-04-11 SHMCTL(2)