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

semop.3p (12490B)


  1. '\" et
  2. .TH SEMOP "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. semop
  12. \(em XSI semaphore operations
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <sys/sem.h>
  17. .P
  18. int semop(int \fIsemid\fP, struct sembuf *\fIsops\fP, size_t \fInsops\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIsemop\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. \fIsemop\fR()
  31. function shall perform atomically a user-defined array of semaphore
  32. operations in array order on the set of semaphores associated with the
  33. semaphore identifier specified by the argument
  34. .IR semid .
  35. .P
  36. The argument
  37. .IR sops
  38. is a pointer to a user-defined array of semaphore operation
  39. structures. The implementation shall not modify elements of this array
  40. unless the application uses implementation-defined extensions.
  41. .P
  42. The argument
  43. .IR nsops
  44. is the number of such structures in the array.
  45. .P
  46. Each structure,
  47. .BR sembuf ,
  48. includes the following members:
  49. .TS
  50. center box tab(!);
  51. cB | cB | cB
  52. lw(1.25i)B | lw(1.25i)I | lw(2.5i).
  53. Member Type!Member Name!Description
  54. _
  55. unsigned short!sem_num!Semaphore number.
  56. short!sem_op!Semaphore operation.
  57. short!sem_flg!Operation flags.
  58. .TE
  59. .P
  60. Each semaphore operation specified by
  61. .IR sem_op
  62. is performed on the corresponding semaphore specified by
  63. .IR semid
  64. and
  65. .IR sem_num .
  66. .P
  67. The variable
  68. .IR sem_op
  69. specifies one of three semaphore operations:
  70. .IP " 1." 4
  71. If
  72. .IR sem_op
  73. is a negative integer and the calling process has alter permission, one
  74. of the following shall occur:
  75. .RS 4
  76. .IP " *" 4
  77. If
  78. .IR semval (see
  79. .IR <sys/sem.h> )
  80. is greater than or equal to the absolute value of
  81. .IR sem_op ,
  82. the absolute value of
  83. .IR sem_op
  84. is subtracted from
  85. .IR semval .
  86. Also, if (\fIsem_flg\fP &SEM_UNDO) is non-zero, the absolute value of
  87. .IR sem_op
  88. shall be added to the
  89. .IR semadj
  90. value of the calling process for the specified semaphore.
  91. .IP " *" 4
  92. If
  93. .IR semval
  94. is less than the absolute value of
  95. .IR sem_op
  96. and (\fIsem_flg\fP &IPC_NOWAIT) is non-zero,
  97. \fIsemop\fR()
  98. shall return immediately.
  99. .IP " *" 4
  100. If
  101. .IR semval
  102. is less than the absolute value of
  103. .IR sem_op
  104. and (\fIsem_flg\fP &IPC_NOWAIT) is 0,
  105. \fIsemop\fR()
  106. shall increment the
  107. .IR semncnt
  108. associated with the specified semaphore and suspend execution of the
  109. calling thread until one of the following conditions occurs:
  110. .RS 4
  111. .IP -- 4
  112. The value of
  113. .IR semval
  114. becomes greater than or equal to the absolute value of
  115. .IR sem_op .
  116. When this occurs, the value of
  117. .IR semncnt
  118. associated with the specified semaphore shall be decremented, the
  119. absolute value of
  120. .IR sem_op
  121. shall be subtracted from
  122. .IR semval
  123. and, if (\fIsem_flg\fP &SEM_UNDO) is non-zero, the absolute value of
  124. .IR sem_op
  125. shall be added to the
  126. .IR semadj
  127. value of the calling process for the specified semaphore.
  128. .IP -- 4
  129. The
  130. .IR semid
  131. for which the calling thread is awaiting action is removed from the
  132. system. When this occurs,
  133. .IR errno
  134. shall be set to
  135. .BR [EIDRM]
  136. and \-1 shall be returned.
  137. .IP -- 4
  138. The calling thread receives a signal that is to be caught. When this
  139. occurs, the value of
  140. .IR semncnt
  141. associated with the specified semaphore shall be decremented, and the
  142. calling thread shall resume execution in the manner prescribed in
  143. .IR "\fIsigaction\fR\^(\|)".
  144. .RE
  145. .RE
  146. .IP " 2." 4
  147. If
  148. .IR sem_op
  149. is a positive integer and the calling process has alter permission, the
  150. value of
  151. .IR sem_op
  152. shall be added to
  153. .IR semval
  154. and, if (\fIsem_flg\fP &SEM_UNDO) is non-zero, the value of
  155. .IR sem_op
  156. shall be subtracted from the
  157. .IR semadj
  158. value of the calling process for the specified semaphore.
  159. .IP " 3." 4
  160. If
  161. .IR sem_op
  162. is 0 and the calling process has read permission, one of the following
  163. shall occur:
  164. .RS 4
  165. .IP " *" 4
  166. If
  167. .IR semval
  168. is 0,
  169. \fIsemop\fR()
  170. shall return immediately.
  171. .IP " *" 4
  172. If
  173. .IR semval
  174. is non-zero and (\fIsem_flg\fP &IPC_NOWAIT) is non-zero,
  175. \fIsemop\fR()
  176. shall return immediately.
  177. .IP " *" 4
  178. If
  179. .IR semval
  180. is non-zero and (\fIsem_flg\fP &IPC_NOWAIT) is 0,
  181. \fIsemop\fR()
  182. shall increment the
  183. .IR semzcnt
  184. associated with the specified semaphore and suspend execution of the
  185. calling thread until one of the following occurs:
  186. .RS 4
  187. .IP -- 4
  188. The value of
  189. .IR semval
  190. becomes 0, at which time the value of
  191. .IR semzcnt
  192. associated with the specified semaphore shall be decremented.
  193. .IP -- 4
  194. The
  195. .IR semid
  196. for which the calling thread is awaiting action is removed from the
  197. system. When this occurs,
  198. .IR errno
  199. shall be set to
  200. .BR [EIDRM]
  201. and \-1 shall be returned.
  202. .IP -- 4
  203. The calling thread receives a signal that is to be caught. When this
  204. occurs, the value of
  205. .IR semzcnt
  206. associated with the specified semaphore shall be decremented, and the
  207. calling thread shall resume execution in the manner prescribed in
  208. .IR "\fIsigaction\fR\^(\|)".
  209. .RE
  210. .RE
  211. .P
  212. Upon successful completion, the value of
  213. .IR sempid
  214. for each semaphore specified in the array pointed to by
  215. .IR sops
  216. shall be set to the process ID of the calling process. Also, the
  217. .IR sem_otime
  218. timestamp shall be set to the current time, as described in
  219. .IR "Section 2.7.1" ", " "IPC General Description".
  220. .SH "RETURN VALUE"
  221. Upon successful completion,
  222. \fIsemop\fR()
  223. shall return 0; otherwise, it shall return \-1 and set
  224. .IR errno
  225. to indicate the error.
  226. .SH ERRORS
  227. The
  228. \fIsemop\fR()
  229. function shall fail if:
  230. .TP
  231. .BR E2BIG
  232. The value of
  233. .IR nsops
  234. is greater than the system-imposed maximum.
  235. .TP
  236. .BR EACCES
  237. Operation permission is denied to the calling process; see
  238. .IR "Section 2.7" ", " "XSI Interprocess Communication".
  239. .TP
  240. .BR EAGAIN
  241. The operation would result in suspension of the calling process but
  242. (\fIsem_flg\fP &IPC_NOWAIT) is non-zero.
  243. .TP
  244. .BR EFBIG
  245. The value of
  246. .IR sem_num
  247. is greater than or equal to the number of semaphores in the set
  248. associated with
  249. .IR semid .
  250. .TP
  251. .BR EIDRM
  252. The semaphore identifier
  253. .IR semid
  254. is removed from the system.
  255. .TP
  256. .BR EINTR
  257. The
  258. \fIsemop\fR()
  259. function was interrupted by a signal.
  260. .TP
  261. .BR EINVAL
  262. The value of
  263. .IR semid
  264. is not a valid semaphore identifier, or the number of individual
  265. semaphores for which the calling process requests a SEM_UNDO would
  266. exceed the system-imposed limit.
  267. .TP
  268. .BR ENOSPC
  269. The limit on the number of individual processes requesting a SEM_UNDO
  270. would be exceeded.
  271. .TP
  272. .BR ERANGE
  273. An operation would cause a
  274. .IR semval
  275. to overflow the system-imposed limit, or an operation would cause a
  276. .IR semadj
  277. value to overflow the system-imposed limit.
  278. .LP
  279. .IR "The following sections are informative."
  280. .SH EXAMPLES
  281. .SS "Setting Values in Semaphores"
  282. .P
  283. The following example sets the values of the two semaphores associated
  284. with the
  285. .IR semid
  286. identifier to the values contained in the
  287. .IR sb
  288. array.
  289. .sp
  290. .RS 4
  291. .nf
  292. #include <sys/sem.h>
  293. \&...
  294. int semid;
  295. struct sembuf sb[2];
  296. int nsops = 2;
  297. int result;
  298. .P
  299. /* Code to initialize semid. */
  300. \&...
  301. .P
  302. /* Adjust value of semaphore in the semaphore array semid. */
  303. sb[0].sem_num = 0;
  304. sb[0].sem_op = -1;
  305. sb[0].sem_flg = SEM_UNDO | IPC_NOWAIT;
  306. sb[1].sem_num = 1;
  307. sb[1].sem_op = 1;
  308. sb[1].sem_flg = 0;
  309. .P
  310. result = semop(semid, sb, nsops);
  311. .fi
  312. .P
  313. .RE
  314. .SS "Creating a Semaphore Identifier"
  315. .P
  316. The following example gets a unique semaphore key using the
  317. \fIftok\fR()
  318. function, then gets a semaphore ID associated with that key using the
  319. \fIsemget\fR()
  320. function (the first call also tests to make sure the semaphore exists).
  321. If the semaphore does not exist, the program creates it, as shown by
  322. the second call to
  323. \fIsemget\fR().
  324. In creating the semaphore for the queuing process, the program
  325. attempts to create one semaphore with read/write permission for all. It
  326. also uses the IPC_EXCL flag, which forces
  327. \fIsemget\fR()
  328. to fail if the semaphore already exists.
  329. .P
  330. After creating the semaphore, the program uses calls to
  331. \fIsemctl\fR()
  332. and
  333. \fIsemop\fR()
  334. to initialize it to the values in the
  335. .IR sbuf
  336. array. The number of processes that can execute concurrently without
  337. queuing is initially set to 2. The final call to
  338. \fIsemget\fR()
  339. creates a semaphore identifier that can be used later in the program.
  340. .P
  341. Processes that obtain
  342. .IR semid
  343. without creating it check that
  344. .IR sem_otime
  345. is non-zero, to ensure that the creating process has completed the
  346. \fIsemop\fR()
  347. initialization.
  348. .P
  349. The final call to
  350. \fIsemop\fR()
  351. acquires the semaphore and waits until it is free; the SEM_UNDO option
  352. releases the semaphore when the process exits, waiting until there are
  353. less than two processes running concurrently.
  354. .br
  355. .sp
  356. .RS 4
  357. .nf
  358. #include <stdio.h>
  359. #include <sys/sem.h>
  360. #include <sys/stat.h>
  361. #include <errno.h>
  362. #include <stdlib.h>
  363. \&...
  364. key_t semkey;
  365. int semid;
  366. struct sembuf sbuf;
  367. union semun {
  368. int val;
  369. struct semid_ds *buf;
  370. unsigned short *array;
  371. } arg;
  372. struct semid_ds ds;
  373. \&...
  374. /* Get unique key for semaphore. */
  375. if ((semkey = ftok("/tmp", \(aqa\(aq)) == (key_t) -1) {
  376. perror("IPC error: ftok"); exit(1);
  377. }
  378. .P
  379. /* Get semaphore ID associated with this key. */
  380. if ((semid = semget(semkey, 0, 0)) == -1) {
  381. .P
  382. /* Semaphore does not exist - Create. */
  383. if ((semid = semget(semkey, 1, IPC_CREAT | IPC_EXCL | S_IRUSR |
  384. S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH | S_IWOTH)) != -1)
  385. {
  386. /* Initialize the semaphore. */
  387. arg.val = 0;
  388. sbuf.sem_num = 0;
  389. sbuf.sem_op = 2; /* This is the number of runs without queuing. */
  390. sbuf.sem_flg = 0;
  391. if (semctl(semid, 0, SETVAL, arg) == -1
  392. || semop(semid, &sbuf, 1) == -1) {
  393. perror("IPC error: semop"); exit(1);
  394. }
  395. }
  396. else if (errno == EEXIST) {
  397. if ((semid = semget(semkey, 0, 0)) == -1) {
  398. perror("IPC error 1: semget"); exit(1);
  399. }
  400. goto check_init;
  401. }
  402. else {
  403. perror("IPC error 2: semget"); exit(1);
  404. }
  405. }
  406. else
  407. {
  408. /* Check that semid has completed initialization. */
  409. /* An application can use a retry loop at this point rather than
  410. exiting. */
  411. check_init:
  412. arg.buf = &ds;
  413. if (semctl(semid, 0, IPC_STAT, arg) < 0) {
  414. perror("IPC error 3: semctl"); exit(1);
  415. }
  416. if (ds.sem_otime == 0) {
  417. perror("IPC error 4: semctl"); exit(1);
  418. }
  419. }
  420. \&...
  421. sbuf.sem_num = 0;
  422. sbuf.sem_op = -1;
  423. sbuf.sem_flg = SEM_UNDO;
  424. if (semop(semid, &sbuf, 1) == -1) {
  425. perror("IPC Error: semop"); exit(1);
  426. }
  427. .fi
  428. .P
  429. .RE
  430. .SH "APPLICATION USAGE"
  431. The POSIX Realtime Extension defines alternative interfaces for interprocess
  432. communication. Application developers who need to use IPC should
  433. design their applications so that modules using the IPC routines
  434. described in
  435. .IR "Section 2.7" ", " "XSI Interprocess Communication"
  436. can be easily modified to use the alternative interfaces.
  437. .SH RATIONALE
  438. None.
  439. .SH "FUTURE DIRECTIONS"
  440. None.
  441. .SH "SEE ALSO"
  442. .IR "Section 2.7" ", " "XSI Interprocess Communication",
  443. .IR "Section 2.8" ", " "Realtime",
  444. .IR "\fIexec\fR\^",
  445. .IR "\fIexit\fR\^(\|)",
  446. .IR "\fIfork\fR\^(\|)",
  447. .IR "\fIsemctl\fR\^(\|)",
  448. .IR "\fIsemget\fR\^(\|)",
  449. .IR "\fIsem_close\fR\^(\|)",
  450. .IR "\fIsem_destroy\fR\^(\|)",
  451. .IR "\fIsem_getvalue\fR\^(\|)",
  452. .IR "\fIsem_init\fR\^(\|)",
  453. .IR "\fIsem_open\fR\^(\|)",
  454. .IR "\fIsem_post\fR\^(\|)",
  455. .IR "\fIsem_trywait\fR\^(\|)",
  456. .IR "\fIsem_unlink\fR\^(\|)"
  457. .P
  458. The Base Definitions volume of POSIX.1\(hy2017,
  459. .IR "Section 4.17" ", " "Semaphore",
  460. .IR "\fB<sys_ipc.h>\fP",
  461. .IR "\fB<sys_sem.h>\fP",
  462. .IR "\fB<sys_types.h>\fP"
  463. .\"
  464. .SH COPYRIGHT
  465. Portions of this text are reprinted and reproduced in electronic form
  466. from IEEE Std 1003.1-2017, Standard for Information Technology
  467. -- Portable Operating System Interface (POSIX), The Open Group Base
  468. Specifications Issue 7, 2018 Edition,
  469. Copyright (C) 2018 by the Institute of
  470. Electrical and Electronics Engineers, Inc and The Open Group.
  471. In the event of any discrepancy between this version and the original IEEE and
  472. The Open Group Standard, the original IEEE and The Open Group Standard
  473. is the referee document. The original Standard can be obtained online at
  474. http://www.opengroup.org/unix/online.html .
  475. .PP
  476. Any typographical or formatting errors that appear
  477. in this page are most likely
  478. to have been introduced during the conversion of the source files to
  479. man page format. To report such errors, see
  480. https://www.kernel.org/doc/man-pages/reporting_bugs.html .