getopt(3C)						   Standard C Library Functions 						getopt(3C)

NAME

       getopt - command option parsing

SYNOPSIS

   SVID3, XPG3
       #include <stdio.h>

       int getopt(int argc, char * const argv[], const char *optstring);
       extern char *optarg;
       extern int optind, opterr, optopt;

   POSIX.2, XPG4, SUS, SUSv2
       #include <unistd.h>

       int getopt(int argc, char * const argv[], const char *optstring);
       extern char *optarg;
       extern int optind, opterr, optopt;

DESCRIPTION

       The  getopt() function is a command line parser that can be used by applications that follow Basic Utility Syntax Guidelines 3, 4, 5, 6, 7,
       9, and 10 which parallel those defined by application portability standards (see intro(1)). It can also be used by applications which addi-
       tionally  follow  the Command Line Interface Paradigm (CLIP) syntax extension guidelines 15, 16, and 17. It partially enforces guideline 18
       by requiring that every option has a short-name, but it allows multiple long-names to be associated with an option.  The  remaining  guide-
       lines are not addressed by getopt() and are the responsibility of the application.

       The argc and argv arguments are the argument count and argument array as passed to main (see exec(2)). The optstring argument specifies the
       acceptable options. For utilities wanting to conform to the Basic Utility Syntax Guidelines, optstring is a  string  of	recognized  option
       characters.  All  option  characters  allowed by Utility Syntax Guideline 3 are allowed in optstring. If a character is followed by a colon
       (:), the option is expected to have an option-argument, which can be separated from it by white space.  Utilities wanting to conform to the
       extended CLIP guidelines can specifiy long-option equivalents to short options by following the short-option character (and optional colon)
       with a sequence of strings, each enclosed in parentheses, that specify the long-option aliases.

       The getopt() function returns the short-option character in optstring that corresponds to the next option found in argv.

       The getopt() function places in optind the argv index of the next argument to be processed. The optind variable is external and is initial-
       ized to 1 before the first call to getopt(). The getopt() function sets the variable optarg to point to the start of the option-argument as
       follows:

	 o  If the option is a short option and that character is the last character in the argument, then optarg contains  the  next  element	of
	    argv, and optind is incremented by 2.

	 o  If the option is a short option and that character is not the last character in the argument, then optarg points to the string follow-
	    ing the option character in that argument, and optind is incremented by 1.

	 o  If the option is a long option and the character equals is not found in the argument, then optarg contains the next element  of  argv,
	    and optind is incremented by 2.

	 o  If	the  option  is  a  long  option and the character equals is found in the argument, then optarg points to the string following the
	    equals character in that argument and optind is incremented by 1.

       In all cases, if the resulting value of optind is not less than argc, this indicates a missing  option-argument	and  getopt()  returns	an
       error indication.

       When  all options have been processed (that is, up to the first operand), getopt() returns -1. The special option "--" (two hyphens) can be
       used to delimit the end of the options; when it is encountered, -1 is returned and "--" is skipped. This is useful in delimiting non-option
       arguments that begin with "-" (hyphen).

       If  getopt()  encounters  a short-option character or a long-option string not described in the opstring argument, it returns the question-
       mark (?) character. If it detects a missing option-argument, it also returns the question-mark (?) character, unless the first character of
       the  optstring argument was a colon (:), in which case getopt() returns the colon (:) character. For short options, getopt() sets the vari-
       able optopt to the option character that caused the error. For long options, optopt is set to the hyphen (-) character and the failing long
       option  can  be	identified through argv[optind-1]. If the application has not set the variable opterr to 0 and the first character of opt-
       string is not a colon (:), getopt() also prints a diagnostic message to stderr.

RETURN VALUES

       The getopt() function returns the short-option character associated with the option recognized.

       A colon (:) is returned if getopt() detects a missing argument and the first character of optstring was a colon (:).

       A question mark (?) is returned if getopt() encounters an option not specified in optstring or detects a missing  argument  and	the  first
       character of optstring was not a colon (:).

       Otherwise, getopt() returns -1 when all command line options are parsed.

ERRORS

       No errors are defined.

