debian/control: Include `prlimit' and `x86-model' in the metapackage.

[misc] / sema.1

.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, <mdw@distorted.org.uk>