man2/shmctl.2

   1 .\" Copyright (c) 1993 Luigi P. Bai (lpb@softint.com) July 28, 1993
   2 .\" and Copyright 1993 Giorgio Ciucci <giorgio@crcc.it>
   3 .\" and Copyright 2004, 2005 Michael Kerrisk <mtk.manpages@gmail.com>
   4 .\"
   5 .\" %%%LICENSE_START(VERBATIM)
   6 .\" Permission is granted to make and distribute verbatim copies of this
   7 .\" manual provided the copyright notice and this permission notice are
   8 .\" preserved on all copies.
   9 .\"
  10 .\" Permission is granted to copy and distribute modified versions of this
  11 .\" manual under the conditions for verbatim copying, provided that the
  12 .\" entire resulting derived work is distributed under the terms of a
  13 .\" permission notice identical to this one.
  14 .\"
  15 .\" Since the Linux kernel and libraries are constantly changing, this
  16 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  17 .\" responsibility for errors or omissions, or for damages resulting from
  18 .\" the use of the information contained herein.  The author(s) may not
  19 .\" have taken the same level of care in the production of this manual,
  20 .\" which is licensed free of charge, as they might when working
  21 .\" professionally.
  22 .\"
  23 .\" Formatted or processed versions of this manual, if unaccompanied by
  24 .\" the source, must acknowledge the copyright and authors of this work.
  25 .\" %%%LICENSE_END
  26 .\"
  27 .\" Modified 1993-07-28, Rik Faith <faith@cs.unc.edu>
  28 .\" Modified 1993-11-28, Giorgio Ciucci <giorgio@crcc.it>
  29 .\" Modified 1997-01-31, Eric S. Raymond <esr@thyrsus.com>
  30 .\" Modified 2001-02-18, Andries Brouwer <aeb@cwi.nl>
  31 .\" Modified 2002-01-05, 2004-05-27, 2004-06-17,
  32 .\"    Michael Kerrisk <mtk.manpages@gmail.com>
  33 .\" Modified 2004-10-11, aeb
  34 .\" Modified, Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  35 .\"     Language and formatting clean-ups
  36 .\"     Updated shmid_ds structure definitions
  37 .\"     Added information on SHM_DEST and SHM_LOCKED flags
  38 .\"     Noted that CAP_IPC_LOCK is not required for SHM_UNLOCK
  39 .\"             since kernel 2.6.9
  40 .\" Modified, 2004-11-25, mtk, notes on 2.6.9 RLIMIT_MEMLOCK changes
  41 .\" 2005-04-25, mtk -- noted aberrant Linux behavior w.r.t. new
  42 .\"     attaches to a segment that has already been marked for deletion.
  43 .\" 2005-08-02, mtk: Added IPC_INFO, SHM_INFO, SHM_STAT descriptions.
  44 .\" 2018-03-20, dbueso: Added SHM_STAT_ANY description.
  45 .\"
  46 .TH SHMCTL 2 2017-09-15 "Linux" "Linux Programmer's Manual"
  47 .SH NAME
  48 shmctl \- System V shared memory control
  49 .SH SYNOPSIS
  50 .ad l
  51 .B #include <sys/ipc.h>
  52 .br
  53 .B #include <sys/shm.h>
  54 .PP
  55 .BI "int shmctl(int " shmid ", int " cmd ", struct shmid_ds *" buf );
  56 .ad b
  57 .SH DESCRIPTION
  58 .BR shmctl ()
  59 performs the control operation specified by
  60 .I cmd
  61 on the System\ V shared memory segment whose identifier is given in
  62 .IR shmid .
  63 .PP
  64 The
  65 .I buf
  66 argument is a pointer to a \fIshmid_ds\fP structure,
  67 defined in \fI<sys/shm.h>\fP as follows:
  68 .PP
  69 .in +4n
  70 .EX
  71 struct shmid_ds {
  72     struct ipc_perm shm_perm;    /* Ownership and permissions */
  73     size_t          shm_segsz;   /* Size of segment (bytes) */
  74     time_t          shm_atime;   /* Last attach time */
  75     time_t          shm_dtime;   /* Last detach time */
  76     time_t          shm_ctime;   /* Last change time */
  77     pid_t           shm_cpid;    /* PID of creator */
  78     pid_t           shm_lpid;    /* PID of last shmat(2)/shmdt(2) */
  79     shmatt_t        shm_nattch;  /* No. of current attaches */
  80     ...
  81 };
  82 .EE
  83 .in
  84 .PP
  85 The
  86 .I ipc_perm
  87 structure is defined as follows
  88 (the highlighted fields are settable using
  89 .BR IPC_SET ):
  90 .PP
  91 .in +4n
  92 .EX
  93 struct ipc_perm {
  94     key_t          __key;    /* Key supplied to shmget(2) */
  95     uid_t          \fBuid\fP;      /* Effective UID of owner */
  96     gid_t          \fBgid\fP;      /* Effective GID of owner */
  97     uid_t          cuid;     /* Effective UID of creator */
  98     gid_t          cgid;     /* Effective GID of creator */
  99     unsigned short \fBmode\fP;     /* \fBPermissions\fP + SHM_DEST and
 100                                 SHM_LOCKED flags */
 101     unsigned short __seq;    /* Sequence number */
 102 };
 103 .EE
 104 .in
 105 .PP
 106 Valid values for
 107 .I cmd
 108 are:
 109 .TP 10
 110 .B IPC_STAT
 111 Copy information from the kernel data structure associated with
 112 .I shmid
 113 into the
 114 .I shmid_ds
 115 structure pointed to by \fIbuf\fP.
 116 The caller must have read permission on the
 117 shared memory segment.
 118 .TP
 119 .B IPC_SET
 120 Write the values of some members of the
 121 .I shmid_ds
 122 structure pointed to by
 123 .I buf
 124 to the kernel data structure associated with this shared memory segment,
 125 updating also its
 126 .I shm_ctime
 127 member.
 128 The following fields can be changed:
 129 \fIshm_perm.uid\fP, \fIshm_perm.gid\fP,
 130 and (the least significant 9 bits of) \fIshm_perm.mode\fP.
 131 The effective UID of the calling process must match the owner
 132 .RI ( shm_perm.uid )
 133 or creator
 134 .RI ( shm_perm.cuid )
 135 of the shared memory segment, or the caller must be privileged.
 136 .TP
 137 .B IPC_RMID
 138 Mark the segment to be destroyed.
 139 The segment will actually be destroyed
 140 only after the last process detaches it (i.e., when the
 141 .I shm_nattch
 142 member of the associated structure
 143 .I shmid_ds
 144 is zero).
 145 The caller must be the owner or creator of the segment, or be privileged.
 146 The
 147 .I buf
 148 argument is ignored.
 149 .IP
 150 If a segment has been marked for destruction, then the (nonstandard)
 151 .B SHM_DEST
 152 flag of the
 153 .I shm_perm.mode
 154 field in the associated data structure retrieved by
 155 .B IPC_STAT
 156 will be set.
 157 .IP
 158 The caller \fImust\fP ensure that a segment is eventually destroyed;
 159 otherwise its pages that were faulted in will remain in memory or swap.
 160 .IP
 161 See also the description of
 162 .I  /proc/sys/kernel/shm_rmid_forced
 163 in
 164 .BR proc (5).
 165 .TP 10
 166 .BR IPC_INFO " (Linux-specific)"
 167 Return information about system-wide shared memory limits and
 168 parameters in the structure pointed to by
 169 .IR buf .
 170 This structure is of type
 171 .I shminfo
 172 (thus, a cast is required),
 173 defined in
 174 .I <sys/shm.h>
 175 if the
 176 .B _GNU_SOURCE
 177 feature test macro is defined:
 178 .IP
 179 .in +4n
 180 .EX
 181 struct shminfo {
 182     unsigned long shmmax; /* Maximum segment size */
 183     unsigned long shmmin; /* Minimum segment size;
 184                              always 1 */
 185     unsigned long shmmni; /* Maximum number of segments */
 186     unsigned long shmseg; /* Maximum number of segments
 187                              that a process can attach;
 188                              unused within kernel */
 189     unsigned long shmall; /* Maximum number of pages of
 190                              shared memory, system-wide */
 191 };
 192 .EE
 193 .in
 194 .IP
 195 The
 196 .IR shmmni ,
 197 .IR shmmax ,
 198 and
 199 .I shmall
 200 settings can be changed via
 201 .I /proc
 202 files of the same name; see
 203 .BR proc (5)
 204 for details.
 205 .TP
 206 .BR SHM_INFO " (Linux-specific)"
 207 Return a
 208 .I shm_info
 209 structure whose fields contain information
 210 about system resources consumed by shared memory.
 211 This structure is defined in
 212 .I <sys/shm.h>
 213 if the
 214 .B _GNU_SOURCE
 215 feature test macro is defined:
 216 .IP
 217 .in +4n
 218 .EX
 219 struct shm_info {
 220     int           used_ids; /* # of currently existing
 221                                segments */
 222     unsigned long shm_tot;  /* Total number of shared
 223                                memory pages */
 224     unsigned long shm_rss;  /* # of resident shared
 225                                memory pages */
 226     unsigned long shm_swp;  /* # of swapped shared
 227                                memory pages */
 228     unsigned long swap_attempts;
 229                             /* Unused since Linux 2.4 */
 230     unsigned long swap_successes;
 231                             /* Unused since Linux 2.4 */
 232 };
 233 .EE
 234 .in
 235 .TP
 236 .BR SHM_STAT " (Linux-specific)"
 237 Return a
 238 .I shmid_ds
 239 structure as for
 240 .BR IPC_STAT .
 241 However, the
 242 .I shmid
 243 argument is not a segment identifier, but instead an index into
 244 the kernel's internal array that maintains information about
 245 all shared memory segments on the system.
 246 .TP
 247 .BR SHM_STAT_ANY " (Linux-specific, since Linux 4.17)"
 248 Return a
 249 .I shmid_ds
 250 structure as for
 251 .BR SHM_STAT .
 252 However,
 253 .I shm_perm.mode
 254 is not checked for read access for
 255 .IR shmid ,
 256 meaning that any user can employ this operation (just as any user may read
 257 .IR /proc/sysvipc/shm
 258 to obtain the same information).
 259 .PP
 260 The caller can prevent or allow swapping of a shared
 261 memory segment with the following \fIcmd\fP values:
 262 .TP 10
 263 .BR SHM_LOCK " (Linux-specific)"
 264 Prevent swapping of the shared memory segment.
 265 The caller must fault in
 266 any pages that are required to be present after locking is enabled.
 267 If a segment has been locked, then the (nonstandard)
 268 .B SHM_LOCKED
 269 flag of the
 270 .I shm_perm.mode
 271 field in the associated data structure retrieved by
 272 .B IPC_STAT
 273 will be set.
 274 .TP
 275 .BR SHM_UNLOCK " (Linux-specific)"
 276 Unlock the segment, allowing it to be swapped out.
 277 .PP
 278 In kernels before 2.6.10, only a privileged process
 279 could employ
 280 .B SHM_LOCK
 281 and
 282 .BR SHM_UNLOCK .
 283 Since kernel 2.6.10, an unprivileged process can employ these operations
 284 if its effective UID matches the owner or creator UID of the segment, and
 285 (for
 286 .BR SHM_LOCK )
 287 the amount of memory to be locked falls within the
 288 .B RLIMIT_MEMLOCK
 289 resource limit (see
 290 .BR setrlimit (2)).
 291 .\" There was some weirdness in 2.6.9: SHM_LOCK and SHM_UNLOCK could
 292 .\" be applied to a segment, regardless of ownership of the segment.
 293 .\" This was a botch-up in the move to RLIMIT_MEMLOCK, and was fixed
 294 .\" in 2.6.10.  MTK, May 2005
 295 .SH RETURN VALUE
 296 A successful
 297 .B IPC_INFO
 298 or
 299 .B SHM_INFO
 300 operation returns the index of the highest used entry in the
 301 kernel's internal array recording information about all
 302 shared memory segments.
 303 (This information can be used with repeated
 304 .B SHM_STAT
 305 or
 306 .B SHM_STAT_ANY
 307 operations to obtain information about all shared memory segments
 308 on the system.)
 309 A successful
 310 .B SHM_STAT
 311 operation returns the identifier of the shared memory segment
 312 whose index was given in
 313 .IR shmid .
 314 Other operations return 0 on success.
 315 .PP
 316 On error, \-1 is returned, and
 317 .I errno
 318 is set appropriately.
 319 .SH ERRORS
 320 .TP
 321 .B EACCES
 322 \fBIPC_STAT\fP or \fBSHM_STAT\fP is requested and
 323 \fIshm_perm.mode\fP does not allow read access for
 324 .IR shmid ,
 325 and the calling process does not have the
 326 .B CAP_IPC_OWNER
 327 capability in the user namespace that governs its IPC namespace.
 328 .TP
 329 .B EFAULT
 330 The argument
 331 .I cmd
 332 has value
 333 .B IPC_SET
 334 or
 335 .B IPC_STAT
 336 but the address pointed to by
 337 .I buf
 338 isn't accessible.
 339 .TP
 340 .B EIDRM
 341 \fIshmid\fP points to a removed identifier.
 342 .TP
 343 .B EINVAL
 344 \fIshmid\fP is not a valid identifier, or \fIcmd\fP
 345 is not a valid command.
 346 Or: for a
 347 .B SHM_STAT
 348 or
 349 .B SHM_STAT_ANY
 350 operation, the index value specified in
 351 .I shmid
 352 referred to an array slot that is currently unused.
 353 .TP
 354 .B ENOMEM
 355 (In kernels since 2.6.9),
 356 .B SHM_LOCK
 357 was specified and the size of the to-be-locked segment would mean
 358 that the total bytes in locked shared memory segments would exceed
 359 the limit for the real user ID of the calling process.
 360 This limit is defined by the
 361 .B RLIMIT_MEMLOCK
 362 soft resource limit (see
 363 .BR setrlimit (2)).
 364 .TP
 365 .B EOVERFLOW
 366 \fBIPC_STAT\fP is attempted, and the GID or UID value
 367 is too large to be stored in the structure pointed to by
 368 .IR buf .
 369 .TP
 370 .B EPERM
 371 \fBIPC_SET\fP or \fBIPC_RMID\fP is attempted, and the
 372 effective user ID of the calling process is not that of the creator
 373 (found in
 374 .IR shm_perm.cuid ),
 375 or the owner
 376 (found in
 377 .IR shm_perm.uid ),
 378 and the process was not privileged (Linux: did not have the
 379 .B CAP_SYS_ADMIN
 380 capability).
 381 .IP
 382 Or (in kernels before 2.6.9),
 383 .B SHM_LOCK
 384 or
 385 .B SHM_UNLOCK
 386 was specified, but the process was not privileged
 387 (Linux: did not have the
 388 .B CAP_IPC_LOCK
 389 capability).
 390 (Since Linux 2.6.9, this error can also occur if the
 391 .B RLIMIT_MEMLOCK
 392 is 0 and the caller is not privileged.)
 393 .SH CONFORMING TO
 394 POSIX.1-2001, POSIX.1-2008, SVr4.
 395 .\" SVr4 documents additional error conditions EINVAL,
 396 .\" ENOENT, ENOSPC, ENOMEM, EEXIST.  Neither SVr4 nor SVID documents
 397 .\" an EIDRM error condition.
 398 .SH NOTES
 399 The inclusion of
 400 .I <sys/types.h>
 401 and
 402 .I <sys/ipc.h>
 403 isn't required on Linux or by any version of POSIX.
 404 However,
 405 some old implementations required the inclusion of these header files,
 406 and the SVID also documented their inclusion.
 407 Applications intended to be portable to such old systems may need
 408 to include these header files.
 409 .\" Like Linux, the FreeBSD man pages still document
 410 .\" the inclusion of these header files.
 411 .PP
 412 The
 413 .BR IPC_INFO ,
 414 .B SHM_STAT
 415 and
 416 .B SHM_INFO
 417 operations are used by the
 418 .BR ipcs (1)
 419 program to provide information on allocated resources.
 420 In the future, these may modified or moved to a
 421 .I /proc
 422 filesystem interface.
 423 .PP
 424 Linux permits a process to attach
 425 .RB ( shmat (2))
 426 a shared memory segment that has already been marked for deletion
 427 using
 428 .IR shmctl(IPC_RMID) .
 429 This feature is not available on other UNIX implementations;
 430 portable applications should avoid relying on it.
 431 .PP
 432 Various fields in a \fIstruct shmid_ds\fP were typed as
 433 .I short
 434 under Linux 2.2
 435 and have become
 436 .I long
 437 under Linux 2.4.
 438 To take advantage of this,
 439 a recompilation under glibc-2.1.91 or later should suffice.
 440 (The kernel distinguishes old and new calls by an
 441 .B IPC_64
 442 flag in
 443 .IR cmd .)
 444 .SH SEE ALSO
 445 .BR mlock (2),
 446 .BR setrlimit (2),
 447 .BR shmget (2),
 448 .BR shmop (2),
 449 .BR capabilities (7),
 450 .BR svipc (7)