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