1shmctl(2)                     System Calls Manual                    shmctl(2)
2
3
4

NAME

6       shmctl - System V shared memory control
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <sys/shm.h>
13
14       int shmctl(int shmid, int cmd, struct shmid_ds *buf);
15

DESCRIPTION

17       shmctl()  performs  the  control operation specified by cmd on the Sys‐
18       tem V shared memory segment whose identifier is given in shmid.
19
20       The buf argument is a pointer  to  a  shmid_ds  structure,  defined  in
21       <sys/shm.h> as follows:
22
23           struct shmid_ds {
24               struct ipc_perm shm_perm;    /* Ownership and permissions */
25               size_t          shm_segsz;   /* Size of segment (bytes) */
26               time_t          shm_atime;   /* Last attach time */
27               time_t          shm_dtime;   /* Last detach time */
28               time_t          shm_ctime;   /* Creation time/time of last
29                                               modification via shmctl() */
30               pid_t           shm_cpid;    /* PID of creator */
31               pid_t           shm_lpid;    /* PID of last shmat(2)/shmdt(2) */
32               shmatt_t        shm_nattch;  /* No. of current attaches */
33               ...
34           };
35
36       The fields of the shmid_ds structure are as follows:
37
38       shm_perm    This  is  an  ipc_perm structure (see below) that specifies
39                   the access permissions on the shared memory segment.
40
41       shm_segsz   Size in bytes of the shared memory segment.
42
43       shm_atime   Time of the last shmat(2) system call  that  attached  this
44                   segment.
45
46       shm_dtime   Time  of  the  last shmdt(2) system call that detached tgis
47                   segment.
48
49       shm_ctime   Time of creation of segment or time of  the  last  shmctl()
50                   IPC_SET operation.
51
52       shm_cpid    ID of the process that created the shared memory segment.
53
54       shm_lpid    ID of the last process that executed a shmat(2) or shmdt(2)
55                   system call on this segment.
56
57       shm_nattch  Number of processes that have this segment attached.
58
59       The ipc_perm structure is defined as follows  (the  highlighted  fields
60       are settable using IPC_SET):
61
62           struct ipc_perm {
63               key_t          __key;    /* Key supplied to shmget(2) */
64               uid_t          uid;      /* Effective UID of owner */
65               gid_t          gid;      /* Effective GID of owner */
66               uid_t          cuid;     /* Effective UID of creator */
67               gid_t          cgid;     /* Effective GID of creator */
68               unsigned short mode;     /* Permissions + SHM_DEST and
69                                           SHM_LOCKED flags */
70               unsigned short __seq;    /* Sequence number */
71           };
72
73       The  least  significant 9 bits of the mode field of the ipc_perm struc‐
74       ture define the access permissions for the shared memory segment.   The
75       permission bits are as follows:
76
77       0400   Read by user
78       0200   Write by user
79       0040   Read by group
80       0020   Write by group
81       0004   Read by others
82       0002   Write by others
83
84       Bits  0100, 0010, and 0001 (the execute bits) are unused by the system.
85       (It is not necessary to have execute permission on a segment  in  order
86       to perform a shmat(2) call with the SHM_EXEC flag.)
87
88       Valid values for cmd are:
89
90       IPC_STAT
91              Copy  information from the kernel data structure associated with
92              shmid into the shmid_ds structure pointed to by buf.  The caller
93              must have read permission on the shared memory segment.
94
95       IPC_SET
96              Write  the  values  of  some  members  of the shmid_ds structure
97              pointed to by buf to the kernel data structure  associated  with
98              this shared memory segment, updating also its shm_ctime member.
99
100              The  following  fields  are updated: shm_perm.uid, shm_perm.gid,
101              and (the least significant 9 bits of) shm_perm.mode.
102
103              The effective UID of the calling process must  match  the  owner
104              (shm_perm.uid)  or  creator (shm_perm.cuid) of the shared memory
105              segment, or the caller must be privileged.
106
107       IPC_RMID
108              Mark the segment to be destroyed.  The segment will actually  be
109              destroyed  only  after  the last process detaches it (i.e., when
110              the shm_nattch member of the associated  structure  shmid_ds  is
111              zero).   The caller must be the owner or creator of the segment,
112              or be privileged.  The buf argument is ignored.
113
114              If a segment has been marked for destruction, then the (nonstan‐
115              dard) SHM_DEST flag of the shm_perm.mode field in the associated
116              data structure retrieved by IPC_STAT will be set.
117
118              The caller must ensure that a segment is  eventually  destroyed;
119              otherwise  its  pages that were faulted in will remain in memory
120              or swap.
121
122              See also the description of /proc/sys/kernel/shm_rmid_forced  in
123              proc(5).
124
125       IPC_INFO (Linux-specific)
126              Return  information  about  system-wide shared memory limits and
127              parameters in the structure pointed to by buf.   This  structure
128              is  of  type  shminfo  (thus,  a  cast  is required), defined in
129              <sys/shm.h> if the _GNU_SOURCE feature test macro is defined:
130
131                  struct shminfo {
132                      unsigned long shmmax; /* Maximum segment size */
133                      unsigned long shmmin; /* Minimum segment size;
134                                               always 1 */
135                      unsigned long shmmni; /* Maximum number of segments */
136                      unsigned long shmseg; /* Maximum number of segments
137                                               that a process can attach;
138                                               unused within kernel */
139                      unsigned long shmall; /* Maximum number of pages of
140                                               shared memory, system-wide */
141                  };
142
143              The shmmni, shmmax, and shmall settings can be changed via /proc
144              files of the same name; see proc(5) for details.
145
146       SHM_INFO (Linux-specific)
147              Return  a  shm_info  structure  whose fields contain information
148              about system resources consumed by shared memory.   This  struc‐
149              ture  is  defined in <sys/shm.h> if the _GNU_SOURCE feature test
150              macro is defined:
151
152                  struct shm_info {
153                      int           used_ids; /* # of currently existing
154                                                 segments */
155                      unsigned long shm_tot;  /* Total number of shared
156                                                 memory pages */
157                      unsigned long shm_rss;  /* # of resident shared
158                                                 memory pages */
159                      unsigned long shm_swp;  /* # of swapped shared
160                                                 memory pages */
161                      unsigned long swap_attempts;
162                                              /* Unused since Linux 2.4 */
163                      unsigned long swap_successes;
164                                              /* Unused since Linux 2.4 */
165                  };
166
167       SHM_STAT (Linux-specific)
168              Return a shmid_ds structure as for IPC_STAT.  However, the shmid
169              argument  is not a segment identifier, but instead an index into
170              the kernel's internal array that maintains information about all
171              shared memory segments on the system.
172
173       SHM_STAT_ANY (Linux-specific, since Linux 4.17)
174              Return   a   shmid_ds   structure  as  for  SHM_STAT.   However,
175              shm_perm.mode is not checked for read access for shmid,  meaning
176              that  any  user  can employ this operation (just as any user may
177              read /proc/sysvipc/shm to obtain the same information).
178
179       The caller can prevent or allow swapping of  a  shared  memory  segment
180       with the following cmd values:
181
182       SHM_LOCK (Linux-specific)
183              Prevent  swapping of the shared memory segment.  The caller must
184              fault in any pages that are required to be present after locking
185              is  enabled.   If  a segment has been locked, then the (nonstan‐
186              dard) SHM_LOCKED flag of the shm_perm.mode field in the  associ‐
187              ated data structure retrieved by IPC_STAT will be set.
188
189       SHM_UNLOCK (Linux-specific)
190              Unlock the segment, allowing it to be swapped out.
191
192       Before  Linux  2.6.10,  only a privileged process could employ SHM_LOCK
193       and SHM_UNLOCK.  Since Linux 2.6.10, an unprivileged process can employ
194       these  operations if its effective UID matches the owner or creator UID
195       of the segment, and (for SHM_LOCK) the amount of memory  to  be  locked
196       falls within the RLIMIT_MEMLOCK resource limit (see setrlimit(2)).
197

