1semop(2)                         System Calls                         semop(2)
2
3
4

NAME

6       semop, semtimedop - semaphore operations
7

SYNOPSIS

9       #include <sys/types.h>
10       #include <sys/ipc.h>
11       #include <sys/sem.h>
12
13       int semop(int semid, struct sembuf *sops, size_t nsops);
14
15
16       int semtimedop(int semid, struct sembuf *sops, size_t nsops,
17            const struct timespec *timeout);
18
19

DESCRIPTION

21       The  semop()  function  is used to perform atomically an array of sema‐
22       phore operations on the set of semaphores associated with the semaphore
23       identifier  specified  by  semid. The sops argument is a pointer to the
24       array of semaphore-operation structures. The nsops argument is the num‐
25       ber of such structures in the array.
26
27
28       Each sembuf structure contains the following members:
29
30         short     sem_num;    /* semaphore number */
31         short     sem_op;     /* semaphore operation */
32         short     sem_flg;    /* operation flags */
33
34
35
36       Each semaphore operation specified by sem_op is performed on the corre‐
37       sponding semaphore specified  by  semid  and  sem_num.  The  permission
38       required  for a semaphore operation is given as {token}, where token is
39       the type of permission needed.  The types of permission are interpreted
40       as follows:
41
42         00400    READ by user
43         00200    ALTER by user
44         00040    READ by group
45         00020    ALTER by group
46         00004    READ by others
47         00002    ALTER by others
48
49
50
51       See  the  Semaphore  Operation Permissions section of Intro(2) for more
52       information.
53
54
55       A process maintains a value, semadj, for each  semaphore  it  modifies.
56       This value contains the cumulative effect of operations the process has
57       performed on an individual semaphore with the  SEM_UNDO  flag  set  (so
58       that  they  can be undone if the process terminates unexpectedly).  The
59       value of semadj can affect the behavior of calls to  semop(),  semtime‐
60       dop(),  exit(),  and  _exit()  (the  latter two functions documented on
61       exit(2)), but is otherwise unobservable. See below for details.
62
63
64       The sem_op member specifies one of three semaphore operations:
65
66           1.     The sem_op member is a negative integer; {ALTER}
67
68               o      If semval (see Intro(2)) is greater than or equal to the
69                      absolute  value  of sem_op, the absolute value of sem_op
70                      is subtracted from semval. Also,  if  (sem_flg&SEM_UNDO)
71                      is  true,  the  absolute value of sem_op is added to the
72                      calling process's semadj value  (see  exit(2))  for  the
73                      specified semaphore.
74
75               o      If  semval is less than the absolute value of sem_op and
76                      (sem_flg&IPC_NOWAIT) is true,  semop()  returns  immedi‐
77                      ately.
78
79               o      If  semval is less than the absolute value of sem_op and
80                      (sem_flg&IPC_NOWAIT) is false,  semop()  increments  the
81                      semncnt associated with the specified semaphore and sus‐
82                      pends execution of the calling thread until one  of  the
83                      following conditions occur:
84
85                   o      The value of semval becomes greater than or equal to
86                          the absolute value of sem_op. When this occurs,  the
87                          value of semncnt associated with the specified sema‐
88                          phore is decremented, the absolute value  of  sem_op
89                          is subtracted from semval and, if (sem_flg&SEM_UNDO)
90                          is true, the absolute value of sem_op  is  added  to
91                          the calling process's semadj value for the specified
92                          semaphore.
93
94                   o      The semid for which the calling thread  is  awaiting
95                          action  is  removed from the system (see semctl(2)).
96                          When this occurs, errno is set to EIDRM  and  −1  is
97                          returned.
98
99                   o      The  calling  thread receives a signal that is to be
100                          caught. When this occurs, the value of semncnt asso‐
101                          ciated  with the specified semaphore is decremented,
102                          and the calling thread resumes execution in the man‐
103                          ner prescribed in sigaction(2).
104
105           2.     The sem_op member is a positive integer; {ALTER}
106
107                  The   value   of   sem_op   is   added  to  semval  and,  if
108                  (sem_flg&SEM_UNDO) is true, the  value  of  sem_op  is  sub‐
109                  tracted  from  the  calling  process's  semadj value for the
110                  specified semaphore.
111
112           3.     The sem_op member is 0; {READ}
113
114               o      If semval is 0, semop() returns immediately.
115
116               o      If semval is not equal to 0 and (sem_flg&IPC_NOWAIT)  is
117                      true, semop() returns immediately.
118
119               o      If  semval is not equal to 0 and (sem_flg&IPC_NOWAIT) is
120                      false, semop() increments the  semzcnt  associated  with
121                      the  specified  semaphore  and suspends execution of the
122                      calling thread until one of the following occurs:
123
124                   o      The value of semval becomes 0,  at  which  time  the
125                          value of semzcnt associated with the specified sema‐
126                          phore is set to 0 and all processes waiting on  sem‐
127                          val to become 0 are awakened.
128
129                   o      The  semid  for which the calling thread is awaiting
130                          action is removed from the system. When this occurs,
131                          errno is set to EIDRM and −1 is returned.
132
133                   o      The  calling  thread receives a signal that is to be
134                          caught. When this occurs, the value of semzcnt asso‐
135                          ciated  with the specified semaphore is decremented,
136                          and the calling thread resumes execution in the man‐
137                          ner prescribed in sigaction(2).
138
139
140       Upon  successful  completion,  the  value  of sempid for each semaphore
141       specified in the array pointed to by sops is set to the process  ID  of
142       the calling process.
143
144
145       The  semtimedop()  function behaves as semop() except when it must sus‐
146       pend execution of the calling process to complete  its  operation.   If
147       semtimedop()  must  suspend the calling process after the time interval
148       specified in timeout expires, or  if  the  timeout  expires  while  the
149       process  is suspended, semtimedop() returns with an error. If the time‐
150       spec structure pointed to by timeout is  zero-valued  and  semtimedop()
151       needs  to  suspend the calling process to complete the requested opera‐
152       tion(s), it returns immediately with an error. If timeout is  the  NULL
153       pointer, the behavior of semtimedop() is identical to that of semop().
154

