1 .TH ARG 3
2 .SH NAME
3 ARGBEGIN, ARGEND, ARGC, ARGF, EARGF, arginit, argopt \- process option letters from argv
4 .SH SYNOPSIS
5 .B #include <u.h>
6 .br
7 .B #include <libc.h>
8 .PP
9 .nf
10 .B ARGBEGIN {
11 .B char *ARGF();
12 .B char *EARGF(code);
13 .B Rune ARGC();
14 .B } ARGEND
15 .PP
16 .B extern char *argv0;
17 .SH DESCRIPTION
18 These macros assume the names
19 .I argc
20 and
21 .I argv
22 are in scope; see
23 .MR exec (3) .
24 .I ARGBEGIN
25 and
26 .I ARGEND
27 surround code for processing program options.
28 The code
29 should be the cases of a C switch on
30 option characters;
31 it is executed once for each option character.
32 Options end after an argument 
33 .BR -- ,
34 before an argument
35 .BR - ,
36 or before an argument that doesn't begin with
37 .BR - .
38 .PP
39 The function macro
40 .I ARGC
41 returns the current option character, as an integer.
42 .PP
43 The function macro
44 .I ARGF
45 returns the current option argument:
46 a pointer to the rest of the option string if not empty,
47 or the next argument in
48 .I argv
49 if any, or 0.
50 .I ARGF
51 must be called just once for each option
52 that takes an argument.
53 The macro
54 .I EARGF
55 is like
56 .I ARGF
57 but instead of returning zero
58 runs
59 .I code
60 and, if that returns, calls
61 .MR abort (3) .
62 A typical value for
63 .I code
64 is 
65 .BR usage() ,
66 as in
67 .BR EARGF(usage()) .
68 .PP
69 After
70 .IR ARGBEGIN ,
71 .I argv0
72 is a copy of
73 .BR argv[0]
74 (conventionally the name of the program).
75 .PP
76 After
77 .IR ARGEND ,
78 .I argv
79 points at a zero-terminated list of the remaining
80 .I argc
81 arguments.
82 .SH EXAMPLE
83 This C program can take option
84 .B b
85 and option
86 .BR f ,
87 which requires an argument.
88 .IP
89 .EX
90 .ta \w'12345678'u +\w'12345678'u +\w'12345678'u +\w'12345678'u +\w'12345678'u
91 #include <u.h>
92 #include <libc.h>
93 void
94 main(int argc, char *argv[])
95 {
96 	char *f;
97 	print("%s", argv[0]);
98 	ARGBEGIN {
99 	case 'b':
100 		print(" -b");
101 		break;
102 	case 'f':
103 		print(" -f(%s)", (f=ARGF())? f: "no arg");
104 		break;
105 	default:
106 		print(" badflag('%c')", ARGC());
107 	} ARGEND
108 	print(" %d args:", argc);
109 	while(*argv)
110 		print(" '%s'", *argv++);
111 	print("\en");
112 	exits(nil);
113 }
114 .EE
115 .PP
116 Here is the output from running the command
117 .B
118 prog -bffile1 -r -f file2 arg1 arg2
119 .IP
120 .B
121 prog -b -f(file1) badflag('r') -f(file2) 2 args: 'arg1' 'arg2'
122 .PP
123 .SH SOURCE
124 .B \*9/include/libc.h