1 .TH "sema" 1 "6 March 2016" "Mark Wooding" "Toys"
3 sema \- operations on (SysV-style) semaphores
55 program performs simple operations
56 on (System V-style) semaphores.
57 It's not intended to be a utility for
58 general-purpose hacking on
60 but rather a tool for doing synchronization
61 between shell scripts or other simple programs.
62 The two biggest limitations of
64 are that it only ever acts on the first semaphore of a set,
65 and it has no way to change the project-id
69 Semaphores are identified by a
71 Currently, this is always a pathname,
72 though additional ways of designating semaphore sets
73 may be added in later versions,
74 so an open-ended syntax is used:
92 is a pathname to a file in the filesystem.
93 The file's inode number and other information
94 are converted to an IPC key using
96 which is used to fetch a semaphore id using
101 may be omitted if it is
111 most plain pathnames can be used directly.
113 The command-line options accepted before the subcommand name
117 Write a help message to standard output
118 and exit successfully.
120 .B "\-v, \-\-version"
121 Write a version number to standard output
122 and exit successfully.
124 .BI "\-w, \-\-wait " duration
125 Nearly all operations on SysV semaphores may need to block
126 for an extended period of time.
127 This is obvious for waiting, but, alas,
128 semaphore initialization is poorly designed,
131 operation which expects a properly initialized semaphore
132 has little choice but to wait until the semaphore has been set up.
141 will wait indefinitely until the thing it's waiting for happens.
150 will exit immediately,
157 (possibly fractional \(en i.e., with a decimal point)
158 number followed by an optional unit suffix:
160 for seconds (the default),
171 The semaphore did not become available
176 The semaphore was not properly initialized
181 An error was detected in
183 command-line arguments.
185 A system error occurred.
187 Exit status from the program executed by the
194 it writes a human-readable description of the problem
195 to standard error and exits with one of the above status codes.
196 The codes have been chosen so as not to conflict
197 with those commonly used by other programs,
200 itself can be distinguished from problems encountered
201 by the program executed by the
204 but the available space for error codes is small
205 and conflicts are inevitable.
209 Create the file designated by the semaphore
212 (An error is reported if the
214 does not designate a pathname.)
216 Options are as follows.
218 .BI "\-m, \-\-mode " mode
219 Set the permissions for the new file.
222 should be a numeric file permission specification, in octal,
225 The default is to allow read and write according to the process umask.
227 .B "\-x, \-\-exclusive"
228 Fail if the file already exists.
230 Create a new semaphore set containing a single semaphore
235 Options are as follows.
237 .BI "\-m, \-\-mode " mode
238 Set the permissions for the new file.
241 should be a numeric file permission specification, in octal;
242 the read and write bits determine whether the owner, group and others
243 can read and change the semaphore;
244 the execute bits are ignored.
245 The default is to allow read and write according to the process umask.
247 .B "\-x, \-\-exclusive"
248 Fail if a semaphore set with the given
252 Delete the semaphore set with the given
255 Options are as follows.
258 Don't report an error if no semaphore set exists with the given name.
260 Fetch the current value of the semaphore with the given
263 write it, in decimal, to standard outout, followed by a newline.
265 Because this captures a snapshot of the state
266 of an asynchronously changing value,
267 this command is only really useful for diagnostic purposes
268 or when the system is known to be quiescent.
270 There are no options.
272 Set the value of the semaphore with the given
277 Because this modifies a the state
278 of an asynchronously changing value,
279 this command is only really useful
280 when the system is known to be quiescent.
282 There are no options.
284 Atomically increment the value of the semaphore with the given
286 This operation can't block
287 (though it may still be necessary to wait
288 until the semaphore set is initialized).
290 Options are as follows.
292 .BI "\-n, \-\-count " count
293 Adjust the semaphore value by
295 which must be a positive integer,
298 Wait until the value of the semaphore with the given
300 is positive and then atomically decrement it.
307 then execute it and then increment the semaphore value again
309 The program is executed directly by
311 Restoring the semaphore value is reliable:
312 it is done by the kernel,
313 so there's no risk of some program crashing and
314 leaving the semaphore in an inconsistent state;
315 though obviously if the program gets stuck
316 it will continue to hold the semaphore until it's killed.
317 The semaphore is released as soon as the
320 if it forked child processed,
321 the semaphore will be released
322 and the children will continue to run.
324 Options are as follows.
326 .BI "\-n, \-\-count " count
327 Adjust the semaphore value by
329 which must be a positive integer,
332 will wait until semaphore value is at least
334 and atomically decrease it by
340 arranges for the semaphore value to be increased by
345 System V semaphores are remarkably awful.
346 POSIX semaphores are superficially much better,
347 but actually deficient in a number of ways.
348 Most significantly for our purposes,
349 there's no analogue of the
352 so to implement the feature of
354 which holds the semaphore during the execution of a command
356 would have to wait for it to finish;
359 is killed in the meantime then nobody will fix the semaphore.
360 Another important deficiency is that
361 POSIX semaphores can only be adjusted a single step at a time,
368 commands can't be implemented satisfactorily.
370 Mark Wooding, <mdw@distorted.org.uk>