Add copyright
[unix-history] / usr / src / lib / libc / stdlib / getopt.3
CommitLineData
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
10getopt \- get option letter from argv
11.SH SYNOPSIS
12.ft B
13int getopt(argc, argv, optstring)
14.br
15int argc;
16.br
17char **argv;
18.br
19char *optstring;
20.sp
21extern char *optarg;
22.br
23extern int optind;
24.ft
25.SH DESCRIPTION
26.I Getopt
27returns the next option letter in
28.I argv
29that matches a letter in
30.IR optstring .
31.I Optstring
32is a string of recognized option letters;
33if a letter is followed by a colon, the option is expected to have
34an argument that may or may not be separated from it by white space.
35.I Optarg
36is set to point to the start of the option argument on return from
37.IR getopt .
38.PP
39.I Getopt
40places in
41.I optind
42the
43.I argv
44index of the next argument to be processed.
45Because
46.I optind
47is external, it is normally initialized to zero automatically
48before the first call to
49.IR getopt .
50.PP
51When all options have been processed (i.e., up to the first
52non-option argument),
53.I getopt
54returns
55.BR EOF .
56The special option
57.B \-\-
58may be used to delimit the end of the options;
59.B EOF
60will be returned, and
61.B \-\-
62will be skipped.
63.SH SEE ALSO
64getopt(1)
65.SH DIAGNOSTICS
66.I Getopt
67prints an error message on
68.I stderr
69and returns a question mark
70.RB ( ? )
71when it encounters an option letter not included in
72.IR optstring .
73.SH EXAMPLE
74The following code fragment shows how one might process the arguments
75for a command that can take the mutually exclusive options
76.B a
77and
78.BR b ,
79and the options
80.B f
81and
82.BR o ,
83both of which require arguments:
84.PP
85.RS
86.nf
87main(argc, argv)
88int argc;
89char **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
137A template similar to this can be found in
138.IR /usr/pub/template.c .
139.SH HISTORY
140Written by Henry Spencer, working from a Bell Labs manual page.
141Behavior believed identical to the Bell version.
142Modified by Keith Bostic to behave closer to the System V version.
143.SH BUGS
144It is not obvious how
145`\-'
146standing alone should be treated; this version treats it as
147a non-option argument, which is not always right.
148.PP
149Option arguments are allowed to begin with `\-';
150this is reasonable but reduces the amount of error checking possible.
151.PP
152.I Getopt
153is quite flexible but the obvious price must be paid: there is much
154it could do that it doesn't, like
155checking mutually exclusive options, checking type of
156option arguments, etc.