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