X-Git-Url: https://git.distorted.org.uk/~mdw/misc/blobdiff_plain/0f581568f662310ff4a32e3d43016fff268d10bd..300a556d392d9bd6ac5b98c1b4b2d0a052459053:/sema.1 diff --git a/sema.1 b/sema.1 new file mode 100644 index 0000000..3c81b23 --- /dev/null +++ b/sema.1 @@ -0,0 +1,370 @@ +.TH "sema" 1 "6 March 2016" "Mark Wooding" "Toys" +.SH NAME +sema \- operations on (SysV-style) semaphores +. +.SH SYNOPSIS +.B sema +.RB [ \-w +.IR when ] +.I subcmd +.RI [ args ...] +.PP +Subcommands: +'RS +.br +.B mkfile +.RB [ \-x ] +.RB [ \-m +.IR mode ] +.I name +.br +.B new +.RB [ \-x ] +.RB [ \-m +.IR mode ] +.I name +.I value +.br +.B rm +.RB [ \-f ] +.I name +.br +.B get +.I name +.br +.B set +.I name +.I value +.br +.B post +.RB [ \-n +.IR count ] +.I name +.br +.B wait +.RB [ \-n +.IR count ] +.I name +.RI [ cmd +.IR args ...] +.RE +. +.SH DESCRIPTION +The +.B sema +program performs simple operations +on (System V-style) semaphores. +It's not intended to be a utility for +general-purpose hacking on +existing semaphores, +but rather a tool for doing synchronization +between shell scripts or other simple programs. +The two biggest limitations of +.B sema +are that it only ever acts on the first semaphore of a set, +and it has no way to change the project-id +(see +.BR ftok (3)). +.SS Common features +Semaphores are identified by a +.IR name . +Currently, this is always a pathname, +though additional ways of designating semaphore sets +may be added in later versions, +so an open-ended syntax is used: +a +.I name +has the form +.IP +.RI [ type \c +.BR : ] \c +.I value +.PP +Currently defined +.IR type s +and the required +.IR value s +are as follows. +.TP +.B file +The +.I value +is a pathname to a file in the filesystem. +The file's inode number and other information +are converted to an IPC key using +.BR ftok (3) +which is used to fetch a semaphore id using +.BR semget (2). +.PP +The +.I type +may be omitted if it is +.B file +and the +.I value +does not contain a +.RB ` : ' +before its first +.RB ` / ' +(if any); +as a result, +most plain pathnames can be used directly. +.PP +The command-line options accepted before the subcommand name +are as follows. +.TP +.B "\-h, \-\-help" +Write a help message to standard output +and exit successfully. +.TP +.B "\-v, \-\-version" +Write a version number to standard output +and exit successfully. +.TP +.BI "\-w, \-\-wait " duration +Nearly all operations on SysV semaphores may need to block +for an extended period of time. +This is obvious for waiting, but, alas, +semaphore initialization is poorly designed, +and +.I every +operation which expects a properly initialized semaphore +has little choice but to wait until the semaphore has been set up. +.IP +If +.I duration +is +.B forever +(the default) +then +.B sema +will wait indefinitely until the thing it's waiting for happens. +If +.I duration +is +.B none +or +.B never +then +.B sema +will exit immediately, +with status 251, +instead of waiting. +Otherwise, +.I +duration +should be a +(possibly fractional \(en i.e., with a decimal point) +number followed by an optional unit suffix: +.RB ` s ' +for seconds (the default), +.RB ` m ' +for minutes, +.RB ` h ' +for hours, and +.RB ` d ' +for days. +.SS Exit status +.IP 0 +Success. +.IP 251 +The semaphore did not become available +within the period +.B sema +was told to wait. +.IP 252 +The semaphore was not properly initialized +within the period +.B sema +was told to wait. +.IP 253 +An error was detected in +.BR sema 's +command-line arguments. +.IP 254 +A system error occurred. +.IP Other +Exit status from the program executed by the +.B wait +subcommand. +.PP +If +.B sema +detects an error, +it writes a human-readable description of the problem +to standard error and exits with one of the above status codes. +The codes have been chosen so as not to conflict +with those commonly used by other programs, +so that errors from +.B sema +itself can be distinguished from problems encountered +by the program executed by the +.B wait +subcommand, +but the available space for error codes is small +and conflicts are inevitable. +. +.SH SUBCOMMANDS +.SS mkfile +Create the file designated by the semaphore +.I name +argument. +(An error is reported if the +.I name +does not designate a pathname.) +.PP +Options are as follows. +.TP +.BI "\-m, \-\-mode " mode +Set the permissions for the new file. +The +.I mode +should be a numeric file permission specification, in octal, +as for +.BR chmod (1). +The default is to allow read and write according to the process umask. +.TP +.B "\-x, \-\-exclusive" +Fail if the file already exists. +.SS new +Create a new semaphore set containing a single semaphore +with the given +.I name +and initial +.IR value . +Options are as follows. +.TP +.BI "\-m, \-\-mode " mode +Set the permissions for the new file. +The +.I mode +should be a numeric file permission specification, in octal; +the read and write bits determine whether the owner, group and others +can read and change the semaphore; +the execute bits are ignored. +The default is to allow read and write according to the process umask. +.TP +.B "\-x, \-\-exclusive" +Fail if a semaphore set with the given +.I name +already exists. +.SS rm +Delete the semaphore set with the given +.IR name . +.PP +Options are as follows. +.TP +.B "\-f, \-\-force" +Don't report an error if no semaphore set exists with the given name. +.SS get +Fetch the current value of the semaphore with the given +.I name +and +write it, in decimal, to standard outout, followed by a newline. +.PP +Because this captures a snapshot of the state +of an asynchronously changing value, +this command is only really useful for diagnostic purposes +or when the system is known to be quiescent. +.PP +There are no options. +.SS set +Set the value of the semaphore with the given +.I name +to +.IR value . +.PP +Because this modifies a the state +of an asynchronously changing value, +this command is only really useful +when the system is known to be quiescent. +.PP +There are no options. +.SS post +Atomically increment the value of the semaphore with the given +.IR name . +This operation can't block +(though it may still be necessary to wait +until the semaphore set is initialized). +.PP +Options are as follows. +.TP +.BI "\-n, \-\-count " count +Adjust the semaphore value by +.IR count , +which must be a positive integer, +rather than 1. +.SS wait +Wait until the value of the semaphore with the given +.I name +is positive and then atomically decrement it. +.PP +If a +.I command +is provided +(possibly with some +.IR arguments ) +then execute it and then increment the semaphore value again +when it finishes. +The program is executed directly by +.BR execvp (3). +Restoring the semaphore value is reliable: +it is done by the kernel, +so there's no risk of some program crashing and +leaving the semaphore in an inconsistent state; +though obviously if the program gets stuck +it will continue to hold the semaphore until it's killed. +The semaphore is released as soon as the +.I command +exits; +if it forked child processed, +the semaphore will be released +and the children will continue to run. +.PP +Options are as follows. +.TP +.BI "\-n, \-\-count " count +Adjust the semaphore value by +.IR count , +which must be a positive integer, +rather than 1. +.B sema +will wait until semaphore value is at least +.IR count , +and atomically decrease it by +.IR count . +If there is a +.I command +then +.B sema +arranges for the semaphore value to be increased by +.I count +when it exits. +. +.SH BUGS +System V semaphores are remarkably awful. +POSIX semaphores are superficially much better, +but actually deficient in a number of ways. +Most significantly for our purposes, +there's no analogue of the +.B SEM_UNDO +feature, +so to implement the feature of +.B wait +which holds the semaphore during the execution of a command +.B sema +would have to wait for it to finish; +and if +.B sema +is killed in the meantime then nobody will fix the semaphore. +Another important deficiency is that +POSIX semaphores can only be adjusted a single step at a time, +so the +.B \-n +feature of the +.B wait +and +.B post +commands can't be implemented satisfactorily. +.SH AUTHOR +Mark Wooding,