]> git.pld-linux.org Git - packages/man-pages.git/blob - semget.2
- separated POSIX man pages, rel. 1
[packages/man-pages.git] / semget.2
1 .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
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 Tue Oct 22 17:54:56 1996 by Eric S. Raymond <esr@thyrsus.com>
24 .\" Modified 1 Jan 2002, Martin Schulze <joey@infodrom.org>
25 .\" Modified 4 Jan 2002, Michael Kerrisk <mtk16@ext.canterbury.ac.nz>
26 .\"
27 .TH SEMGET 2 2002-01-04 "Linux 2.5" "Linux Programmer's Manual" 
28 .SH NAME
29 semget \- get a semaphore set identifier
30 .SH SYNOPSIS
31 .nf
32 .B
33 #include <sys/types.h>
34 .B
35 #include <sys/ipc.h>
36 .B
37 #include <sys/sem.h>
38 .fi
39 .sp
40 .BI "int semget(key_t " key ,
41 .BI "int " nsems ,
42 .BI "int " semflg );
43 .SH DESCRIPTION
44 This function returns the semaphore set identifier
45 associated with the argument
46 .IR key .
47 A new set of
48 .I nsems
49 semaphores is created if
50 .I key
51 has the value
52 .B IPC_PRIVATE
53 or if no existing semaphore set is associated to
54 .I key
55 and
56 .B IPC_CREAT
57 is asserted in
58 .I semflg
59 (i.e.
60 .IR semflg " &"
61 .B IPC_CREAT
62 isn't zero).
63 .PP
64 The presence in
65 .I semflg
66 of the fields
67 .B IPC_CREAT
68 and
69 .B IPC_EXCL
70 plays the same role, with respect to the existence
71 of the semaphore set, as the presence
72 of
73 .B O_CREAT
74 and
75 .B O_EXCL
76 in the mode argument of the
77 .BR open (2)
78 system call: i.e. the
79 .B semget
80 function fails if
81 .I semflg
82 asserts both
83 .B IPC_CREAT
84 and
85 .B IPC_EXCL
86 and a semaphore set already exists for
87 .IR key .
88 .PP
89 Upon creation, the low-order 9 bits of the argument
90 .I semflg
91 define the access permissions (for owner, group and others)
92 for the semaphore set.
93 These bits have the same format, and the same
94 meaning, as the mode argument in the
95 .BR open (2)
96 or
97 .BR creat (2)
98 system calls (though the execute permissions are
99 not meaningful for semaphores, and write permissions mean permission
100 to alter semaphore values).
101 .PP
102 When creating a new semaphore set,
103 .B semget
104 initializes the semaphore set's associated data structure
105 .B semid_ds
106 as follows:
107 .IP
108 .B sem_perm.cuid
109 and
110 .B sem_perm.uid
111 are set to the effective user\-ID of the calling process.
112 .IP
113 .B sem_perm.cgid
114 and
115 .B sem_perm.gid
116 are set to the effective group\-ID of the calling process.
117 .IP
118 The low-order 9 bits of
119 .B sem_perm.mode
120 are set to the low-order 9 bits of
121 .IR semflg .
122 .IP
123 .B sem_nsems
124 is set to the value of
125 .IR nsems .
126 .IP
127 .B sem_otime
128 is set to 0.
129 .IP
130 .B sem_ctime
131 is set to the current time.
132 .PP
133 The argument
134 .I nsems
135 can be
136 .B 0
137 (a don't care)
138 when a semaphore set is not being created.
139 Otherwise
140 .I nsems
141 must be greater than
142 .B 0
143 and less than or equal to the maximum number of semaphores per semaphore set
144 .RB ( SEMMSL ).
145 .PP
146 If the semaphore set already exists, the access permissions are
147 verified.
148 .\" and a check is made to see if it is marked for destruction.
149 .SH "RETURN VALUE"
150 If successful, the return value will be the semaphore set identifier
151 (a nonnegative integer), otherwise
152 .B \-1
153 is returned, with
154 .I errno
155 indicating the error.
156 .SH ERRORS
157 On failure
158 .I errno
159 will be set to one of the following:
160 .TP 11
161 .B EACCES
162 A semaphore set exists for
163 .IR key ,
164 but the calling process does not have permission to access the set.
165 .TP
166 .B EEXIST
167 A semaphore set exists for
168 .B key
169 and
170 .I semflg
171 was asserting both
172 .B IPC_CREAT
173 and
174 .BR IPC_EXCL .
175 .\" .TP
176 .\" .B EIDRM
177 .\" The semaphore set is marked to be deleted.
178 .TP
179 .B ENOENT
180 No semaphore set exists for
181 .I key
182 and
183 .I semflg
184 wasn't asserting
185 .BR IPC_CREAT .
186 .TP
187 .B EINVAL
188 .IR nsems
189 is less than 0 or greater than the limit on the number
190 of semaphores per semaphore set
191 .RB ( SEMMSL ),
192 or a semaphore set corresponding to
193 .I key
194 already exists, and
195 .I nsems
196 is larger than the number of semaphores in that set.
197 .TP
198 .B ENOMEM
199 A semaphore set has to be created but the system has not enough memory for
200 the new data structure.
201 .TP
202 .B ENOSPC
203 A semaphore set has to be created but the system limit for the maximum
204 number of semaphore sets
205 .RB ( SEMMNI ),
206 or the system wide maximum number of semaphores
207 .RB ( SEMMNS ),
208 would be exceeded.
209 .SH NOTES
210 .B IPC_PRIVATE
211 isn't a flag field but a
212 .B key_t
213 type.
214 If this special value is used for
215 .IR key ,
216 the system call ignores everything but the low-order 9 bits of
217 .I semflg
218 and creates a new semaphore set (on success).
219 .PP
220 The followings are limits on semaphore set resources affecting a
221 .B semget
222 call:
223 .TP 11
224 .B SEMMNI
225 System wide maximum number of semaphore sets: policy dependent.
226 .TP
227 .B SEMMSL
228 Maximum number of semaphores per semid: implementation dependent
229 (500 currently).
230 .TP
231 .B SEMMNS
232 System wide maximum number of semaphores: policy dependent.
233 Values greater than
234 .B SEMMSL * SEMMNI
235 makes it irrelevant.
236 .SH BUGS
237 Use of
238 .B IPC_PRIVATE
239 doesn't inhibit to other processes the access to the allocated
240 semaphore set.
241 .PP
242 As for the files, there is currently no intrinsic way for a process to ensure
243 exclusive access to a semaphore set.
244 Asserting both
245 .B IPC_CREAT
246 and
247 .B IPC_EXCL
248 in
249 .I semflg
250 only ensures (on success) that a new semaphore set will be created,
251 it doesn't imply exclusive access to the semaphore set.
252 .PP
253 The data structure associated with each semaphore in the set
254 isn't initialized by the system call.
255 In order to initialize those data structures, one has to execute a
256 subsequent call to
257 .BR semctl (2)
258 to perform a
259 .B SETVAL
260 or a
261 .B SETALL
262 command on the semaphore set.
263 .SH "CONFORMING TO"
264 SVr4, SVID.
265 SVr4 documents additional error conditions EFBIG, E2BIG, EAGAIN,
266 ERANGE, EFAULT.
267 .SH "SEE ALSO"
268 .BR ftok (3),
269 .BR ipc (5),
270 .BR semctl (2),
271 .BR semop (2)
This page took 0.110761 seconds and 3 git commands to generate.