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