]>
Commit | Line | Data |
---|---|---|
bc191751 | 1 | .\" Copyright (c) 1993 Luigi P. Bai (lpb@softint.com) July 28, 1993 |
2 | .\" | |
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. | |
6 | .\" | |
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 | |
11 | .\" | |
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 | |
18 | .\" professionally. | |
19 | .\" | |
20 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
21 | .\" the source, must acknowledge the copyright and authors of this work. | |
22 | .\" | |
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> | |
30 | .\" | |
31 | .TH SHMCTL 2 2002-01-05 "Linux 2.4.1" "Linux Programmer's Manual" | |
32 | .SH NAME | |
33 | shmctl \- shared memory control | |
34 | .SH SYNOPSIS | |
35 | .ad l | |
36 | .B #include <sys/ipc.h> | |
37 | .sp | |
38 | .B #include <sys/shm.h> | |
39 | .sp | |
40 | .BI "int shmctl(int " shmid ", int " cmd ", struct shmid_ds *" buf ); | |
41 | .ad b | |
42 | .SH DESCRIPTION | |
43 | \fBshmctl()\fP | |
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 | |
48 | structure: | |
49 | .PP | |
50 | .in +4n | |
51 | .nf | |
52 | struct shmid_ds { | |
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 */ | |
61 | ... | |
62 | }; | |
63 | .fi | |
64 | .in -4n | |
65 | .PP | |
66 | The highlighted fields in the member \fIshm_perm\fP can be set: | |
67 | .PP | |
68 | .in +4n | |
69 | .nf | |
70 | struct ipc_perm { | |
71 | key_t key; | |
72 | \fBushort uid\fP; /* \fBowner\fP euid and egid */ | |
73 | \fBushort gid\fP; | |
74 | ushort cuid; /* creator euid and egid */ | |
75 | ushort cgid; | |
76 | \fBushort mode\fP; /* lower 9 bits of access modes */ | |
77 | ushort seq; /* sequence number */ | |
78 | }; | |
79 | .fi | |
80 | .in -4n | |
81 | .PP | |
82 | The following \fIcmds\fP are available: | |
83 | .br | |
84 | .TP 12 | |
85 | .B IPC_STAT | |
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. | |
89 | .TP | |
90 | .B IPC_SET | |
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 | |
94 | .I shm_ctime | |
95 | member is also updated. The user must be the owner, creator, or the | |
96 | super-user. | |
97 | .TP | |
98 | .B IPC_RMID | |
99 | is used to mark the segment as destroyed. It will actually be destroyed | |
100 | after the last detach. (I.e., when the | |
101 | .I shm_nattch | |
102 | member of the associated structure | |
103 | .I shmid_ds | |
104 | is zero.) The user must be the owner, creator, or the super-user. | |
105 | .PP | |
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. | |
108 | .PP | |
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) | |
111 | .br | |
112 | .TP 12 | |
113 | .B SHM_LOCK | |
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. | |
116 | .TP | |
117 | .B SHM_UNLOCK | |
118 | allows the shared memory segment to be swapped out. | |
119 | .PP | |
120 | The | |
121 | .BR IPC_INFO , | |
122 | .BR SHM_STAT | |
123 | and | |
124 | .B SHM_INFO | |
125 | control calls are used by the | |
126 | .BR ipcs (8) | |
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. | |
129 | .SH "RETURN VALUE" | |
130 | 0 is returned on success, \-1 on error. | |
131 | .SH ERRORS | |
132 | On error, | |
133 | .B errno | |
134 | will be set to one of the following: | |
135 | .TP 12 | |
136 | .B EACCES | |
137 | is returned if \fBIPC_STAT\fP is requested and | |
138 | \fIshm_perm.modes\fP does not allow read access for | |
139 | .IR msqid . | |
140 | .TP | |
141 | .B EFAULT | |
142 | The argument | |
143 | .I cmd | |
144 | has value | |
145 | .B IPC_SET | |
146 | or | |
147 | .B IPC_STAT | |
148 | but the address pointed to by | |
149 | .I buf | |
150 | isn't accessible. | |
151 | .TP | |
152 | .B EINVAL | |
153 | is returned if \fIshmid\fP is not a valid identifier, or \fIcmd\fP | |
154 | is not a valid command. | |
155 | .TP | |
156 | .B EIDRM | |
157 | is returned if \fIshmid\fP points to a removed identifier. | |
158 | .TP | |
159 | .B EPERM | |
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 | |
162 | (as found in | |
163 | .IR shm_perm.cuid ), | |
164 | the owner | |
165 | (as found in | |
166 | .IR shm_perm.uid ), | |
167 | or the super-user. | |
168 | .TP | |
169 | .B EOVERFLOW | |
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 | |
172 | .IR buf . | |
173 | .SH NOTE | |
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 | |
178 | .IR cmd .) | |
179 | .SH "CONFORMING TO" | |
180 | SVr4, SVID. SVr4 documents additional error conditions EINVAL, | |
181 | ENOENT, ENOSPC, ENOMEM, EEXIST. Neither SVr4 nor SVID documents | |
182 | an EIDRM error condition. | |
183 | .SH "SEE ALSO" | |
184 | .BR shmget (2), | |
185 | .BR shmop (2) |