1SHMCTL(2)                  Linux Programmer's Manual                 SHMCTL(2)
2
3
4

NAME

6       shmctl - System V shared memory control
7

SYNOPSIS

9       #include <sys/shm.h>
10
11       int shmctl(int shmid, int cmd, struct shmid_ds *buf);
12

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

CONFORMING TO

246       POSIX.1-2001, POSIX.1-2008, SVr4.
247

NOTES

249       The IPC_INFO, SHM_STAT, and SHM_INFO operations are used by the ipcs(1)
250       program  to provide information on allocated resources.  In the future,
251       these may modified or moved to a /proc filesystem interface.
252
253       Linux permits a process to attach (shmat(2)) a  shared  memory  segment
254       that has already been marked for deletion using shmctl(IPC_RMID).  This
255       feature is not available on other UNIX implementations; portable appli‐
256       cations should avoid relying on it.
257
258       Various fields in a struct shmid_ds were typed as short under Linux 2.2
259       and have become long under Linux 2.4.  To take advantage of this, a re‐
260       compilation  under  glibc-2.1.91  or later should suffice.  (The kernel
261       distinguishes old and new calls by an IPC_64 flag in cmd.)
262

SEE ALSO

264       mlock(2),   setrlimit(2),   shmget(2),    shmop(2),    capabilities(7),
265       sysvipc(7)
266

COLOPHON

268       This  page  is  part of release 5.13 of the Linux man-pages project.  A
269       description of the project, information about reporting bugs,  and  the
270       latest     version     of     this    page,    can    be    found    at
271       https://www.kernel.org/doc/man-pages/.
272
273
274
275Linux                             2021-03-22                         SHMCTL(2)
Impressum