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

semctl.3p (8364B)


  1. '\" et
  2. .TH SEMCTL "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. semctl
  12. \(em XSI semaphore control operations
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include\ <sys/sem.h>
  17. .P
  18. int semctl(int \fIsemid\fP, int \fIsemnum\fP, int \fIcmd\fP, ...);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIsemctl\fR()
  23. function operates on XSI semaphores (see the Base Definitions volume of POSIX.1\(hy2017,
  24. .IR "Section 4.17" ", " "Semaphore").
  25. It is unspecified whether this function interoperates with the
  26. realtime interprocess communication facilities defined in
  27. .IR "Section 2.8" ", " "Realtime".
  28. .P
  29. The
  30. \fIsemctl\fR()
  31. function provides a variety of semaphore control operations as
  32. specified by
  33. .IR cmd .
  34. The fourth argument is optional and depends upon the operation
  35. requested. If required, it is of type
  36. .BR "union semun" ,
  37. which the application shall explicitly declare:
  38. .sp
  39. .RS 4
  40. .nf
  41. union semun {
  42. int val;
  43. struct semid_ds *buf;
  44. unsigned short *array;
  45. } arg;
  46. .fi
  47. .P
  48. .RE
  49. .P
  50. Each operation shall be performed atomically.
  51. .P
  52. The following semaphore control operations as specified by
  53. .IR cmd
  54. are executed with respect to the semaphore specified by
  55. .IR semid
  56. and
  57. .IR semnum .
  58. The level of permission required for each operation is shown with each
  59. command; see
  60. .IR "Section 2.7" ", " "XSI Interprocess Communication".
  61. The symbolic names for the values of
  62. .IR cmd
  63. are defined in the
  64. .IR <sys/sem.h>
  65. header:
  66. .IP GETVAL 12
  67. Return the value of
  68. .IR semval ;
  69. see
  70. .IR <sys/sem.h> .
  71. Requires read permission.
  72. .IP SETVAL 12
  73. Set the value of
  74. .IR semval
  75. to
  76. .IR arg.val ,
  77. where
  78. .IR arg
  79. is the value of the fourth argument to
  80. \fIsemctl\fR().
  81. When this command is successfully executed, the
  82. .IR semadj
  83. value corresponding to the specified semaphore in all processes is
  84. cleared. Also, the
  85. .IR sem_ctime
  86. timestamp shall be set to the current time, as described in
  87. .IR "Section 2.7.1" ", " "IPC General Description".
  88. Requires alter permission; see
  89. .IR "Section 2.7" ", " "XSI Interprocess Communication".
  90. .IP GETPID 12
  91. Return the value of
  92. .IR sempid .
  93. Requires read permission.
  94. .IP GETNCNT 12
  95. Return the value of
  96. .IR semncnt .
  97. Requires read permission.
  98. .IP GETZCNT 12
  99. Return the value of
  100. .IR semzcnt .
  101. Requires read permission.
  102. .P
  103. The following values of
  104. .IR cmd
  105. operate on each
  106. .IR semval
  107. in the set of semaphores:
  108. .IP GETALL 12
  109. Return the value of
  110. .IR semval
  111. for each semaphore in the semaphore set and place into the array
  112. pointed to by
  113. .IR arg.array ,
  114. where
  115. .IR arg
  116. is the fourth argument to
  117. \fIsemctl\fR().
  118. Requires read permission.
  119. .IP SETALL 12
  120. Set the value of
  121. .IR semval
  122. for each semaphore in the semaphore set according to the array pointed
  123. to by
  124. .IR arg.array ,
  125. where
  126. .IR arg
  127. is the fourth argument to
  128. \fIsemctl\fR().
  129. When this command is successfully executed, the
  130. .IR semadj
  131. values corresponding to each specified semaphore in all processes are
  132. cleared. Also, the
  133. .IR sem_ctime
  134. timestamp shall be set to the current time, as described in
  135. .IR "Section 2.7.1" ", " "IPC General Description".
  136. Requires alter permission.
  137. .br
  138. .P
  139. The following values of
  140. .IR cmd
  141. are also available:
  142. .IP IPC_STAT 12
  143. Place the current value of each member of the
  144. .BR semid_ds
  145. data structure associated with
  146. .IR semid
  147. into the structure pointed to by
  148. .IR arg.buf ,
  149. where
  150. .IR arg
  151. is the fourth argument to
  152. \fIsemctl\fR().
  153. The contents of this structure are defined in
  154. .IR <sys/sem.h> .
  155. Requires read permission.
  156. .IP IPC_SET 12
  157. Set the value of the following members of the
  158. .BR semid_ds
  159. data structure associated with
  160. .IR semid
  161. to the corresponding value found in the structure pointed to by
  162. .IR arg.buf ,
  163. where
  164. .IR arg
  165. is the fourth argument to
  166. \fIsemctl\fR():
  167. .RS 12
  168. .sp
  169. .RS 4
  170. .nf
  171. sem_perm.uid
  172. sem_perm.gid
  173. sem_perm.mode
  174. .fi
  175. .P
  176. .RE
  177. .P
  178. The mode bits specified in
  179. .IR "Section 2.7.1" ", " "IPC General Description"
  180. are copied into the corresponding bits of the
  181. .IR sem_perm.mode
  182. associated with
  183. .IR semid .
  184. The stored values of any other bits are unspecified. The
  185. .IR sem_ctime
  186. timestamp shall be set to the current time, as described in
  187. .IR "Section 2.7.1" ", " "IPC General Description".
  188. .P
  189. This command can only be executed by a process that has an effective
  190. user ID equal to either that of a process with appropriate privileges
  191. or to the value of
  192. .IR sem_perm.cuid
  193. or
  194. .IR sem_perm.uid
  195. in the
  196. .BR semid_ds
  197. data structure associated with
  198. .IR semid .
  199. .RE
  200. .IP IPC_RMID 12
  201. Remove the semaphore identifier specified by
  202. .IR semid
  203. from the system and destroy the set of semaphores and
  204. .BR semid_ds
  205. data structure associated with it. This command can only be executed
  206. by a process that has an effective user ID equal to either that of a
  207. process with appropriate privileges or to the value of
  208. .IR sem_perm.cuid
  209. or
  210. .IR sem_perm.uid
  211. in the
  212. .BR semid_ds
  213. data structure associated with
  214. .IR semid .
  215. .SH "RETURN VALUE"
  216. If successful, the value returned by
  217. \fIsemctl\fR()
  218. depends on
  219. .IR cmd
  220. as follows:
  221. .IP GETVAL 12
  222. The value of
  223. .IR semval .
  224. .IP GETPID 12
  225. The value of
  226. .IR sempid .
  227. .IP GETNCNT 12
  228. The value of
  229. .IR semncnt .
  230. .IP GETZCNT 12
  231. The value of
  232. .IR semzcnt .
  233. .IP "All others" 12
  234. 0.
  235. .P
  236. Otherwise,
  237. \fIsemctl\fR()
  238. shall return \-1 and set
  239. .IR errno
  240. to indicate the error.
  241. .SH ERRORS
  242. The
  243. \fIsemctl\fR()
  244. function shall fail if:
  245. .TP
  246. .BR EACCES
  247. Operation permission is denied to the calling process; see
  248. .IR "Section 2.7" ", " "XSI Interprocess Communication".
  249. .TP
  250. .BR EINVAL
  251. The value of
  252. .IR semid
  253. is not a valid semaphore identifier, or the value of
  254. .IR semnum
  255. is less than 0 or greater than or equal to
  256. .IR sem_nsems ,
  257. or the value of
  258. .IR cmd
  259. is not a valid command.
  260. .TP
  261. .BR EPERM
  262. The argument
  263. .IR cmd
  264. is equal to IPC_RMID or IPC_SET
  265. and the effective user ID of the calling process is not equal to that
  266. of a process with appropriate privileges and it is not equal to the
  267. value of
  268. .IR sem_perm.cuid
  269. or
  270. .IR sem_perm.uid
  271. in the data structure associated with
  272. .IR semid .
  273. .TP
  274. .BR ERANGE
  275. The argument
  276. .IR cmd
  277. is equal to SETVAL or SETALL and the value to which
  278. .IR semval
  279. is to be set is greater than the system-imposed maximum.
  280. .LP
  281. .IR "The following sections are informative."
  282. .SH EXAMPLES
  283. Refer to
  284. .IR "\fIsemop\fR\^(\|)".
  285. .SH "APPLICATION USAGE"
  286. The fourth parameter in the SYNOPSIS section is now specified as
  287. .BR \(dq...\(dq
  288. in order to avoid a clash with the ISO\ C standard when referring to the union
  289. .IR semun
  290. (as defined in Issue 3) and for backwards-compatibility.
  291. .P
  292. The POSIX Realtime Extension defines alternative interfaces for interprocess
  293. communication. Application developers who need to use IPC should
  294. design their applications so that modules using the IPC routines
  295. described in
  296. .IR "Section 2.7" ", " "XSI Interprocess Communication"
  297. can be easily modified to use the alternative interfaces.
  298. .SH RATIONALE
  299. None.
  300. .SH "FUTURE DIRECTIONS"
  301. None.
  302. .SH "SEE ALSO"
  303. .ad l
  304. .IR "Section 2.7" ", " "XSI Interprocess Communication",
  305. .IR "Section 2.8" ", " "Realtime",
  306. .IR "\fIsemget\fR\^(\|)",
  307. .IR "\fIsemop\fR\^(\|)",
  308. .IR "\fIsem_close\fR\^(\|)",
  309. .IR "\fIsem_destroy\fR\^(\|)",
  310. .IR "\fIsem_getvalue\fR\^(\|)",
  311. .IR "\fIsem_init\fR\^(\|)",
  312. .IR "\fIsem_open\fR\^(\|)",
  313. .IR "\fIsem_post\fR\^(\|)",
  314. .IR "\fIsem_trywait\fR\^(\|)",
  315. .IR "\fIsem_unlink\fR\^(\|)"
  316. .ad b
  317. .P
  318. The Base Definitions volume of POSIX.1\(hy2017,
  319. .IR "Section 4.17" ", " "Semaphore",
  320. .IR "\fB<sys_sem.h>\fP"
  321. .\"
  322. .SH COPYRIGHT
  323. Portions of this text are reprinted and reproduced in electronic form
  324. from IEEE Std 1003.1-2017, Standard for Information Technology
  325. -- Portable Operating System Interface (POSIX), The Open Group Base
  326. Specifications Issue 7, 2018 Edition,
  327. Copyright (C) 2018 by the Institute of
  328. Electrical and Electronics Engineers, Inc and The Open Group.
  329. In the event of any discrepancy between this version and the original IEEE and
  330. The Open Group Standard, the original IEEE and The Open Group Standard
  331. is the referee document. The original Standard can be obtained online at
  332. http://www.opengroup.org/unix/online.html .
  333. .PP
  334. Any typographical or formatting errors that appear
  335. in this page are most likely
  336. to have been introduced during the conversion of the source files to
  337. man page format. To report such errors, see
  338. https://www.kernel.org/doc/man-pages/reporting_bugs.html .