RETURN VALUE

199       A  successful  IPC_INFO  or SHM_INFO operation returns the index of the
200       highest used entry in the kernel's internal array recording information
201       about  all  shared memory segments.  (This information can be used with
202       repeated SHM_STAT or  SHM_STAT_ANY  operations  to  obtain  information
203       about all shared memory segments on the system.)  A successful SHM_STAT
204       operation returns the identifier of the shared memory segment whose in‐
205       dex was given in shmid.  Other operations return 0 on success.
206
207       On error, -1 is returned, and errno is set to indicate the error.
208

ERRORS

210       EACCES IPC_STAT or SHM_STAT is requested and shm_perm.mode does not al‐
211              low read access for shmid, and the calling process does not have
212              the  CAP_IPC_OWNER capability in the user namespace that governs
213              its IPC namespace.
214
215       EFAULT The argument cmd has value IPC_SET or IPC_STAT but  the  address
216              pointed to by buf isn't accessible.
217
218       EIDRM  shmid points to a removed identifier.
219
220       EINVAL shmid  is not a valid identifier, or cmd is not a valid command.
221              Or: for a SHM_STAT or SHM_STAT_ANY operation,  the  index  value
222              specified  in  shmid referred to an array slot that is currently
223              unused.
224
225       ENOMEM (Since Linux 2.6.9), SHM_LOCK was specified and the size of  the
226              to-be-locked  segment  would mean that the total bytes in locked
227              shared memory segments would exceed the limit for the real  user
228              ID  of  the  calling  process.   This  limit  is  defined by the
229              RLIMIT_MEMLOCK soft resource limit (see setrlimit(2)).
230
231       EOVERFLOW
232              IPC_STAT is attempted, and the GID or UID value is too large  to
233              be stored in the structure pointed to by buf.
234
235       EPERM  IPC_SET  or  IPC_RMID is attempted, and the effective user ID of
236              the calling process  is  not  that  of  the  creator  (found  in
237              shm_perm.cuid),  or  the  owner (found in shm_perm.uid), and the
238              process was not privileged (Linux: did not have the  CAP_SYS_AD‐
239              MIN capability).
240
241              Or  (before  Linux 2.6.9), SHM_LOCK or SHM_UNLOCK was specified,
242              but the process was not privileged  (Linux:  did  not  have  the
243              CAP_IPC_LOCK  capability).   (Since  Linux 2.6.9, this error can
244              also occur if the RLIMIT_MEMLOCK is 0  and  the  caller  is  not
245              privileged.)
246

VERSIONS

248       Linux  permits  a  process to attach (shmat(2)) a shared memory segment
249       that has already been marked for deletion using shmctl(IPC_RMID).  This
250       feature is not available on other UNIX implementations; portable appli‐
251       cations should avoid relying on it.
252

STANDARDS

254       POSIX.1-2008.
255

HISTORY

257       POSIX.1-2001, SVr4.
258
259       Various fields in a struct shmid_ds were typed as short under Linux 2.2
260       and have become long under Linux 2.4.  To take advantage of this, a re‐
261       compilation under glibc-2.1.91 or later should  suffice.   (The  kernel
262       distinguishes old and new calls by an IPC_64 flag in cmd.)
263

NOTES

265       The IPC_INFO, SHM_STAT, and SHM_INFO operations are used by the ipcs(1)
266       program to provide information on allocated resources.  In the  future,
267       these may modified or moved to a /proc filesystem interface.
268

SEE ALSO

270       mlock(2),    setrlimit(2),    shmget(2),   shmop(2),   capabilities(7),
271       sysvipc(7)
272
273
274
275Linux man-pages 6.04              2023-03-30                         shmctl(2)
Impressum