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 2020-04-11 "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;   /* Creation time/time of last
  77                                     modification via shmctl() */
  78     pid_t           shm_cpid;    /* PID of creator */
  79     pid_t           shm_lpid;    /* PID of last shmat(2)/shmdt(2) */
  80     shmatt_t        shm_nattch;  /* No. of current attaches */
  81     ...
  82 };
  83 .EE
  84 .in
  85 .PP
  86 The fields of the
  87 .I shmid_ds
  88 structure are as follows:
  89 .TP 12
  90 .I shm_perm
  91 This is an
  92 .I ipc_perm
  93 structure (see below) that specifies the access permissions
  94 on the shared memory segment.
  95 .TP
  96 .I shm_segsz
  97 Size in bytes of the shared memory segment.
  98 .TP
  99 .I shm_cpid
 100 ID of the process that created the shared memory segment.
 101 .TP
 102 .I shm_lpid
 103 ID of the last process that executed a
 104 .BR shmat (2)
 105 or
 106 .BR shmdt (2)
 107 system call on this segment.
 108 .TP
 109 .I shm_nattch
 110 Number of processes that have this segment attached.
 111 .TP
 112 .I shm_atime
 113 Time of the last
 114 .BR shmat (2)
 115 system call that attached this segment.
 116 .TP
 117 .I shm_dtime
 118 Time of the last
 119 .BR shmdt (2)
 120 system call that detached tgis segment.
 121 .TP
 122 .I shm_ctime
 123 Time of creation of segment or time of the last
 124 .BR shmctl ()
 125 .BR IPC_SET
 126 operation.
 127 .PP
 128 The
 129 .I ipc_perm
 130 structure is defined as follows
 131 (the highlighted fields are settable using
 132 .BR IPC_SET ):
 133 .PP
 134 .in +4n
 135 .EX
 136 struct ipc_perm {
 137     key_t          __key;    /* Key supplied to shmget(2) */
 138     uid_t          \fBuid\fP;      /* Effective UID of owner */
 139     gid_t          \fBgid\fP;      /* Effective GID of owner */
 140     uid_t          cuid;     /* Effective UID of creator */
 141     gid_t          cgid;     /* Effective GID of creator */
 142     unsigned short \fBmode\fP;     /* \fBPermissions\fP + SHM_DEST and
 143                                 SHM_LOCKED flags */
 144     unsigned short __seq;    /* Sequence number */
 145 };
 146 .EE
 147 .in
 148 .PP
 149 The least significant 9 bits of the
 150 .I mode
 151 field of the
 152 .I ipc_perm
 153 structure define the access permissions for the shared memory segment.
 154 The permission bits are as follows:
 155 .TS
 156 l l.
 157 0400    Read by user
 158 0200    Write by user
 159 0040    Read by group
 160 0020    Write by group
 161 0004    Read by others
 162 0002    Write by others
 163 .TE
 164 .PP
 165 Bits 0100, 0010, and 0001 (the execute bits) are unused by the system.
 166 (It is not necessary to have execute permission on a segment
 167 in order to perform a
 168 .BR shmat (2)
 169 call with the
 170 .B SHM_EXEC
 171 flag.)
 172 .PP
 173 Valid values for
 174 .I cmd
 175 are:
 176 .TP
 177 .B IPC_STAT
 178 Copy information from the kernel data structure associated with
 179 .I shmid
 180 into the
 181 .I shmid_ds
 182 structure pointed to by \fIbuf\fP.
 183 The caller must have read permission on the
 184 shared memory segment.
 185 .TP
 186 .B IPC_SET
 187 Write the values of some members of the
 188 .I shmid_ds
 189 structure pointed to by
 190 .I buf
 191 to the kernel data structure associated with this shared memory segment,
 192 updating also its
 193 .I shm_ctime
 194 member.
 195 The following fields can be changed:
 196 \fIshm_perm.uid\fP, \fIshm_perm.gid\fP,
 197 and (the least significant 9 bits of) \fIshm_perm.mode\fP.
 198 The effective UID of the calling process must match the owner
 199 .RI ( shm_perm.uid )
 200 or creator
 201 .RI ( shm_perm.cuid )
 202 of the shared memory segment, or the caller must be privileged.
 203 .TP
 204 .B IPC_RMID
 205 Mark the segment to be destroyed.
 206 The segment will actually be destroyed
 207 only after the last process detaches it (i.e., when the
 208 .I shm_nattch
 209 member of the associated structure
 210 .I shmid_ds
 211 is zero).
 212 The caller must be the owner or creator of the segment, or be privileged.
 213 The
 214 .I buf
 215 argument is ignored.
 216 .IP
 217 If a segment has been marked for destruction, then the (nonstandard)
 218 .B SHM_DEST
 219 flag of the
 220 .I shm_perm.mode
 221 field in the associated data structure retrieved by
 222 .B IPC_STAT
 223 will be set.
 224 .IP
 225 The caller \fImust\fP ensure that a segment is eventually destroyed;
 226 otherwise its pages that were faulted in will remain in memory or swap.
 227 .IP
 228 See also the description of
 229 .I  /proc/sys/kernel/shm_rmid_forced
 230 in
 231 .BR proc (5).
 232 .TP
 233 .BR IPC_INFO " (Linux-specific)"
 234 Return information about system-wide shared memory limits and
 235 parameters in the structure pointed to by
 236 .IR buf .
 237 This structure is of type
 238 .I shminfo
 239 (thus, a cast is required),
 240 defined in
 241 .I <sys/shm.h>
 242 if the
 243 .B _GNU_SOURCE
 244 feature test macro is defined:
 245 .IP
 246 .in +4n
 247 .EX
 248 struct shminfo {
 249     unsigned long shmmax; /* Maximum segment size */
 250     unsigned long shmmin; /* Minimum segment size;
 251                              always 1 */
 252     unsigned long shmmni; /* Maximum number of segments */
 253     unsigned long shmseg; /* Maximum number of segments
 254                              that a process can attach;
 255                              unused within kernel */
 256     unsigned long shmall; /* Maximum number of pages of
 257                              shared memory, system-wide */
 258 };
 259 .EE
 260 .in
 261 .IP
 262 The
 263 .IR shmmni ,
 264 .IR shmmax ,
 265 and
 266 .I shmall
 267 settings can be changed via
 268 .I /proc
 269 files of the same name; see
 270 .BR proc (5)
 271 for details.
 272 .TP
 273 .BR SHM_INFO " (Linux-specific)"
 274 Return a
 275 .I shm_info
 276 structure whose fields contain information
 277 about system resources consumed by shared memory.
 278 This structure is defined in
 279 .I <sys/shm.h>
 280 if the
 281 .B _GNU_SOURCE
 282 feature test macro is defined:
 283 .IP
 284 .in +4n
 285 .EX
 286 struct shm_info {
 287     int           used_ids; /* # of currently existing
 288                                segments */
 289     unsigned long shm_tot;  /* Total number of shared
 290                                memory pages */
 291     unsigned long shm_rss;  /* # of resident shared
 292                                memory pages */
 293     unsigned long shm_swp;  /* # of swapped shared
 294                                memory pages */
 295     unsigned long swap_attempts;
 296                             /* Unused since Linux 2.4 */
 297     unsigned long swap_successes;
 298                             /* Unused since Linux 2.4 */
 299 };
 300 .EE
 301 .in
 302 .TP
 303 .BR SHM_STAT " (Linux-specific)"
 304 Return a
 305 .I shmid_ds
 306 structure as for
 307 .BR IPC_STAT .
 308 However, the
 309 .I shmid
 310 argument is not a segment identifier, but instead an index into
 311 the kernel's internal array that maintains information about
 312 all shared memory segments on the system.
 313 .TP
 314 .BR SHM_STAT_ANY " (Linux-specific, since Linux 4.17)"
 315 Return a
 316 .I shmid_ds
 317 structure as for
 318 .BR SHM_STAT .
 319 However,
 320 .I shm_perm.mode
 321 is not checked for read access for
 322 .IR shmid ,
 323 meaning that any user can employ this operation (just as any user may read
 324 .IR /proc/sysvipc/shm
 325 to obtain the same information).
 326 .PP
 327 The caller can prevent or allow swapping of a shared
 328 memory segment with the following \fIcmd\fP values:
 329 .TP
 330 .BR SHM_LOCK " (Linux-specific)"
 331 Prevent swapping of the shared memory segment.
 332 The caller must fault in
 333 any pages that are required to be present after locking is enabled.
 334 If a segment has been locked, then the (nonstandard)
 335 .B SHM_LOCKED
 336 flag of the
 337 .I shm_perm.mode
 338 field in the associated data structure retrieved by
 339 .B IPC_STAT
 340 will be set.
 341 .TP
 342 .BR SHM_UNLOCK " (Linux-specific)"
 343 Unlock the segment, allowing it to be swapped out.
 344 .PP
 345 In kernels before 2.6.10, only a privileged process
 346 could employ
 347 .B SHM_LOCK
 348 and
 349 .BR SHM_UNLOCK .
 350 Since kernel 2.6.10, an unprivileged process can employ these operations
 351 if its effective UID matches the owner or creator UID of the segment, and
 352 (for
 353 .BR SHM_LOCK )
 354 the amount of memory to be locked falls within the
 355 .B RLIMIT_MEMLOCK
 356 resource limit (see
 357 .BR setrlimit (2)).
 358 .\" There was some weirdness in 2.6.9: SHM_LOCK and SHM_UNLOCK could
 359 .\" be applied to a segment, regardless of ownership of the segment.
 360 .\" This was a botch-up in the move to RLIMIT_MEMLOCK, and was fixed
 361 .\" in 2.6.10.  MTK, May 2005
 362 .SH RETURN VALUE
 363 A successful
 364 .B IPC_INFO
 365 or
 366 .B SHM_INFO
 367 operation returns the index of the highest used entry in the
 368 kernel's internal array recording information about all
 369 shared memory segments.
 370 (This information can be used with repeated
 371 .B SHM_STAT
 372 or
 373 .B SHM_STAT_ANY
 374 operations to obtain information about all shared memory segments
 375 on the system.)
 376 A successful
 377 .B SHM_STAT
 378 operation returns the identifier of the shared memory segment
 379 whose index was given in
 380 .IR shmid .
 381 Other operations return 0 on success.
 382 .PP
 383 On error, \-1 is returned, and
 384 .I errno
 385 is set appropriately.
 386 .SH ERRORS
 387 .TP
 388 .B EACCES
 389 \fBIPC_STAT\fP or \fBSHM_STAT\fP is requested and
 390 \fIshm_perm.mode\fP does not allow read access for
 391 .IR shmid ,
 392 and the calling process does not have the
 393 .B CAP_IPC_OWNER
 394 capability in the user namespace that governs its IPC namespace.
 395 .TP
 396 .B EFAULT
 397 The argument
 398 .I cmd
 399 has value
 400 .B IPC_SET
 401 or
 402 .B IPC_STAT
 403 but the address pointed to by
 404 .I buf
 405 isn't accessible.
 406 .TP
 407 .B EIDRM
 408 \fIshmid\fP points to a removed identifier.
 409 .TP
 410 .B EINVAL
 411 \fIshmid\fP is not a valid identifier, or \fIcmd\fP
 412 is not a valid command.
 413 Or: for a
 414 .B SHM_STAT
 415 or
 416 .B SHM_STAT_ANY
 417 operation, the index value specified in
 418 .I shmid
 419 referred to an array slot that is currently unused.
 420 .TP
 421 .B ENOMEM
 422 (In kernels since 2.6.9),
 423 .B SHM_LOCK
 424 was specified and the size of the to-be-locked segment would mean
 425 that the total bytes in locked shared memory segments would exceed
 426 the limit for the real user ID of the calling process.
 427 This limit is defined by the
 428 .B RLIMIT_MEMLOCK
 429 soft resource limit (see
 430 .BR setrlimit (2)).
 431 .TP
 432 .B EOVERFLOW
 433 \fBIPC_STAT\fP is attempted, and the GID or UID value
 434 is too large to be stored in the structure pointed to by
 435 .IR buf .
 436 .TP
 437 .B EPERM
 438 \fBIPC_SET\fP or \fBIPC_RMID\fP is attempted, and the
 439 effective user ID of the calling process is not that of the creator
 440 (found in
 441 .IR shm_perm.cuid ),
 442 or the owner
 443 (found in
 444 .IR shm_perm.uid ),
 445 and the process was not privileged (Linux: did not have the
 446 .B CAP_SYS_ADMIN
 447 capability).
 448 .IP
 449 Or (in kernels before 2.6.9),
 450 .B SHM_LOCK
 451 or
 452 .B SHM_UNLOCK
 453 was specified, but the process was not privileged
 454 (Linux: did not have the
 455 .B CAP_IPC_LOCK
 456 capability).
 457 (Since Linux 2.6.9, this error can also occur if the
 458 .B RLIMIT_MEMLOCK
 459 is 0 and the caller is not privileged.)
 460 .SH CONFORMING TO
 461 POSIX.1-2001, POSIX.1-2008, SVr4.
 462 .\" SVr4 documents additional error conditions EINVAL,
 463 .\" ENOENT, ENOSPC, ENOMEM, EEXIST.  Neither SVr4 nor SVID documents
 464 .\" an EIDRM error condition.
 465 .SH NOTES
 466 The inclusion of
 467 .I <sys/types.h>
 468 and
 469 .I <sys/ipc.h>
 470 isn't required on Linux or by any version of POSIX.
 471 However,
 472 some old implementations required the inclusion of these header files,
 473 and the SVID also documented their inclusion.
 474 Applications intended to be portable to such old systems may need
 475 to include these header files.
 476 .\" Like Linux, the FreeBSD man pages still document
 477 .\" the inclusion of these header files.
 478 .PP
 479 The
 480 .BR IPC_INFO ,
 481 .B SHM_STAT
 482 and
 483 .B SHM_INFO
 484 operations are used by the
 485 .BR ipcs (1)
 486 program to provide information on allocated resources.
 487 In the future, these may modified or moved to a
 488 .I /proc
 489 filesystem interface.
 490 .PP
 491 Linux permits a process to attach
 492 .RB ( shmat (2))
 493 a shared memory segment that has already been marked for deletion
 494 using
 495 .IR shmctl(IPC_RMID) .
 496 This feature is not available on other UNIX implementations;
 497 portable applications should avoid relying on it.
 498 .PP
 499 Various fields in a \fIstruct shmid_ds\fP were typed as
 500 .I short
 501 under Linux 2.2
 502 and have become
 503 .I long
 504 under Linux 2.4.
 505 To take advantage of this,
 506 a recompilation under glibc-2.1.91 or later should suffice.
 507 (The kernel distinguishes old and new calls by an
 508 .B IPC_64
 509 flag in
 510 .IR cmd .)
 511 .SH SEE ALSO
 512 .BR mlock (2),
 513 .BR setrlimit (2),
 514 .BR shmget (2),
 515 .BR shmop (2),
 516 .BR capabilities (7),
 517 .BR sysvipc (7)