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