original/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 .\"
  45 .TH SHMCTL 2 2013-03-18 "Linux" "Linux Programmer's Manual"
  46 .SH NAME
  47 shmctl \- System V shared memory control
  48 .SH SYNOPSIS
  49 .ad l
  50 .B #include <sys/ipc.h>
  51 .br
  52 .B #include <sys/shm.h>
  53 .sp
  54 .BI "int shmctl(int " shmid ", int " cmd ", struct shmid_ds *" buf );
  55 .ad b
  56 .SH DESCRIPTION
  57 .BR shmctl ()
  58 performs the control operation specified by
  59 .I cmd
  60 on the System V shared memory segment whose identifier is given in
  61 .IR shmid .
  62 .PP
  63 The
  64 .I buf
  65 argument is a pointer to a \fIshmid_ds\fP structure,
  66 defined in \fI<sys/shm.h>\fP as follows:
  67 .PP
  68 .in +4n
  69 .nf
  70 struct shmid_ds {
  71     struct ipc_perm shm_perm;    /* Ownership and permissions */
  72     size_t          shm_segsz;   /* Size of segment (bytes) */
  73     time_t          shm_atime;   /* Last attach time */
  74     time_t          shm_dtime;   /* Last detach time */
  75     time_t          shm_ctime;   /* Last change time */
  76     pid_t           shm_cpid;    /* PID of creator */
  77     pid_t           shm_lpid;    /* PID of last shmat(2)/shmdt(2) */
  78     shmatt_t        shm_nattch;  /* No. of current attaches */
  79     ...
  80 };
  81 .fi
  82 .in
  83 .PP
  84 The
  85 .I ipc_perm
  86 structure is defined as follows
  87 (the highlighted fields are settable using
  88 .BR IPC_SET ):
  89 .PP
  90 .in +4n
  91 .nf
  92 struct ipc_perm {
  93     key_t          __key;    /* Key supplied to shmget(2) */
  94     uid_t          \fBuid\fP;      /* Effective UID of owner */
  95     gid_t          \fBgid\fP;      /* Effective GID of owner */
  96     uid_t          cuid;     /* Effective UID of creator */
  97     gid_t          cgid;     /* Effective GID of creator */
  98     unsigned short \fBmode\fP;     /* \fBPermissions\fP + SHM_DEST and
  99                                 SHM_LOCKED flags */
 100     unsigned short __seq;    /* Sequence number */
 101 };
 102 .fi
 103 .in
 104 .PP
 105 Valid values for
 106 .I cmd
 107 are:
 108 .br
 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 only actually be destroyed
 140 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, or be privileged.
 146 If a segment has been marked for destruction, then the (nonstandard)
 147 .B SHM_DEST
 148 flag of the
 149 .I shm_perm.mode
 150 field in the associated data structure retrieved by
 151 .B IPC_STAT
 152 will be set.
 153 .IP
 154 The caller \fImust\fP ensure that a segment is eventually destroyed;
 155 otherwise its pages that were faulted in will remain in memory or swap.
 156 .IP
 157 See also the description of
 158 .I  /proc/sys/kernel/shm_rmid_forced
 159 in
 160 .BR proc (5).
 161 .TP 10
 162 .BR IPC_INFO " (Linux-specific)"
 163 Returns information about system-wide shared memory limits and
 164 parameters in the structure pointed to by
 165 .IR buf .
 166 This structure is of type
 167 .I shminfo
 168 (thus, a cast is required),
 169 defined in
 170 .I <sys/shm.h>
 171 if the
 172 .B _GNU_SOURCE
 173 feature test macro is defined:
 174 .nf
 175 .in +4n
 176
 177 struct  shminfo {
 178     unsigned long shmmax; /* Maximum segment size */
 179     unsigned long shmmin; /* Minimum segment size;
 180                              always 1 */
 181     unsigned long shmmni; /* Maximum number of segments */
 182     unsigned long shmseg; /* Maximum number of segments
 183                              that a process can attach;
 184                              unused within kernel */
 185     unsigned long shmall; /* Maximum number of pages of
 186                              shared memory, system-wide */
 187 };
 188
 189 .in
 190 .fi
 191 The
 192 .IR shmmni ,
 193 .IR shmmax ,
 194 and
 195 .I shmall
 196 settings can be changed via
 197 .I /proc
 198 files of the same name; see
 199 .BR proc (5)
 200 for details.
 201 .TP
 202 .BR SHM_INFO " (Linux-specific)"
 203 Returns a
 204 .I shm_info
 205 structure whose fields contain information
 206 about system resources consumed by shared memory.
 207 This structure is defined in
 208 .I <sys/shm.h>
 209 if the
 210 .B _GNU_SOURCE
 211 feature test macro is defined:
 212 .nf
 213 .in +4n
 214
 215 struct shm_info {
 216     int           used_ids; /* # of currently existing
 217                                segments */
 218     unsigned long shm_tot;  /* Total number of shared
 219                                memory pages */
 220     unsigned long shm_rss;  /* # of resident shared
 221                                memory pages */
 222     unsigned long shm_swp;  /* # of swapped shared
 223                                memory pages */
 224     unsigned long swap_attempts;
 225                             /* Unused since Linux 2.4 */
 226     unsigned long swap_successes;
 227                             /* Unused since Linux 2.4 */
 228 };
 229 .in
 230 .fi
 231 .TP
 232 .BR SHM_STAT " (Linux-specific)"
 233 Returns a
 234 .I shmid_ds
 235 structure as for
 236 .BR IPC_STAT .
 237 However, the
 238 .I shmid
 239 argument is not a segment identifier, but instead an index into
 240 the kernel's internal array that maintains information about
 241 all shared memory segments on the system.
 242 .PP
 243 The caller can prevent or allow swapping of a shared
 244 memory segment with the following \fIcmd\fP values:
 245 .br
 246 .TP 10
 247 .BR SHM_LOCK " (Linux-specific)"
 248 Prevent swapping of the shared memory segment.
 249 The caller must fault in
 250 any pages that are required to be present after locking is enabled.
 251 If a segment has been locked, then the (nonstandard)
 252 .B SHM_LOCKED
 253 flag of the
 254 .I shm_perm.mode
 255 field in the associated data structure retrieved by
 256 .B IPC_STAT
 257 will be set.
 258 .TP
 259 .BR SHM_UNLOCK " (Linux-specific)"
 260 Unlock the segment, allowing it to be swapped out.
 261 .PP
 262 In kernels before 2.6.10, only a privileged process
 263 could employ
 264 .B SHM_LOCK
 265 and
 266 .BR SHM_UNLOCK .
 267 Since kernel 2.6.10, an unprivileged process can employ these operations
 268 if its effective UID matches the owner or creator UID of the segment, and
 269 (for
 270 .BR SHM_LOCK )
 271 the amount of memory to be locked falls within the
 272 .B RLIMIT_MEMLOCK
 273 resource limit (see
 274 .BR setrlimit (2)).
 275 .\" There was some weirdness in 2.6.9: SHM_LOCK and SHM_UNLOCK could
 276 .\" be applied to a segment, regardless of ownership of the segment.
 277 .\" This was a botch-up in the move to RLIMIT_MEMLOCK, and was fixed
 278 .\" in 2.6.10.  MTK, May 2005
 279 .SH RETURN VALUE
 280 A successful
 281 .B IPC_INFO
 282 or
 283 .B SHM_INFO
 284 operation returns the index of the highest used entry in the
 285 kernel's internal array recording information about all
 286 shared memory segments.
 287 (This information can be used with repeated
 288 .B SHM_STAT
 289 operations to obtain information about all shared memory segments
 290 on the system.)
 291 A successful
 292 .B SHM_STAT
 293 operation returns the identifier of the shared memory segment
 294 whose index was given in
 295 .IR shmid .
 296 Other operations return 0 on success.
 297
 298 On error, \-1 is returned, and
 299 .I errno
 300 is set appropriately.
 301 .SH ERRORS
 302 .TP
 303 .B EACCES
 304 \fBIPC_STAT\fP or \fBSHM_STAT\fP is requested and
 305 \fIshm_perm.mode\fP does not allow read access for
 306 .IR shmid ,
 307 and the calling process does not have the
 308 .B CAP_IPC_OWNER
 309 capability.
 310 .TP
 311 .B EFAULT
 312 The argument
 313 .I cmd
 314 has value
 315 .B IPC_SET
 316 or
 317 .B IPC_STAT
 318 but the address pointed to by
 319 .I buf
 320 isn't accessible.
 321 .TP
 322 .B EIDRM
 323 \fIshmid\fP points to a removed identifier.
 324 .TP
 325 .B EINVAL
 326 \fIshmid\fP is not a valid identifier, or \fIcmd\fP
 327 is not a valid command.
 328 Or: for a
 329 .B SHM_STAT
 330 operation, the index value specified in
 331 .I shmid
 332 referred to an array slot that is currently unused.
 333 .TP
 334 .B ENOMEM
 335 (In kernels since 2.6.9),
 336 .B SHM_LOCK
 337 was specified and the size of the to-be-locked segment would mean
 338 that the total bytes in locked shared memory segments would exceed
 339 the limit for the real user ID of the calling process.
 340 This limit is defined by the
 341 .B RLIMIT_MEMLOCK
 342 soft resource limit (see
 343 .BR setrlimit (2)).
 344 .TP
 345 .B EOVERFLOW
 346 \fBIPC_STAT\fP is attempted, and the GID or UID value
 347 is too large to be stored in the structure pointed to by
 348 .IR buf .
 349 .TP
 350 .B EPERM
 351 \fBIPC_SET\fP or \fBIPC_RMID\fP is attempted, and the
 352 effective user ID of the calling process is not that of the creator
 353 (found in
 354 .IR shm_perm.cuid ),
 355 or the owner
 356 (found in
 357 .IR shm_perm.uid ),
 358 and the process was not privileged (Linux: did not have the
 359 .B CAP_SYS_ADMIN
 360 capability).
 361
 362 Or (in kernels before 2.6.9),
 363 .B SHM_LOCK
 364 or
 365 .B SHM_UNLOCK
 366 was specified, but the process was not privileged
 367 (Linux: did not have the
 368 .B CAP_IPC_LOCK
 369 capability).
 370 (Since Linux 2.6.9, this error can also occur if the
 371 .B RLIMIT_MEMLOCK
 372 is 0 and the caller is not privileged.)
 373 .SH CONFORMING TO
 374 SVr4, POSIX.1-2001.
 375 .\" SVr4 documents additional error conditions EINVAL,
 376 .\" ENOENT, ENOSPC, ENOMEM, EEXIST.  Neither SVr4 nor SVID documents
 377 .\" an EIDRM error condition.
 378 .SH NOTES
 379 The inclusion of
 380 .I <sys/types.h>
 381 and
 382 .I <sys/ipc.h>
 383 isn't required on Linux or by any version of POSIX.
 384 However,
 385 some old implementations required the inclusion of these header files,
 386 and the SVID also documented their inclusion.
 387 Applications intended to be portable to such old systems may need
 388 to include these header files.
 389 .\" Like Linux, the FreeBSD man pages still document
 390 .\" the inclusion of these header files.
 391
 392 The
 393 .BR IPC_INFO ,
 394 .B SHM_STAT
 395 and
 396 .B SHM_INFO
 397 operations are used by the
 398 .BR ipcs (1)
 399 program to provide information on allocated resources.
 400 In the future these may modified or moved to a
 401 .I /proc
 402 filesystem interface.
 403
 404 Linux permits a process to attach
 405 .RB ( shmat (2))
 406 a shared memory segment that has already been marked for deletion
 407 using
 408 .IR shmctl(IPC_RMID) .
 409 This feature is not available on other UNIX implementations;
 410 portable applications should avoid relying on it.
 411
 412 Various fields in a \fIstruct shmid_ds\fP were typed as
 413 .I short
 414 under Linux 2.2
 415 and have become
 416 .I long
 417 under Linux 2.4.
 418 To take advantage of this,
 419 a recompilation under glibc-2.1.91 or later should suffice.
 420 (The kernel distinguishes old and new calls by an
 421 .B IPC_64
 422 flag in
 423 .IR cmd .)
 424 .SH SEE ALSO
 425 .BR mlock (2),
 426 .BR setrlimit (2),
 427 .BR shmget (2),
 428 .BR shmop (2),
 429 .BR capabilities (7),
 430 .BR svipc (7)