RETURN VALUES

156       Upon  successful  completion,  0 is returned. Otherwise, −1 is returned
157       and errno is set to indicate the error.
158

ERRORS

160       The semop() and semtimedop() functions will fail if:
161
162       E2BIG     The nsops argument is greater than the  system-imposed  maxi‐
163                 mum. See NOTES.
164
165
166       EACCES    Operation  permission  is  denied to the calling process (see
167                 Intro(2)).
168
169
170       EAGAIN    The operation would  result  in  suspension  of  the  calling
171                 process but (sem_flg&IPC_NOWAIT) is true.
172
173
174       EFAULT    The sops argument points to an illegal address.
175
176
177       EFBIG     The  value of sem_num is less than 0 or greater than or equal
178                 to the number of semaphores in the set associated with semid.
179
180
181       EIDRM     A semid was removed from the system.
182
183
184       EINTR     A signal was received.
185
186
187       EINVAL    The semid argument is not a valid  semaphore  identifier,  or
188                 the  number  of  individual  semaphores for which the calling
189                 process requests a SEM_UNDO operation would exceed  the  sys‐
190                 tem-imposed  limit.  Solaris  does  not impose a limit on the
191                 number of individual semaphores for which the calling process
192                 requests a SEM_UNDO operation.
193
194
195       ENOSPC    The  limit on the number of individual processes requesting a
196                 SEM_UNDO operation would be exceeded. Solaris does not impose
197                 a  limit  on the number of individual processes requesting an
198                 SEM_UNDO operation.
199
200
201       ERANGE    An operation would cause a semval or a semadj value to  over‐
202                 flow the system-imposed limit.
203
204
205
206       The semtimedop() function will fail if:
207
208       EAGAIN    The  timeout  expired before the requested operation could be
209                 completed.
210
211
212
213       The semtimedop()  function  will  fail  if  one  of  the  following  is
214       detected:
215
216       EFAULT    The timeout argument points to an illegal address.
217
218
219       EINVAL    The timeout argument specified a tv_sec or tv_nsec value less
220                 than 0, or a tv_nsec value greater than or equal to 1000 mil‐
221                 lion.
222
223

ATTRIBUTES

225       See attributes(5) for descriptions of the following attributes:
226
227
228
229
230       ┌─────────────────────────────┬─────────────────────────────┐
231       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
232       ├─────────────────────────────┼─────────────────────────────┤
233       │Interface Stability          │semop() is Standard.         │
234       └─────────────────────────────┴─────────────────────────────┘
235

SEE ALSO

237       ipcs(1),  rctladm(1M),  Intro(2), exec(2), exit(2), fork(2), semctl(2),
238       semget(2), setrctl(2), sigaction(2), attributes(5), standards(5)
239

NOTES

241       The system-imposed maximum on nsops for a semaphore identifier  is  the
242       minimum  enforced  value of the process.max-sem-ops resource control of
243       the creating process at the time semget(2) was  used  to  allocate  the
244       identifier.
245
246
247       See  rctladm(1M)  and  setrctl(2)  for information about using resource
248       controls.
249
250
251
252SunOS 5.11                        12 May 2006                         semop(2)
Impressum