Commit | Line | Data |
---|---|---|
53e9b2ee KM |
1 | .\" Copyright (c) 1985 Regents of the University of California. |
2 | .\" All rights reserved. The Berkeley software License Agreement | |
3 | .\" specifies the terms and conditions for redistribution. | |
4 | .\" | |
5 | .\" @(#)getopt.3 6.1 (Berkeley) %G% | |
6 | .\" | |
7 | .TH GETOPT 3 "" | |
8 | .UC 6 | |
9 | .SH NAME | |
10 | getopt \- get option letter from argv | |
11 | .SH SYNOPSIS | |
12 | .ft B | |
13 | int getopt(argc, argv, optstring) | |
14 | .br | |
15 | int argc; | |
16 | .br | |
17 | char **argv; | |
18 | .br | |
19 | char *optstring; | |
20 | .sp | |
21 | extern char *optarg; | |
22 | .br | |
23 | extern int optind; | |
24 | .ft | |
25 | .SH DESCRIPTION | |
26 | .I Getopt | |
27 | returns the next option letter in | |
28 | .I argv | |
29 | that matches a letter in | |
30 | .IR optstring . | |
31 | .I Optstring | |
32 | is a string of recognized option letters; | |
33 | if a letter is followed by a colon, the option is expected to have | |
34 | an argument that may or may not be separated from it by white space. | |
35 | .I Optarg | |
36 | is set to point to the start of the option argument on return from | |
37 | .IR getopt . | |
38 | .PP | |
39 | .I Getopt | |
40 | places in | |
41 | .I optind | |
42 | the | |
43 | .I argv | |
44 | index of the next argument to be processed. | |
45 | Because | |
46 | .I optind | |
47 | is external, it is normally initialized to zero automatically | |
48 | before the first call to | |
49 | .IR getopt . | |
50 | .PP | |
51 | When all options have been processed (i.e., up to the first | |
52 | non-option argument), | |
53 | .I getopt | |
54 | returns | |
55 | .BR EOF . | |
56 | The special option | |
57 | .B \-\- | |
58 | may be used to delimit the end of the options; | |
59 | .B EOF | |
60 | will be returned, and | |
61 | .B \-\- | |
62 | will be skipped. | |
63 | .SH SEE ALSO | |
64 | getopt(1) | |
65 | .SH DIAGNOSTICS | |
66 | .I Getopt | |
67 | prints an error message on | |
68 | .I stderr | |
69 | and returns a question mark | |
70 | .RB ( ? ) | |
71 | when it encounters an option letter not included in | |
72 | .IR optstring . | |
73 | .SH EXAMPLE | |
74 | The following code fragment shows how one might process the arguments | |
75 | for a command that can take the mutually exclusive options | |
76 | .B a | |
77 | and | |
78 | .BR b , | |
79 | and the options | |
80 | .B f | |
81 | and | |
82 | .BR o , | |
83 | both of which require arguments: | |
84 | .PP | |
85 | .RS | |
86 | .nf | |
87 | main(argc, argv) | |
88 | int argc; | |
89 | char **argv; | |
90 | { | |
91 | int c; | |
92 | extern int optind; | |
93 | extern char *optarg; | |
94 | \&. | |
95 | \&. | |
96 | \&. | |
97 | while ((c = getopt(argc, argv, "abf:o:")) != EOF) | |
98 | switch (c) { | |
99 | case 'a': | |
100 | if (bflg) | |
101 | errflg++; | |
102 | else | |
103 | aflg++; | |
104 | break; | |
105 | case 'b': | |
106 | if (aflg) | |
107 | errflg++; | |
108 | else | |
109 | bproc(); | |
110 | break; | |
111 | case 'f': | |
112 | ifile = optarg; | |
113 | break; | |
114 | case 'o': | |
115 | ofile = optarg; | |
116 | break; | |
117 | case '?': | |
118 | default: | |
119 | errflg++; | |
120 | break; | |
121 | } | |
122 | if (errflg) { | |
123 | fprintf(stderr, "Usage: ..."); | |
124 | exit(2); | |
125 | } | |
126 | for (; optind < argc; optind++) { | |
127 | \&. | |
128 | \&. | |
129 | \&. | |
130 | } | |
131 | \&. | |
132 | \&. | |
133 | \&. | |
134 | } | |
135 | .RE | |
136 | .PP | |
137 | A template similar to this can be found in | |
138 | .IR /usr/pub/template.c . | |
139 | .SH HISTORY | |
140 | Written by Henry Spencer, working from a Bell Labs manual page. | |
141 | Behavior believed identical to the Bell version. | |
142 | Modified by Keith Bostic to behave closer to the System V version. | |
143 | .SH BUGS | |
144 | It is not obvious how | |
145 | `\-' | |
146 | standing alone should be treated; this version treats it as | |
147 | a non-option argument, which is not always right. | |
148 | .PP | |
149 | Option arguments are allowed to begin with `\-'; | |
150 | this is reasonable but reduces the amount of error checking possible. | |
151 | .PP | |
152 | .I Getopt | |
153 | is quite flexible but the obvious price must be paid: there is much | |
154 | it could do that it doesn't, like | |
155 | checking mutually exclusive options, checking type of | |
156 | option arguments, etc. |