1 .\" Copyright (c) 1993 Luigi P. Bai (lpb@softint.com) July 28, 1993
3 .\" Permission is granted to make and distribute verbatim copies of this
4 .\" manual provided the copyright notice and this permission notice are
5 .\" preserved on all copies.
7 .\" Permission is granted to copy and distribute modified versions of this
8 .\" manual under the conditions for verbatim copying, provided that the
9 .\" entire resulting derived work is distributed under the terms of a
10 .\" permission notice identical to this one
12 .\" Since the Linux kernel and libraries are constantly changing, this
13 .\" manual page may be incorrect or out-of-date. The author(s) assume no
14 .\" responsibility for errors or omissions, or for damages resulting from
15 .\" the use of the information contained herein. The author(s) may not
16 .\" have taken the same level of care in the production of this manual,
17 .\" which is licensed free of charge, as they might when working
20 .\" Formatted or processed versions of this manual, if unaccompanied by
21 .\" the source, must acknowledge the copyright and authors of this work.
23 .\" Modified Wed Jul 28 11:03:24 1993, Rik Faith <faith@cs.unc.edu>
24 .\" Modified Sun Nov 28 16:43:30 1993, Rik Faith <faith@cs.unc.edu>
25 .\" with material from Giorgio Ciucci <giorgio@crcc.it>
26 .\" Portions Copyright 1993 Giorgio Ciucci <giorgio@crcc.it>
27 .\" Modified Fri Jan 31 17:24:31 1997 by Eric S. Raymond <esr@thyrsus.com>
28 .\" Modified Sun Feb 18 01:59:29 2001 by Andries Brouwer <aeb@cwi.nl>
29 .\" Modified 5 Jan 2002 Michael Kerrisk <mtk16@ext.canterbury.ac.nz>
31 .TH SHMCTL 2 2002-01-05 "Linux 2.4.1" "Linux Programmer's Manual"
33 shmctl \- shared memory control
36 .B #include <sys/ipc.h>
38 .B #include <sys/shm.h>
40 .BI "int shmctl(int " shmid ", int " cmd ", struct shmid_ds *" buf );
44 allows the user to receive information on a shared memory segment,
45 set the owner, group, and permissions of a shared memory segment,
46 or destroy a segment. The information about the segment identified by
47 \fIshmid\fP is returned in a \fIshmid_ds\fP
53 struct ipc_perm shm_perm; /* operation perms */
54 int 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; /* last change time */
58 unsigned short shm_cpid; /* pid of creator */
59 unsigned short shm_lpid; /* pid of last operator */
60 short shm_nattch; /* no. of current attaches */
66 The highlighted fields in the member \fIshm_perm\fP can be set:
72 \fBushort uid\fP; /* \fBowner\fP euid and egid */
74 ushort cuid; /* creator euid and egid */
76 \fBushort mode\fP; /* lower 9 bits of access modes */
77 ushort seq; /* sequence number */
82 The following \fIcmds\fP are available:
86 is used to copy the information about the shared memory segment into
87 the buffer \fIbuf\fP. The user must have \fBread\fP access to the
88 shared memory segment.
91 is used to apply the changes the user has made to the \fIuid\fP, \fIgid\fP,
92 or \fImode\fP members of the \fIshm_perms\fP field. Only the lowest 9 bits
93 of \fImode\fP are used. The
95 member is also updated. The user must be the owner, creator, or the
99 is used to mark the segment as destroyed. It will actually be destroyed
100 after the last detach. (I.e., when the
102 member of the associated structure
104 is zero.) The user must be the owner, creator, or the super-user.
106 The user \fImust\fP ensure that a segment is eventually destroyed; otherwise
107 its pages that were faulted in will remain in memory or swap.
109 In addition, the \fBsuper-user\fP can prevent or allow swapping of a shared
110 memory segment with the following \fIcmds\fP: (Linux only)
114 prevents swapping of a shared memory segment. The user must fault in
115 any pages that are required to be present after locking is enabled.
118 allows the shared memory segment to be swapped out.
125 control calls are used by the
127 program to provide information on allocated resources. In the future,
128 these may be modified as needed or moved to a proc file system interface.
130 0 is returned on success, \-1 on error.
134 will be set to one of the following:
137 is returned if \fBIPC_STAT\fP is requested and
138 \fIshm_perm.modes\fP does not allow read access for
148 but the address pointed to by
153 is returned if \fIshmid\fP is not a valid identifier, or \fIcmd\fP
154 is not a valid command.
157 is returned if \fIshmid\fP points to a removed identifier.
160 is returned if \fBIPC_SET\fP or \fBIPC_RMID\fP is attempted, and the
161 effective user ID of the calling process is not the creator
170 is returned if \fBIPC_STAT\fP is attempted, and the gid or uid value
171 is too large to be stored in the structure pointed to by
174 Various fields in a \fIstruct shmid_ds\fP were shorts under Linux 2.2
175 and have become longs under Linux 2.4. To take advantage of this,
176 a recompilation under glibc-2.1.91 or later should suffice.
177 (The kernel distinguishes old and new calls by a IPC_64 flag in
180 SVr4, SVID. SVr4 documents additional error conditions EINVAL,
181 ENOENT, ENOSPC, ENOMEM, EEXIST. Neither SVr4 nor SVID documents
182 an EIDRM error condition.