logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

sem_open.3p (8116B)


  1. '\" et
  2. .TH SEM_OPEN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. sem_open
  12. \(em initialize and open a named semaphore
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <semaphore.h>
  17. .P
  18. sem_t *sem_open(const char *\fIname\fP, int \fIoflag\fP, ...);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIsem_open\fR()
  23. function shall establish a connection between a named semaphore
  24. and a process. Following a call to
  25. \fIsem_open\fR()
  26. with semaphore name
  27. .IR name ,
  28. the process may reference the semaphore associated with
  29. .IR name
  30. using the address returned from the call. This semaphore may be used
  31. in subsequent calls to
  32. \fIsem_wait\fR(),
  33. \fIsem_timedwait\fR(),
  34. \fIsem_trywait\fR(),
  35. \fIsem_post\fR(),
  36. and
  37. \fIsem_close\fR().
  38. The semaphore remains usable by this process until the semaphore is
  39. closed by a successful call to
  40. \fIsem_close\fR(),
  41. \fI_exit\fR(),
  42. or one of the
  43. .IR exec
  44. functions.
  45. .P
  46. The
  47. .IR oflag
  48. argument controls whether the semaphore is created or merely accessed
  49. by the call to
  50. \fIsem_open\fR().
  51. The following flag bits may be set in
  52. .IR oflag :
  53. .IP O_CREAT 10
  54. This flag is used to create a semaphore if it does not already exist.
  55. If O_CREAT is set and the semaphore already exists, then O_CREAT has no
  56. effect, except as noted under O_EXCL. Otherwise,
  57. \fIsem_open\fR()
  58. creates a named semaphore. The O_CREAT flag requires a third and a
  59. fourth argument:
  60. .IR mode ,
  61. which is of type
  62. .BR mode_t ,
  63. and
  64. .IR value ,
  65. which is of type
  66. .BR unsigned .
  67. The semaphore is created with an initial value of
  68. .IR value .
  69. Valid initial values for semaphores are less than or equal to
  70. {SEM_VALUE_MAX}.
  71. .RS 10
  72. .P
  73. The user ID of the semaphore shall be set to the effective user ID of
  74. the process. The group ID of the semaphore shall be set to the effective
  75. group ID of the process; however, if the
  76. .IR name
  77. argument is visible in the file system, the group ID may be set to
  78. the group ID of the containing directory. The permission bits of the
  79. semaphore are set to the value of the
  80. .IR mode
  81. argument except those set in the file mode creation mask of the
  82. process. When bits in
  83. .IR mode
  84. other than the file permission bits are specified, the effect is
  85. unspecified.
  86. .P
  87. After the semaphore named
  88. .IR name
  89. has been created by
  90. \fIsem_open\fR()
  91. with the O_CREAT flag, other processes can connect to the semaphore by
  92. calling
  93. \fIsem_open\fR()
  94. with the same value of
  95. .IR name .
  96. .RE
  97. .IP O_EXCL 10
  98. If O_EXCL and O_CREAT are set,
  99. \fIsem_open\fR()
  100. fails if the semaphore
  101. .IR name
  102. exists. The check for the existence of the semaphore and the creation
  103. of the semaphore if it does not exist are atomic with respect to other
  104. processes executing
  105. \fIsem_open\fR()
  106. with O_EXCL and O_CREAT set. If O_EXCL is set and O_CREAT is not set,
  107. the effect is undefined.
  108. .RS 10
  109. .P
  110. If flags other than O_CREAT and O_EXCL are specified in the
  111. .IR oflag
  112. parameter, the effect is unspecified.
  113. .RE
  114. .P
  115. The
  116. .IR name
  117. argument points to a string naming a semaphore object. It is
  118. unspecified whether the name appears in the file system and is visible
  119. to functions that take pathnames as arguments. The
  120. .IR name
  121. argument conforms to the construction rules for a pathname, except
  122. that the interpretation of
  123. <slash>
  124. characters other than the leading
  125. <slash>
  126. character in
  127. .IR name
  128. is implementation-defined, and that the length limits for the
  129. .IR name
  130. argument are implementation-defined and need not be the same as
  131. the pathname limits
  132. {PATH_MAX}
  133. and
  134. {NAME_MAX}.
  135. If
  136. .IR name
  137. begins with the
  138. <slash>
  139. character, then processes calling
  140. \fIsem_open\fR()
  141. with the same value of
  142. .IR name
  143. shall refer to the same semaphore object, as long as that name has not
  144. been removed. If
  145. .IR name
  146. does not begin with the
  147. <slash>
  148. character, the effect is implementation-defined.
  149. .P
  150. If a process makes multiple successful calls to
  151. \fIsem_open\fR()
  152. with the same value for
  153. .IR name ,
  154. the same semaphore address shall be returned for each such successful
  155. call, provided that there have been no calls to
  156. \fIsem_unlink\fR()
  157. for this semaphore, and at least one previous successful
  158. \fIsem_open\fR()
  159. call for this semaphore has not been matched with a
  160. \fIsem_close\fR()
  161. call.
  162. .P
  163. References to copies of the semaphore produce undefined results.
  164. .SH "RETURN VALUE"
  165. Upon successful completion, the
  166. \fIsem_open\fR()
  167. function shall return the address of the semaphore. Otherwise, it
  168. shall return a value of SEM_FAILED and set
  169. .IR errno
  170. to indicate the error. The symbol SEM_FAILED is defined in the
  171. .IR <semaphore.h>
  172. header. No successful return from
  173. \fIsem_open\fR()
  174. shall return the value SEM_FAILED.
  175. .SH ERRORS
  176. If any of the following conditions occur, the
  177. \fIsem_open\fR()
  178. function shall return SEM_FAILED and set
  179. .IR errno
  180. to the corresponding value:
  181. .TP
  182. .BR EACCES
  183. The named semaphore exists and the permissions specified by
  184. .IR oflag
  185. are denied, or the named semaphore does not exist and permission to
  186. create the named semaphore is denied.
  187. .TP
  188. .BR EEXIST
  189. O_CREAT and O_EXCL are set and the named semaphore already exists.
  190. .TP
  191. .BR EINTR
  192. The
  193. \fIsem_open\fR()
  194. operation was interrupted by a signal.
  195. .TP
  196. .BR EINVAL
  197. The
  198. \fIsem_open\fR()
  199. operation is not supported for the given name, or O_CREAT was specified
  200. in
  201. .IR oflag
  202. and
  203. .IR value
  204. was greater than
  205. {SEM_VALUE_MAX}.
  206. .TP
  207. .BR EMFILE
  208. Too many semaphore descriptors or file descriptors are currently in use
  209. by this process.
  210. .TP
  211. .BR ENFILE
  212. Too many semaphores are currently open in the system.
  213. .TP
  214. .BR ENOENT
  215. O_CREAT is not set and the named semaphore does not exist.
  216. .TP
  217. .BR ENOMEM
  218. There is insufficient memory for the creation of the new named
  219. semaphore.
  220. .TP
  221. .BR ENOSPC
  222. There is insufficient space on a storage device for the creation of the
  223. new named semaphore.
  224. .P
  225. If any of the following conditions occur, the
  226. \fIsem_open\fR()
  227. function may return SEM_FAILED and set
  228. .IR errno
  229. to the corresponding value:
  230. .TP
  231. .BR ENAMETOOLONG
  232. .br
  233. The length of the
  234. .IR name
  235. argument exceeds
  236. {_POSIX_PATH_MAX}
  237. on systems that do not support the XSI option
  238. or exceeds
  239. {_XOPEN_PATH_MAX}
  240. on XSI systems,
  241. or has a pathname component that is longer than
  242. {_POSIX_NAME_MAX}
  243. on systems that do not support the XSI option
  244. or longer than
  245. {_XOPEN_NAME_MAX}
  246. on XSI systems.
  247. .LP
  248. .IR "The following sections are informative."
  249. .SH EXAMPLES
  250. None.
  251. .SH "APPLICATION USAGE"
  252. None.
  253. .SH RATIONALE
  254. Early drafts required an error return value of \-1 with the type
  255. .BR "sem_t *"
  256. for the
  257. \fIsem_open\fR()
  258. function, which is not guaranteed to be portable across
  259. implementations. The revised text provides the symbolic error code
  260. SEM_FAILED to eliminate the type conflict.
  261. .SH "FUTURE DIRECTIONS"
  262. A future version might require the
  263. \fIsem_open\fR()
  264. and
  265. \fIsem_unlink\fR()
  266. functions to have semantics similar to normal file system operations.
  267. .SH "SEE ALSO"
  268. .ad l
  269. .IR "\fIsemctl\fR\^(\|)",
  270. .IR "\fIsemget\fR\^(\|)",
  271. .IR "\fIsemop\fR\^(\|)",
  272. .IR "\fIsem_close\fR\^(\|)",
  273. .IR "\fIsem_post\fR\^(\|)",
  274. .IR "\fIsem_timedwait\fR\^(\|)",
  275. .IR "\fIsem_trywait\fR\^(\|)",
  276. .IR "\fIsem_unlink\fR\^(\|)"
  277. .ad b
  278. .P
  279. The Base Definitions volume of POSIX.1\(hy2017,
  280. .IR "\fB<semaphore.h>\fP"
  281. .\"
  282. .SH COPYRIGHT
  283. Portions of this text are reprinted and reproduced in electronic form
  284. from IEEE Std 1003.1-2017, Standard for Information Technology
  285. -- Portable Operating System Interface (POSIX), The Open Group Base
  286. Specifications Issue 7, 2018 Edition,
  287. Copyright (C) 2018 by the Institute of
  288. Electrical and Electronics Engineers, Inc and The Open Group.
  289. In the event of any discrepancy between this version and the original IEEE and
  290. The Open Group Standard, the original IEEE and The Open Group Standard
  291. is the referee document. The original Standard can be obtained online at
  292. http://www.opengroup.org/unix/online.html .
  293. .PP
  294. Any typographical or formatting errors that appear
  295. in this page are most likely
  296. to have been introduced during the conversion of the source files to
  297. man page format. To report such errors, see
  298. https://www.kernel.org/doc/man-pages/reporting_bugs.html .