osf1 man page for getopt

getopt(3)						     Library Functions Manual							 getopt(3)

NAME
       getopt - Gets flag letters from the argument vector

LIBRARY
       Standard C Library (libc)

SYNOPSIS
       #include <unistd.h>

       int getopt(
	       int argc,
	       char * const argv[],
	       const char *optstring);

       extern char *optarg;

       extern int optind;

       extern int opterr;

       extern int optopt;

STANDARDS
       Interfaces documented on this reference page conform to industry standards as follows:

       getopt(): XSH5.0

       Refer to the standards(5) reference page for more information about industry standards and associated tags.

PARAMETERS
       Specifies  the number of parameters passed to the routine.  Points to an array of argc pointers to argument strings.  Specifies a string of
       recognized flag characters.  If a character is followed by a : (colon), the flag is expected to take a parameter that may  or  may  not	be
       separated from it by white space.

DESCRIPTION
       The  getopt() function parses argument lists. It returns the next flag character in the argv parameter list that matches a character in the
       optstring parameter. If that flag takes an argument, the getopt() function has the optarg variable point to the flag argument according	to
       the  following  rules: If the flag is the last character pointed to by an argv element, optarg will contain argv's next element, and optind
       is incremented by 2. The getopt() function returns an error if the resulting optind is greater than or equal to argc.  If the flag  is  not
       the  last  character,  then the optarg variable points to the string after the flag character in the associated element of argv. The optind
       variable is incremented by 1.

       The optarg external variable is set to point to the start of the flag's parameter on return from the getopt() function.

       The getopt() function places the argv index of the next argument to be processed in optind. The optind variable is  externally  initialized
       to  1 before the first call to getopt() so that argv[0] is not processed. Error messages can be suppressed by providing a value of 0 (zero)
       as the opterr parameter.

NOTES
       [Tru64 UNIX]  The external int optopt variable is set to the real flag found in the argv parameter. This is true whether the flag is in the
       optstring parameter or not.

EXAMPLES
       The following example shows a suggested way to use the getopt() function.

       #include <unistd.h> main(argc, argv) int     argc; char	  *argv[];

       #define ARGS    "r:w:f:s"

       {
	       int     c, errflg = 0;
	       int     readers = 1, writers = 1;
	       int     freeBufs = 1;
	       int     doStats = FALSE;

	       optarg = NULL;
	       while (!errflg && ((c = getopt(argc, argv, ARGS)) != -1))
		       switch (c) {
		       case 'r'        :
			       readers = atoi(optarg);
			       break;
		       case 'w'        :
			       writers = atoi(optarg);
			       break;
		       case 'f'        :
			       freeBufs = atoi(optarg);
			       break;
		       case 's'        :
			       doStats = TRUE;
			       break;
		       default :
			       errflg++;
		       }

RETURN VALUES
       Upon  successful completion, the getopt() function returns the flag character that was detected.  If the function encounters a flag that is
       not included in the optstring parameter, or if the : (colon) character is used incorrectly, the getopt() function prints an  error  message
       on  stderr  and	returns  a  ? (question mark).	If there is a missing flag, the getopt() function returns a : (colon) if optstring's first
       character is a : (colon), and a ? (question mark) otherwise.  In addition, the getopt() function sets the optopt variable to the flag char-
       acter that caused one of these errors.

       The  getopt()  function	also displays a diagnostic message if the application did not set the opterr variable to 0 (zero), and optstring's
       first character is not a : (colon).

       When all flags have been processed (that is, up to the first nonflag argument), the getopt() function returns a value of -1.   The  special
       flag -- (dash dash) can be used to delimit the end of the flags; -1 is returned, and the -- (dash dash) string is skipped.

       The  getopt()  function	does not change optind, and also returns a value of -1, if one of the following occurs: The argv[optind] result is
       NULL.  The *argv[optind] result is not the special - (dash) flag.  The argv[optind] result points to the - (dash) string.

       The getopt() function does increment optind if the result of argv[optind] points to the -- (dash dash) string.

RELATED INFORMATION
       Commands: getopt(1)

       Standards: standards(5) delim off

																	 getopt(3)