EXAMPLES

       Example 1: Parsing Command Line Options

       The  following  code  fragment shows how you might process the arguments for a utility that can take the mutually-exclusive options a and b
       and the options f and o, both of which require arguments:

       #include <unistd.h>

       int
       main(int argc, char *argv[ ])
       {
	   int c;
	   int bflg, aflg, errflg;
	   char *ifile;
	   char *ofile;
	   extern char *optarg;
	   extern int optind, optopt;
	   . . .
	   while ((c = getopt(argc, argv, ":abf:o:")) != -1) {
	       switch(c) {
	       case 'a':
		   if (bflg)
		       errflg++;
		   else
		       aflg++;
		   break;
	       case 'b':
		   if (aflg)
		       errflg++;
		   else {
		       bflg++;
		       bproc();
		   }
		   break;
	       case 'f':
		   ifile = optarg;
		   break;
	       case 'o':
		   ofile = optarg;
		   break;
	       case ':':   /* -f or -o without operand */
		   fprintf(stderr,
			  "Option -%c requires an operand
", optopt);
		   errflg++;
		   break;
	       case '?':
		   fprintf(stderr,
			  "Unrecognized option: -%c
", optopt);
		   errflg++;
	       }
	   }
	   if (errflg) {
	       fprintf(stderr, "usage: . . . ");
	       exit(2);
	   }
	   for ( ; optind < argc; optind++) {
	       if (access(argv[optind], R_OK)) {
	   . . .
       }

       This code accepts any of the following as equivalent:

       cmd -ao arg path path
       cmd -a -o arg path path
       cmd -o arg -a path path
       cmd -a -o arg -- path path
       cmd -a -oarg path path
       cmd -aoarg path path

       Example 2: Check Options and Arguments.

       The following example parses a set of command line options and prints messages to standard output for each  option  and	argument  that	it
       encounters.

       #include <unistd.h>
       #include <stdio.h>
       ...
       int c;
       char *filename;
       extern char *optarg;
       extern int optind, optopt, opterr;
       ...
       while ((c = getopt(argc, argv, ":abf:")) != -1) {
	   switch(c) {
	   case 'a':
		printf("a is set
");
		break;
	   case 'b':
		printf("b is set
");
		break;
	   case 'f':
		filename = optarg;
		printf("filename is %s
", filename);
		break;
	   case ':':
		printf("-%c without filename
", optopt);
		break;
	   case '?':
		printf("unknown arg %c
", optopt);
		break;
	   }
       }

       This example can be expanded to be CLIP-compliant by substituting the following string for the optstring argument:

       :a(ascii)b(binary)f:(in-file)o:(out-file)V(version)?(help)

       and by replacing the '?' case processing with:

       case 'V':
	   fprintf(stdout, "cmd 1.1
");
	   exit(0);
       case '?':
	   if (optopt == '?') {
	       print_help();
	       exit(0);
	   }
	   if (optopt == '-')
	       fprintf(stderr,
		   "unrecognized option: %s
", argv[optind-1]);
	   else
	       fprintf(stderr,
		   "unrecognized option: -%c
", optopt);
	   errflg++;
	   break;

       and by replacing the ':' case processing with:

       case ':':   /* -f or -o without operand */
	   if (optopt == '-')
	       fprintf(stderr,
		   "Option %s requires an operand
", argv[optind-1]);
	   else
	       fprintf(stderr,
		   "Option -%c requires an operand
", optopt);
	   errflg++;
	   break;

       While not encouraged by the CLIP specification, multiple long-option aliases can also be assigned as shown in the following example:

       :a(ascii)b(binary):(in-file)(input)o:(outfile)(output)V(version)?(help)

ENVIRONMENT VARIABLES

       See  environ(5)	for  descriptions  of the following environment variables that affect the execution of getopt(): LANG, LC_ALL, and LC_MES-
       SAGES.

       LC_CTYPE        Determine the locale for the interpretation of sequences of bytes as characters in optstring.

USAGE

       The getopt() function does not fully check for mandatory arguments because there is no unambiguous algorithm to	do  so.  Given	an  option
       string  a:b and the input -a -b, getopt() assumes that -b is the mandatory argument to the -a option and not that -a is missing a mandatory
       argument.  Indeed, the only time a missing option-argument can be reliably detected is when the option is the final option on  the  command
       line and is not followed by any command arguments.

       It  is a violation of the Basic Utility Command syntax standard (see intro(1)) for options with arguments to be grouped with other options,
       as in cmd -abo filename , where a and b are options, o is an option that requires an argument, and filename is the argument to o.  Although
       this syntax is permitted in the current implementation, it should not be used because it may not be supported in future releases.  The cor-
       rect syntax to use is:

	      cmd- ab -o filename

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |See below.		   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |Unsafe			   |
       +-----------------------------+-----------------------------+

       The Basic Utility Command syntax is Standard. The CLIP extensions are Evolving.

SEE ALSO

       intro(1), getopt(1), getopts(1), getsubopt(3C), gettext(3C), setlocale(3C), attributes(5), environ(5), standards(5)

SunOS 5.10							    13 May 2004 							getopt(3C)