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