]>
Commit | Line | Data |
---|---|---|
2c731798 | 1 | '\" t |
c11b1abf | 2 | .\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> |
2c731798 | 3 | .\" |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
2c731798 MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
c13182ef | 13 | .\" |
2c731798 MK |
14 | .\" Since the Linux kernel and libraries are constantly changing, this |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
10d76543 MK |
17 | .\" the use of the information contained herein. The author(s) may not |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
c13182ef | 21 | .\" |
2c731798 MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
2c731798 | 25 | .\" |
4b8c67d9 | 26 | .TH SEM_OPEN 3 2017-09-15 "Linux" "Linux Programmer's Manual" |
2c731798 | 27 | .SH NAME |
d9bfdb9c | 28 | sem_open \- initialize and open a named semaphore |
2c731798 MK |
29 | .SH SYNOPSIS |
30 | .nf | |
87d17de4 | 31 | .BR "#include <fcntl.h>" " /* For O_* constants */" |
84c517a4 | 32 | .BR "#include <sys/stat.h>" " /* For mode constants */" |
2c731798 | 33 | .B #include <semaphore.h> |
68e4db0a | 34 | .PP |
2c731798 MK |
35 | .BI "sem_t *sem_open(const char *" name ", int " oflag ); |
36 | .BI "sem_t *sem_open(const char *" name ", int " oflag ", " | |
37 | .BI " mode_t " mode ", unsigned int " value ); | |
38 | .fi | |
68e4db0a | 39 | .PP |
2c5f8c8c | 40 | Link with \fI\-pthread\fP. |
2c731798 MK |
41 | .SH DESCRIPTION |
42 | .BR sem_open () | |
43 | creates a new POSIX semaphore or opens an existing semaphore. | |
44 | The semaphore is identified by | |
45 | .IR name . | |
c13182ef MK |
46 | For details of the construction of |
47 | .IR name , | |
2c731798 MK |
48 | see |
49 | .BR sem_overview (7). | |
847e0d88 | 50 | .PP |
2c731798 MK |
51 | The |
52 | .I oflag | |
53 | argument specifies flags that control the operation of the call. | |
87d17de4 MK |
54 | (Definitions of the flags values can be obtained by including |
55 | .IR <fcntl.h> .) | |
2c731798 MK |
56 | If |
57 | .B O_CREAT | |
c13182ef MK |
58 | is specified in |
59 | .IR oflag , | |
60 | then the semaphore is created if | |
2c731798 | 61 | it does not already exist. |
c13182ef MK |
62 | The owner (user ID) of the semaphore is set to the effective |
63 | user ID of the calling process. | |
64 | The group ownership (group ID) is set to the effective group ID | |
2c731798 | 65 | of the calling process. |
9ee4a2b6 | 66 | .\" In reality the filesystem IDs are used on Linux. |
2c731798 MK |
67 | If both |
68 | .B O_CREAT | |
69 | and | |
70 | .B O_EXCL | |
71 | are specified in | |
72 | .IR oflag , | |
73 | then an error is returned if a semaphore with the given | |
74 | .I name | |
75 | already exists. | |
76 | .PP | |
c13182ef | 77 | If |
2c731798 | 78 | .B O_CREAT |
c13182ef | 79 | is specified in |
2c731798 MK |
80 | .IR oflag , |
81 | then two additional arguments must be supplied. | |
82 | The | |
83 | .I mode | |
84 | argument specifies the permissions to be placed on the new semaphore, | |
85 | as for | |
86 | .BR open (2). | |
87d17de4 MK |
87 | (Symbolic definitions for the permissions bits can be obtained by including |
88 | .IR <sys/stat.h> .) | |
2c731798 | 89 | The permissions settings are masked against the process umask. |
c13182ef | 90 | Both read and write permission should be granted to each class of |
2c731798 | 91 | user that will access the semaphore. |
c13182ef | 92 | The |
2c731798 MK |
93 | .I value |
94 | argument specifies the initial value for the new semaphore. | |
c13182ef | 95 | If |
2c731798 MK |
96 | .B O_CREAT |
97 | is specified, and a semaphore with the given | |
98 | .I name | |
99 | already exists, then | |
100 | .I mode | |
101 | and | |
102 | .I value | |
103 | are ignored. | |
104 | .SH RETURN VALUE | |
105 | On success, | |
106 | .BR sem_open () | |
c13182ef | 107 | returns the address of the new semaphore; |
7145b9a9 | 108 | this address is used when calling other semaphore-related functions. |
c13182ef | 109 | On error, |
2c731798 | 110 | .BR sem_open () |
c13182ef | 111 | returns |
2c731798 MK |
112 | .BR SEM_FAILED , |
113 | with | |
114 | .I errno | |
115 | set to indicate the error. | |
116 | .SH ERRORS | |
117 | .TP | |
1b3fc756 | 118 | .B EACCES |
c13182ef | 119 | The semaphore exists, but the caller does not have permission to |
2c731798 MK |
120 | open it. |
121 | .TP | |
122 | .B EEXIST | |
123 | Both | |
124 | .B O_CREAT | |
125 | and | |
126 | .B O_EXCL | |
c13182ef | 127 | were specified in |
2c731798 | 128 | .IR oflag , |
c13182ef | 129 | but a semaphore with this |
2c731798 MK |
130 | .I name |
131 | already exists. | |
132 | .TP | |
133 | .B EINVAL | |
c13182ef | 134 | .I value |
2c731798 MK |
135 | was greater than |
136 | .BR SEM_VALUE_MAX . | |
137 | .TP | |
18fe47e0 MK |
138 | .B EINVAL |
139 | .I name | |
140 | consists of just "/", followed by no other characters. | |
141 | .TP | |
2c731798 | 142 | .B EMFILE |
26c32fab | 143 | The per-process limit on the number of open file descriptors has been reached. |
2c731798 MK |
144 | .TP |
145 | .B ENAMETOOLONG | |
0daa9e92 | 146 | .I name |
2c731798 MK |
147 | was too long. |
148 | .TP | |
149 | .B ENFILE | |
e258766b | 150 | The system-wide limit on the total number of open files has been reached. |
2c731798 MK |
151 | .TP |
152 | .B ENOENT | |
153 | The | |
154 | .B O_CREAT | |
c13182ef | 155 | flag was not specified in |
db2fff8c | 156 | .IR oflag |
c13182ef | 157 | and no semaphore with this |
2c731798 | 158 | .I name |
db2fff8c JTT |
159 | exists; |
160 | or, | |
d603cc27 | 161 | .\" this error can occur if we have a name of the (nonportable) form |
db2fff8c JTT |
162 | .\" /dir/name, and the directory /dev/shm/dir does not exist. |
163 | .B O_CREAT | |
164 | was specified, but | |
165 | .I name | |
166 | wasn't well formed. | |
2c731798 MK |
167 | .TP |
168 | .B ENOMEM | |
169 | Insufficient memory. | |
ca6b4c15 ZL |
170 | .SH ATTRIBUTES |
171 | For an explanation of the terms used in this section, see | |
172 | .BR attributes (7). | |
173 | .TS | |
174 | allbox; | |
175 | lb lb lb | |
176 | l l l. | |
177 | Interface Attribute Value | |
178 | T{ | |
179 | .BR sem_open () | |
180 | T} Thread safety MT-Safe | |
181 | .TE | |
847e0d88 | 182 | .sp 1 |
2c731798 | 183 | .SH CONFORMING TO |
64131c24 | 184 | POSIX.1-2001, POSIX.1-2008. |
47297adb | 185 | .SH SEE ALSO |
2c731798 MK |
186 | .BR sem_close (3), |
187 | .BR sem_getvalue (3), | |
188 | .BR sem_post (3), | |
189 | .BR sem_unlink (3), | |
190 | .BR sem_wait (3), | |
191 | .BR sem_overview (7) |