aboutsummaryrefslogtreecommitdiff
path: root/man/man8/getflags.8
blob: 776a17aa218db25111fc52976e9d11beea065b59 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
.TH GETFLAGS 8
.SH NAME
getflags, usage \- command-line parsing for shell scripts
.SH SYNOPSIS
.B getflags $*
.PP
.B usage [ progname ]
.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 
.MR 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
.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
.MR rc (1) ).
If run under 
.MR sh (1) ,
which does not set
.BR $0 ,
the program name must be given explicitly on the command line.
.SH EXAMPLE
Parse the arguments for Plan 9's
.MR leak (1) :
.IP
.EX
flagfmt='b,s,f binary,r res,x width'
args='name | pid list'
if(! ifs=() eval `{getflags $*} || ~ $#* 0){
	usage
	exit usage
}
.EE
.SH SOURCE
.B \*9/src/cmd/getflags.c
.br
.B \*9/src/cmd/usage.c
.SH SEE ALSO
.MR arg (3)