.TH GETFLAGS 8
.SH NAME
getflags, usage \- command-line parsing for shell scripts
.SH SYNOPSIS
.B aux/getflags $*
.PP
.B aux/usage
.SH DESCRIPTION
.I Getflags
parses the options in its command-line arguments
according to the environment variable
.BR $flagfmt .
This variable should be a list of comma-separated options.
Each option can be a single letter, indicating that it does
not take arguments, or a letter followed by the space-separated
names of its arguments.
.I Getflags 
prints an 
.IR rc (1)
script on standard output which initializes the
environment variable
.BI $flag x
for every option mentioned in 
.BR $flagfmt .
If the option is not present on the command-line, the script
sets that option's flag variable to an empty list.
Otherwise, the script sets that option's flag variable with
a list containing the option's arguments or, 
if the option takes no arguments,
with the string
.BR 1 .
The script also sets the variable
.B $*
to the list of arguments following the options.
The final line in the script sets the
.B $status
variable, to the empty string on success
and to the string
.B usage
when there is an error parsing the command line.
.PP
Additionally,
.I getflags
collects arguments according to the environment variable
.BR $ptflagfmt .
This variable has the same format as
.BR $flagfmt .
.I Getflags
adds to the output script a line setting
.B $ptflag
to the list collected arguments.
.PP
.I Usage
prints a usage message to standard error.
It creates the message using
.BR $flagfmt ,
as described above,
.BR $args ,
which should contain the string to be printed explaining
non-option arguments,
and
.BR $0 ,
the program name
(see
.IR rc (1)).
.SH EXAMPLE
Parse the arguments for
.IR leak (1):
.IP
.EX
flagfmt='b,s,f binary,r res,x width'
args='name | pid list'
if(! ifs=() eval `{aux/getflags $*} || ~ $#* 0){
	aux/usage
	exit usage
}
.EE
.SH SOURCE
.B /sys/src/cmd/aux/getflags.c
.br
.B /sys/src/cmd/aux/usage.c
.SH SEE ALSO
.IR arg (2)
