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/shm.h>
  53 .PP
  54 .BI "int shmctl(int " shmid ", int " cmd ", struct shmid_ds *" buf );
  55 .ad b
  56 .fi
  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_atime
 100 Time of the last
 101 .BR shmat (2)
 102 system call that attached this segment.
 103 .TP
 104 .I shm_dtime
 105 Time of the last
 106 .BR shmdt (2)
 107 system call that detached tgis segment.
 108 .TP
 109 .I shm_ctime
 110 Time of creation of segment or time of the last
 111 .BR shmctl ()
 112 .BR IPC_SET
 113 operation.
 114 .TP
 115 .I shm_cpid
 116 ID of the process that created the shared memory segment.
 117 .TP
 118 .I shm_lpid
 119 ID of the last process that executed a
 120 .BR shmat (2)
 121 or
 122 .BR shmdt (2)
 123 system call on this segment.
 124 .TP
 125 .I shm_nattch
 126 Number of processes that have this segment attached.
 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 .IP
 196 The following fields are updated:
 197 \fIshm_perm.uid\fP, \fIshm_perm.gid\fP,
 198 and (the least significant 9 bits of) \fIshm_perm.mode\fP.
 199 .IP
 200 The effective UID of the calling process must match the owner
 201 .RI ( shm_perm.uid )
 202 or creator
 203 .RI ( shm_perm.cuid )
 204 of the shared memory segment, or the caller must be privileged.
 205 .TP
 206 .B IPC_RMID
 207 Mark the segment to be destroyed.
 208 The segment will actually be destroyed
 209 only after the last process detaches it (i.e., when the
 210 .I shm_nattch
 211 member of the associated structure
 212 .I shmid_ds
 213 is zero).
 214 The caller must be the owner or creator of the segment, or be privileged.
 215 The
 216 .I buf
 217 argument is ignored.
 218 .IP
 219 If a segment has been marked for destruction, then the (nonstandard)
 220 .B SHM_DEST
 221 flag of the
 222 .I shm_perm.mode
 223 field in the associated data structure retrieved by
 224 .B IPC_STAT
 225 will be set.
 226 .IP
 227 The caller \fImust\fP ensure that a segment is eventually destroyed;
 228 otherwise its pages that were faulted in will remain in memory or swap.
 229 .IP
 230 See also the description of
 231 .I  /proc/sys/kernel/shm_rmid_forced
 232 in
 233 .BR proc (5).
 234 .TP
 235 .BR IPC_INFO " (Linux-specific)"
 236 Return information about system-wide shared memory limits and
 237 parameters in the structure pointed to by
 238 .IR buf .
 239 This structure is of type
 240 .I shminfo
 241 (thus, a cast is required),
 242 defined in
 243 .I <sys/shm.h>
 244 if the
 245 .B _GNU_SOURCE
 246 feature test macro is defined:
 247 .IP
 248 .in +4n
 249 .EX
 250 struct shminfo {
 251     unsigned long shmmax; /* Maximum segment size */
 252     unsigned long shmmin; /* Minimum segment size;
 253                              always 1 */
 254     unsigned long shmmni; /* Maximum number of segments */
 255     unsigned long shmseg; /* Maximum number of segments
 256                              that a process can attach;
 257                              unused within kernel */
 258     unsigned long shmall; /* Maximum number of pages of
 259                              shared memory, system\-wide */
 260 };
 261 .EE
 262 .in
 263 .IP
 264 The
 265 .IR shmmni ,
 266 .IR shmmax ,
 267 and
 268 .I shmall
 269 settings can be changed via
 270 .I /proc
 271 files of the same name; see
 272 .BR proc (5)
 273 for details.
 274 .TP
 275 .BR SHM_INFO " (Linux-specific)"
 276 Return a
 277 .I shm_info
 278 structure whose fields contain information
 279 about system resources consumed by shared memory.
 280 This structure is defined in
 281 .I <sys/shm.h>
 282 if the
 283 .B _GNU_SOURCE
 284 feature test macro is defined:
 285 .IP
 286 .in +4n
 287 .EX
 288 struct shm_info {
 289     int           used_ids; /* # of currently existing
 290                                segments */
 291     unsigned long shm_tot;  /* Total number of shared
 292                                memory pages */
 293     unsigned long shm_rss;  /* # of resident shared
 294                                memory pages */
 295     unsigned long shm_swp;  /* # of swapped shared
 296                                memory pages */
 297     unsigned long swap_attempts;
 298                             /* Unused since Linux 2.4 */
 299     unsigned long swap_successes;
 300                             /* Unused since Linux 2.4 */
 301 };
 302 .EE
 303 .in
 304 .TP
 305 .BR SHM_STAT " (Linux-specific)"
 306 Return a
 307 .I shmid_ds
 308 structure as for
 309 .BR IPC_STAT .
 310 However, the
 311 .I shmid
 312 argument is not a segment identifier, but instead an index into
 313 the kernel's internal array that maintains information about
 314 all shared memory segments on the system.
 315 .TP
 316 .BR SHM_STAT_ANY " (Linux-specific, since Linux 4.17)"
 317 Return a
 318 .I shmid_ds
 319 structure as for
 320 .BR SHM_STAT .
 321 However,
 322 .I shm_perm.mode
 323 is not checked for read access for
 324 .IR shmid ,
 325 meaning that any user can employ this operation (just as any user may read
 326 .IR /proc/sysvipc/shm
 327 to obtain the same information).
 328 .PP
 329 The caller can prevent or allow swapping of a shared
 330 memory segment with the following \fIcmd\fP values:
 331 .TP
 332 .BR SHM_LOCK " (Linux-specific)"
 333 Prevent swapping of the shared memory segment.
 334 The caller must fault in
 335 any pages that are required to be present after locking is enabled.
 336 If a segment has been locked, then the (nonstandard)
 337 .B SHM_LOCKED
 338 flag of the
 339 .I shm_perm.mode
 340 field in the associated data structure retrieved by
 341 .B IPC_STAT
 342 will be set.
 343 .TP
 344 .BR SHM_UNLOCK " (Linux-specific)"
 345 Unlock the segment, allowing it to be swapped out.
 346 .PP
 347 In kernels before 2.6.10, only a privileged process
 348 could employ
 349 .B SHM_LOCK
 350 and
 351 .BR SHM_UNLOCK .
 352 Since kernel 2.6.10, an unprivileged process can employ these operations
 353 if its effective UID matches the owner or creator UID of the segment, and
 354 (for
 355 .BR SHM_LOCK )
 356 the amount of memory to be locked falls within the
 357 .B RLIMIT_MEMLOCK
 358 resource limit (see
 359 .BR setrlimit (2)).
 360 .\" There was some weirdness in 2.6.9: SHM_LOCK and SHM_UNLOCK could
 361 .\" be applied to a segment, regardless of ownership of the segment.
 362 .\" This was a botch-up in the move to RLIMIT_MEMLOCK, and was fixed
 363 .\" in 2.6.10.  MTK, May 2005
 364 .SH RETURN VALUE
 365 A successful
 366 .B IPC_INFO
 367 or
 368 .B SHM_INFO
 369 operation returns the index of the highest used entry in the
 370 kernel's internal array recording information about all
 371 shared memory segments.
 372 (This information can be used with repeated
 373 .B SHM_STAT
 374 or
 375 .B SHM_STAT_ANY
 376 operations to obtain information about all shared memory segments
 377 on the system.)
 378 A successful
 379 .B SHM_STAT
 380 operation returns the identifier of the shared memory segment
 381 whose index was given in
 382 .IR shmid .
 383 Other operations return 0 on success.
 384 .PP
 385 On error, \-1 is returned, and
 386 .I errno
 387 is set to indicate the error.
 388 .SH ERRORS
 389 .TP
 390 .B EACCES
 391 \fBIPC_STAT\fP or \fBSHM_STAT\fP is requested and
 392 \fIshm_perm.mode\fP does not allow read access for
 393 .IR shmid ,
 394 and the calling process does not have the
 395 .B CAP_IPC_OWNER
 396 capability in the user namespace that governs its IPC namespace.
 397 .TP
 398 .B EFAULT
 399 The argument
 400 .I cmd
 401 has value
 402 .B IPC_SET
 403 or
 404 .B IPC_STAT
 405 but the address pointed to by
 406 .I buf
 407 isn't accessible.
 408 .TP
 409 .B EIDRM
 410 \fIshmid\fP points to a removed identifier.
 411 .TP
 412 .B EINVAL
 413 \fIshmid\fP is not a valid identifier, or \fIcmd\fP
 414 is not a valid command.
 415 Or: for a
 416 .B SHM_STAT
 417 or
 418 .B SHM_STAT_ANY
 419 operation, the index value specified in
 420 .I shmid
 421 referred to an array slot that is currently unused.
 422 .TP
 423 .B ENOMEM
 424 (In kernels since 2.6.9),
 425 .B SHM_LOCK
 426 was specified and the size of the to-be-locked segment would mean
 427 that the total bytes in locked shared memory segments would exceed
 428 the limit for the real user ID of the calling process.
 429 This limit is defined by the
 430 .B RLIMIT_MEMLOCK
 431 soft resource limit (see
 432 .BR setrlimit (2)).
 433 .TP
 434 .B EOVERFLOW
 435 \fBIPC_STAT\fP is attempted, and the GID or UID value
 436 is too large to be stored in the structure pointed to by
 437 .IR buf .
 438 .TP
 439 .B EPERM
 440 \fBIPC_SET\fP or \fBIPC_RMID\fP is attempted, and the
 441 effective user ID of the calling process is not that of the creator
 442 (found in
 443 .IR shm_perm.cuid ),
 444 or the owner
 445 (found in
 446 .IR shm_perm.uid ),
 447 and the process was not privileged (Linux: did not have the
 448 .B CAP_SYS_ADMIN
 449 capability).
 450 .IP
 451 Or (in kernels before 2.6.9),
 452 .B SHM_LOCK
 453 or
 454 .B SHM_UNLOCK
 455 was specified, but the process was not privileged
 456 (Linux: did not have the
 457 .B CAP_IPC_LOCK
 458 capability).
 459 (Since Linux 2.6.9, this error can also occur if the
 460 .B RLIMIT_MEMLOCK
 461 is 0 and the caller is not privileged.)
 462 .SH CONFORMING TO
 463 POSIX.1-2001, POSIX.1-2008, SVr4.
 464 .\" SVr4 documents additional error conditions EINVAL,
 465 .\" ENOENT, ENOSPC, ENOMEM, EEXIST.  Neither SVr4 nor SVID documents
 466 .\" an EIDRM error condition.
 467 .SH NOTES
 468 The
 469 .BR IPC_INFO ,
 470 .BR SHM_STAT ,
 471 and
 472 .B SHM_INFO
 473 operations are used by the
 474 .BR ipcs (1)
 475 program to provide information on allocated resources.
 476 In the future, these may modified or moved to a
 477 .I /proc
 478 filesystem interface.
 479 .PP
 480 Linux permits a process to attach
 481 .RB ( shmat (2))
 482 a shared memory segment that has already been marked for deletion
 483 using
 484 .IR shmctl(IPC_RMID) .
 485 This feature is not available on other UNIX implementations;
 486 portable applications should avoid relying on it.
 487 .PP
 488 Various fields in a \fIstruct shmid_ds\fP were typed as
 489 .I short
 490 under Linux 2.2
 491 and have become
 492 .I long
 493 under Linux 2.4.
 494 To take advantage of this,
 495 a recompilation under glibc-2.1.91 or later should suffice.
 496 (The kernel distinguishes old and new calls by an
 497 .B IPC_64
 498 flag in
 499 .IR cmd .)
 500 .SH SEE ALSO
 501 .BR mlock (2),
 502 .BR setrlimit (2),
 503 .BR shmget (2),
 504 .BR shmop (2),
 505 .BR capabilities (7),
 506 .BR sysvipc (7)