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