GETOPT(3) Library Routines GETOPT(3)
NAME
getopt - get option character from command line argument list
SYNOPSIS
#include <stdlib.h>
extern char *optarg;
extern int optind;
extern int optopt;
extern int opterr;
extern int optreset;
int getopt (int argc, char * const *argv, const char *optstring);
int getopt_restart (void);
DESCRIPTION
This manual page describes the BSD implementation of getopt.
The getopt function incrementally parses a command line argument list
argv and returns the next known option character. An option character
is known if it has been specified in the string of accepted option
characters, optstring.
The option string optstring may contain the following elements: indi‐
vidual characters, and characters followed by a colon to indicate an
option argument is to follow. For example, an option string x recog‐
nizes an option -x, and an option string x: recognizes an option and
argument -x argument. It does not matter to getopt if a following ar‐
gument has leading white space.
On return from getopt, optarg points to an option argument, if it is
anticipated, and the variable optind contains the index to the next
argv argument for a subsequent call to getopt. The variable optopt
saves the last known option character returned by getopt.
The variable opterr and optind are both initialized to 1. The optind
variable may be set to another value before a set of calls to getopt in
order to skip over more or less argv entries.
In order to use getopt to evaluate multiple sets of arguments, or to
evaluate a single set of arguments multiple times, the variable optre
set must be set to 1 before the second and each additional set of calls
to getopt, and the variable optind must be reinitialized.
The getopt function returns an EOF when the argument list is exhausted,
or a non-recognized option is encountered. The interpretation of op‐
tions in the argument list may be canceled by the option -- (double
dash) which causes getopt to signal the end of argument processing and
return an EOF. When all options have been processed (i.e., up to the
first non-option argument), getopt returns EOF.
The getopt_restart function sets optreset and optind to 1 and returns
zero. It is provided for backwards compatibility with older versions
of GNO, and should be avoided in new code.
DIAGNOSTICS
If the getopt function encounters a character not found in the string
optarg or detects a missing option argument it writes an error message
and returns ? to the stderr. Setting opterr to a zero will disable
these error messages. If optstring has a leading : then a missing op‐
tion argument causes a : to be returned in addition to suppressing any
error messages.
Option arguments are allowed to begin with -; this is reasonable but
reduces the amount of error checking possible.
EXTENSIONS
The optreset variable was added to make it possible to call the getopt
function multiple times. This is an extension to the POSIX 1003.2
specification.
The getopt_reset function is also an extension, but one that has been
deprecated.
LIMITATIONS
This implementation of getopt does not allow one to mix options and
non-option arguments; option processing will halt as soon as the first
non-option argument is found. The GNU implementation does not have
this limitation, but also cannot be restarted. The GNU implementation
also allows "long options", where the option name may be more than one
character.
See the GNO FAQ regarding availability of the GNU implementation of
getopt and getopt_long(3) for GNO.
EXAMPLE
extern char *optarg;
extern int optind;
int bflag, ch, fd;
bflag = 0;
while ((ch = getopt(argc, argv, "bf:")) != EOF)
switch(ch) {
case 'b':
bflag = 1;
break;
case 'f':
if ((fd = open(optarg, O_RDONLY, 0)) < 0) {
(void)fprintf(stderr,
"myname: %s: %s\n", optarg, strerror(errno));
exit(1);
}
break;
case '?':
default:
usage();
}
argc -= optind;
argv += optind;
HISTORY
The getopt function appeared 4.3BSD.
BUGS
A single dash - may be specified as an character in optstring, however
it should never have an argument associated with it. This allows
getopt to be used with programs that expect - as an option flag. This
practice is wrong, and should not be used in any current development.
It is provided for backward compatibility only. By default, a single
dash causes getopt to return EOF. This is, we believe, compatible with
System V.
It is also possible to handle digits as option letters. This allows
getopt to be used with programs that expect a number (such as -3) as an
option. This practice is wrong, and should not be used in any current
development. It is provided for backward compatibility only. The fol‐
lowing code fragment works in most cases.
int length;
char *p;
while ((c = getopt(argc, argv, "0123456789")) != EOF)
switch (c) {
case '0': case '1': case '2': case '3': case '4':
case '5': case '6': case '7': case '8': case '9':
p = argv[optind - 1];
if (p[0] == '-' && p[1] == ch && !p[2])
length = atoi(++p);
else
length = atoi(argv[optind] + 1);
break;
}
}
SEE ALSO
getsubopt(3), getopt_long(3G).
GNO 26 January 1997 GETOPT(3)
Man(1) output converted with
man2html