| blob | 2f0b68a1905651e5d45db927407d1a184103ec64 |
1 .\" $NetBSD: shmctl.2,v 1.21 2010/03/22 19:30:55 joerg Exp $
2 .\"
3 .\" Copyright (c) 1995 Frank van der Linden
4 .\" All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. All advertising materials mentioning features or use of this software
15 .\" must display the following acknowledgement:
16 .\" This product includes software developed for the NetBSD Project
17 .\" by Frank van der Linden
18 .\" 4. The name of the author may not be used to endorse or promote products
19 .\" derived from this software without specific prior written permission
20 .\"
21 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
22 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
23 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
24 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
25 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
26 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
30 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 .\"
32 .Dd November 25, 2006
33 .Dt SHMCTL 2
34 .Os
35 .Sh NAME
36 .Nm shmctl
37 .Nd shared memory control operations
38 .Sh LIBRARY
39 .Lb libc
40 .Sh SYNOPSIS
41 .In sys/shm.h
42 .Ft int
43 .Fn shmctl "int shmid" "int cmd" "struct shmid_ds *buf"
44 .Sh DESCRIPTION
45 The
46 .Fn shmctl
47 system call performs control operations on the shared memory segment
48 specified by
49 .Fa shmid .
50 .Pp
51 Each shared memory segment has a
52 .Sy shmid_ds
53 structure associated with it which contains the following members:
54 .Bd -literal
55 struct ipc_perm shm_perm; /* operation permissions */
56 size_t shm_segsz; /* size of segment in bytes */
57 pid_t shm_lpid; /* pid of last shm op */
58 pid_t shm_cpid; /* pid of creator */
59 shmatt_t shm_nattch; /* # of current attaches */
60 time_t shm_atime; /* last shmat() time */
61 time_t shm_dtime; /* last shmdt() time */
62 time_t shm_ctime; /* last change by shmctl() */
63 .Ed
64 .Pp
65 The
66 .Sy ipc_perm
67 structure used inside the
68 .Sy shmid_ds
69 structure is defined in
70 .In sys/ipc.h
71 and contains the following members:
72 .Bd -literal
73 uid_t cuid; /* creator user id */
74 gid_t cgid; /* creator group id */
75 uid_t uid; /* user id */
76 gid_t gid; /* group id */
77 mode_t mode; /* permission (lower 9 bits) */
78 .Ed
79 .Pp
80 The operation to be performed by
81 .Fn shmctl
82 is specified in
83 .Fa cmd
84 and is one of:
85 .Bl -tag -width IPC_RMIDX
86 .It Dv IPC_STAT
87 Gather information about the shared memory segment and place it in the
88 structure pointed to by
89 .Fa buf .
90 .It Dv IPC_SET
91 Set the value of the
92 .Va shm_perm.uid ,
93 .Va shm_perm.gid
94 and
95 .Va shm_perm.mode
96 fields in the structure associated with
97 .Fa shmid .
98 The values are taken from the corresponding fields in the structure
99 pointed to by
100 .Fa buf .
101 This operation can only be executed by the super-user, or a process that
102 has an effective user id equal to either
103 .Va shm_perm.cuid
104 or
105 .Va shm_perm.uid
106 in the data structure associated with the shared memory segment.
107 .It Dv IPC_RMID
108 Remove the shared memory segment specified by
109 .Fa shmid
110 and destroy the data associated with it.
111 Only the super-user or a process with an effective uid equal to the
112 .Va shm_perm.cuid
113 or
114 .Va shm_perm.uid
115 values in the data structure associated with the segment can do this.
116 .It Dv SHM_LOCK
117 Lock the shared memory segment specified by
118 .Fa shmid
119 in memory.
120 This operation can only be executed by the super-user.
121 .It Dv SHM_UNLOCK
122 Unlock the shared memory segment specified by
123 .Fa shmid .
124 This operation can only be executed by the super-user.
125 .El
126 .Pp
127 The read and write permissions on a shared memory identifier
128 are determined by the
129 .Va shm_perm.mode
130 field in the same way as is
131 done with files (see
132 .Xr chmod 2 ) ,
133 but the effective uid can match either the
134 .Va shm_perm.cuid
135 field or the
136 .Va shm_perm.uid
137 field, and the
138 effective gid can match either
139 .Va shm_perm.cgid
140 or
141 .Va shm_perm.gid .
142 .Sh RETURN VALUES
143 Upon successful completion, a value of 0 is returned.
144 Otherwise, \-1 is returned and the global variable
145 .Va errno
146 is set to indicate the error.
147 .Sh ERRORS
148 .Fn shmctl
149 will fail if:
150 .Bl -tag -width Er
151 .It Bq Er EACCES
152 The command is
153 .Dv IPC_STAT
154 and the caller has no read permission for this shared memory segment.
155 .It Bq Er EFAULT
156 .Fa buf
157 specifies an invalid address.
158 .It Bq Er EINVAL
159 .Fa shmid
160 is not a valid shared memory segment identifier.
161 .Pp
162 .Va cmd
163 is not a valid command.
164 .It Bq Er ENOMEM
165 The
166 .Fa cmd
167 is equal to
168 .Dv SHM_LOCK
169 and there is not enough physical memory.
170 .It Bq Er EPERM
171 .Fa cmd
172 is equal to
173 .Dv IPC_SET
174 or
175 .Dv IPC_RMID
176 and the caller is not the super-user, nor does
177 the effective uid match either the
178 .Va shm_perm.uid
179 or
180 .Va shm_perm.cuid
181 fields of the data structure associated with the shared memory segment.
182 .Pp
183 An attempt was made to increase the value of
184 .Va shm_qbytes
185 through
186 .Dv IPC_SET
187 but the caller is not the super-user.
188 .Pp
189 The
190 .Fa cmd
191 is equal to
192 .Dv SHM_LOCK
193 or
194 .Dv SHM_UNLOCK
195 and the caller is not the super-user.
196 .El
197 .Sh SEE ALSO
198 .Xr ipcrm 1 ,
199 .Xr ipcs 1 ,
200 .Xr shmat 2 ,
201 .Xr shmget 2
202 .Sh STANDARDS
203 The
204 .Nm
205 system call conforms to
206 .St -xsh5 .
207 .Sh HISTORY
208 Shared memory segments appeared in the first release of
209 .At V .