1 .TH GETFLAGS 8
2 .SH NAME
3 getflags, usage \- command-line parsing for shell scripts
4 .SH SYNOPSIS
5 .B getflags $*
6 .PP
7 .B usage [ progname ]
8 .SH DESCRIPTION
9 .I Getflags
10 parses the options in its command-line arguments
11 according to the environment variable
12 .BR $flagfmt .
13 This variable should be a list of comma-separated options.
14 Each option can be a single letter, indicating that it does
15 not take arguments, or a letter followed by the space-separated
16 names of its arguments.
17 .I Getflags 
18 prints an 
19 .MR rc (1)
20 script on standard output which initializes the
21 environment variable
22 .BI $flag x
23 for every option mentioned in 
24 .BR $flagfmt .
25 If the option is not present on the command-line, the script
26 sets that option's flag variable to an empty list.
27 Otherwise, the script sets that option's flag variable with
28 a list containing the option's arguments or, 
29 if the option takes no arguments,
30 with the string
31 .BR 1 .
32 The script also sets the variable
33 .B $*
34 to the list of arguments following the options.
35 The final line in the script sets the
36 .B $status
37 variable, to the empty string on success
38 and to the string
39 .B usage
40 when there is an error parsing the command line.
41 .PP
42 .I Usage
43 prints a usage message to standard error.
44 It creates the message using
45 .BR $flagfmt ,
46 as described above,
47 .BR $args ,
48 which should contain the string to be printed explaining
49 non-option arguments,
50 and
51 .BR $0 ,
52 the program name
53 (see
54 .MR rc (1) ).
55 If run under 
56 .MR sh (1) ,
57 which does not set
58 .BR $0 ,
59 the program name must be given explicitly on the command line.
60 .SH EXAMPLE
61 Parse the arguments for Plan 9's
62 .MR leak (1) :
63 .IP
64 .EX
65 flagfmt='b,s,f binary,r res,x width'
66 args='name | pid list'
67 if(! ifs=() eval `{getflags $*} || ~ $#* 0){
68 	usage
69 	exit usage
70 }
71 .EE
72 .SH SOURCE
73 .B \*9/src/cmd/getflags.c
74 .br
75 .B \*9/src/cmd/usage.c
76 .SH SEE ALSO
77 .MR arg (3)