1SEM_OPEN(3P)               POSIX Programmer's Manual              SEM_OPEN(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       sem_open — initialize and open a named semaphore
13

SYNOPSIS

15       #include <semaphore.h>
16
17       sem_t *sem_open(const char *name, int oflag, ...);
18

DESCRIPTION

20       The sem_open() function shall establish a connection  between  a  named
21       semaphore  and a process. Following a call to sem_open() with semaphore
22       name name, the process may reference the semaphore associated with name
23       using the address returned from the call. This semaphore may be used in
24       subsequent  calls  to   sem_wait(),   sem_timedwait(),   sem_trywait(),
25       sem_post(),  and  sem_close().   The  semaphore  remains usable by this
26       process  until  the  semaphore  is  closed  by  a  successful  call  to
27       sem_close(), _exit(), or one of the exec functions.
28
29       The  oflag argument controls whether the semaphore is created or merely
30       accessed by the call to sem_open().  The following flag bits may be set
31       in oflag:
32
33       O_CREAT   This  flag  is  used  to  create  a  semaphore if it does not
34                 already exist.  If O_CREAT is set and the  semaphore  already
35                 exists,  then  O_CREAT  has  no effect, except as noted under
36                 O_EXCL. Otherwise, sem_open() creates a named semaphore.  The
37                 O_CREAT  flag  requires  a third and a fourth argument: mode,
38                 which is  of  type  mode_t,  and  value,  which  is  of  type
39                 unsigned.   The semaphore is created with an initial value of
40                 value.  Valid initial values for semaphores are less than  or
41                 equal to {SEM_VALUE_MAX}.
42
43                 The  user  ID  of the semaphore shall be set to the effective
44                 user ID of the process. The group ID of the  semaphore  shall
45                 be  set to the effective group ID of the process; however, if
46                 the name argument is visible in the file system, the group ID
47                 may  be  set to the group ID of the containing directory. The
48                 permission bits of the semaphore are set to the value of  the
49                 mode argument except those set in the file mode creation mask
50                 of the process. When bits in mode other than the file permis‐
51                 sion bits are specified, the effect is unspecified.
52
53                 After the semaphore named name has been created by sem_open()
54                 with the O_CREAT flag, other processes  can  connect  to  the
55                 semaphore by calling sem_open() with the same value of name.
56
57       O_EXCL    If  O_EXCL and O_CREAT are set, sem_open() fails if the sema‐
58                 phore name exists. The check for the existence of  the  sema‐
59                 phore  and the creation of the semaphore if it does not exist
60                 are  atomic  with  respect  to  other   processes   executing
61                 sem_open()  with O_EXCL and O_CREAT set. If O_EXCL is set and
62                 O_CREAT is not set, the effect is undefined.
63
64                 If flags other than O_CREAT and O_EXCL are specified  in  the
65                 oflag parameter, the effect is unspecified.
66
67       The  name  argument points to a string naming a semaphore object. It is
68       unspecified whether the name appears in the file system and is  visible
69       to  functions  that take pathnames as arguments. The name argument con‐
70       forms to the construction rules for a pathname, except that the  inter‐
71       pretation  of <slash> characters other than the leading <slash> charac‐
72       ter in name is implementation-defined, and that the length  limits  for
73       the  name  argument are implementation-defined and need not be the same
74       as the pathname limits {PATH_MAX} and {NAME_MAX}.  If name begins  with
75       the  <slash> character, then processes calling sem_open() with the same
76       value of name shall refer to the same semaphore object, as long as that
77       name  has  not  been  removed.  If name does not begin with the <slash>
78       character, the effect is implementation-defined.
79
80       If a process makes multiple successful calls  to  sem_open()  with  the
81       same  value  for name, the same semaphore address shall be returned for
82       each such successful call, provided that there have been  no  calls  to
83       sem_unlink()  for  this semaphore, and at least one previous successful
84       sem_open() call  for  this  semaphore  has  not  been  matched  with  a
85       sem_close() call.
86
87       References to copies of the semaphore produce undefined results.
88

RETURN VALUE

90       Upon  successful  completion,  the sem_open() function shall return the
91       address of the  semaphore.  Otherwise,  it  shall  return  a  value  of
92       SEM_FAILED  and  set errno to indicate the error. The symbol SEM_FAILED
93       is defined in the  <semaphore.h>  header.  No  successful  return  from
94       sem_open() shall return the value SEM_FAILED.
95

ERRORS

97       If any of the following conditions occur, the sem_open() function shall
98       return SEM_FAILED and set errno to the corresponding value:
99
100       EACCES The named semaphore exists  and  the  permissions  specified  by
101              oflag are denied, or the named semaphore does not exist and per‐
102              mission to create the named semaphore is denied.
103
104       EEXIST O_CREAT and O_EXCL are  set  and  the  named  semaphore  already
105              exists.
106
107       EINTR  The sem_open() operation was interrupted by a signal.
108
109       EINVAL The sem_open() operation is not supported for the given name, or
110              O_CREAT was specified  in  oflag  and  value  was  greater  than
111              {SEM_VALUE_MAX}.
112
113       EMFILE Too many semaphore descriptors or file descriptors are currently
114              in use by this process.
115
116       ENFILE Too many semaphores are currently open in the system.
117
118       ENOENT O_CREAT is not set and the named semaphore does not exist.
119
120       ENOMEM There is insufficient memory for the creation of the  new  named
121              semaphore.
122
123       ENOSPC There is insufficient space on a storage device for the creation
124              of the new named semaphore.
125
126       If any of the following conditions occur, the sem_open()  function  may
127       return SEM_FAILED and set errno to the corresponding value:
128
129       ENAMETOOLONG
130              The  length  of  the  name argument exceeds {_POSIX_PATH_MAX} on
131              systems  that  do  not  support  the  XSI  option   or   exceeds
132              {_XOPEN_PATH_MAX}  on  XSI  systems, or has a pathname component
133              that is longer than {_POSIX_NAME_MAX} on  systems  that  do  not
134              support  the  XSI option or longer than {_XOPEN_NAME_MAX} on XSI
135              systems.
136
137       The following sections are informative.
138

EXAMPLES

140       None.
141

APPLICATION USAGE

143       None.
144

RATIONALE

146       Early drafts required an error return value of -1 with the type sem_t *
147       for  the  sem_open()  function,  which is not guaranteed to be portable
148       across implementations. The revised text provides  the  symbolic  error
149       code SEM_FAILED to eliminate the type conflict.
150

FUTURE DIRECTIONS

152       A  future  version  might require the sem_open() and sem_unlink() func‐
153       tions to have semantics similar to normal file system operations.
154

SEE ALSO

156       semctl(), semget(), semop(), sem_close(), sem_post(), sem_timedwait(),
157       sem_trywait(), sem_unlink()
158
159       The Base Definitions volume of POSIX.1‐2017, <semaphore.h>
160
162       Portions  of  this text are reprinted and reproduced in electronic form
163       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
164       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
165       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
166       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
167       event of any discrepancy between this version and the original IEEE and
168       The  Open Group Standard, the original IEEE and The Open Group Standard
169       is the referee document. The original Standard can be  obtained  online
170       at http://www.opengroup.org/unix/online.html .
171
172       Any  typographical  or  formatting  errors that appear in this page are
173       most likely to have been introduced during the conversion of the source
174       files  to  man page format. To report such errors, see https://www.ker
175       nel.org/doc/man-pages/reporting_bugs.html .
176
177
178
179IEEE/The Open Group                  2017                         SEM_OPEN(3P)
Impressum