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