Debian Codegraph @

upstream/debian-unstable/man3/sem_open.3

raw
1 '\" t
2 .\" Copyright 2006, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH sem_open 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 sem_open \- initialize and open a named semaphore
10 .SH LIBRARY
11 POSIX threads library
12 .RI ( libpthread ,\~ \-lpthread )
13 .SH SYNOPSIS
14 .nf
15 .BR "#include <fcntl.h>" " /* For O_* constants */"
16 .BR "#include <sys/stat.h>" " /* For mode constants */"
17 .B #include <semaphore.h>
18 .P
19 .BI "sem_t *sem_open(const char *" name ", int " oflag ", ..."
20 .BI " \f[R]/*\f[] mode_t " mode \
21 ", unsigned int " value " \f[R]*/\f[] );"
22 .fi
23 .SH DESCRIPTION
24 .BR sem_open ()
25 creates a new POSIX semaphore or opens an existing semaphore.
26 The semaphore is identified by
27 .IR name .
28 For details of the construction of
29 .IR name ,
30 see
31 .BR sem_overview (7).
32 .P
33 The
34 .I oflag
35 argument specifies flags that control the operation of the call.
36 (Definitions of the flags values can be obtained by including
37 .IR <fcntl.h> .)
38 If
39 .B O_CREAT
40 is specified in
41 .IR oflag ,
42 then the semaphore is created if
43 it does not already exist.
44 The owner (user ID) of the semaphore is set to the effective
45 user ID of the calling process.
46 The group ownership (group ID) is set to the effective group ID
47 of the calling process.
48 .\" In reality the filesystem IDs are used on Linux.
49 If both
50 .B O_CREAT
51 and
52 .B O_EXCL
53 are specified in
54 .IR oflag ,
55 then an error is returned if a semaphore with the given
56 .I name
57 already exists.
58 .P
59 If
60 .B O_CREAT
61 is specified in
62 .IR oflag ,
63 then two additional arguments must be supplied.
64 The
65 .I mode
66 argument specifies the permissions to be placed on the new semaphore,
67 as for
68 .BR open (2).
69 (Symbolic definitions for the permissions bits can be obtained by including
70 .IR <sys/stat.h> .)
71 The permissions settings are masked against the process umask.
72 Both read and write permission should be granted to each class of
73 user that will access the semaphore.
74 The
75 .I value
76 argument specifies the initial value for the new semaphore.
77 If
78 .B O_CREAT
79 is specified, and a semaphore with the given
80 .I name
81 already exists, then
82 .I mode
83 and
84 .I value
85 are ignored.
86 .SH RETURN VALUE
87 On success,
88 .BR sem_open ()
89 returns the address of the new semaphore;
90 this address is used when calling other semaphore-related functions.
91 On error,
92 .BR sem_open ()
93 returns
94 .BR SEM_FAILED ,
95 with
96 .I errno
97 set to indicate the error.
98 .SH ERRORS
99 .TP
100 .B EACCES
101 The semaphore exists, but the caller does not have permission to
102 open it.
103 .TP
104 .B EEXIST
105 Both
106 .B O_CREAT
107 and
108 .B O_EXCL
109 were specified in
110 .IR oflag ,
111 but a semaphore with this
112 .I name
113 already exists.
114 .TP
115 .B EINVAL
116 .I value
117 was greater than
118 .BR SEM_VALUE_MAX .
119 .TP
120 .B EINVAL
121 .I name
122 consists of just "/", followed by no other characters.
123 .TP
124 .B EMFILE
125 The per-process limit on the number of open file descriptors has been reached.
126 .TP
127 .B ENAMETOOLONG
128 .I name
129 was too long.
130 .TP
131 .B ENFILE
132 The system-wide limit on the total number of open files has been reached.
133 .TP
134 .B ENOENT
135 The
136 .B O_CREAT
137 flag was not specified in
138 .I oflag
139 and no semaphore with this
140 .I name
141 exists;
142 or,
143 .\" this error can occur if we have a name of the (nonportable) form
144 .\" /dir/name, and the directory /dev/shm/dir does not exist.
145 .B O_CREAT
146 was specified, but
147 .I name
148 wasn't well formed.
149 .TP
150 .B ENOMEM
151 Insufficient memory.
152 .SH ATTRIBUTES
153 For an explanation of the terms used in this section, see
154 .BR attributes (7).
155 .TS
156 allbox;
157 lbx lb lb
158 l l l.
159 Interface Attribute Value
160 T{
161 .na
162 .nh
163 .BR sem_open ()
164 T} Thread safety MT-Safe
165 .TE
166 .SH STANDARDS
167 POSIX.1-2008.
168 .SH HISTORY
169 POSIX.1-2001.
170 .SH SEE ALSO
171 .BR sem_close (3),
172 .BR sem_getvalue (3),
173 .BR sem_post (3),
174 .BR sem_unlink (3),
175 .BR sem_wait (3),
176 .BR sem_overview (7)