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