Unix/Linux Go Back    


Linux 2.6 - man page for optopt (linux section 3posix)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


GETOPT(P)			    POSIX Programmer's Manual				GETOPT(P)

NAME
       getopt, optarg, opterr, optind, optopt - command option parsing

SYNOPSIS
       #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 shall follow Utility Syntax Guidelines
       3, 4, 5, 6, 7, 9, and 10 in the Base Definitions volume of  IEEE Std 1003.1-2001,  Section
       12.2, Utility Syntax Guidelines.

       The parameters argc and argv are the argument count and argument array as passed to main()
       (see exec() ). The argument optstring is a string of recognized option  characters;  if	a
       character  is  followed	by  a  colon, the option takes an argument. All option characters
       allowed by Utility Syntax Guideline 3 are allowed in  optstring.  The  implementation  may
       accept other characters as an extension.

       The variable optind is the index of the next element of the argv[] vector to be processed.
       It shall be initialized to 1 by the system, and getopt() shall update it when it  finishes
       with  each  element  of argv[]. When an element of argv[] contains multiple option charac-
       ters, it is unspecified how getopt() determines which options have already been processed.

       The getopt() function shall return the next option character (if one is found)  from  argv
       that  matches  a character in optstring, if there is one that matches. If the option takes
       an argument, getopt() shall set the variable optarg to point  to  the  option-argument  as
       follows:

	1. If  the  option was the last character in the string pointed to by an element of argv,
	   then optarg shall contain the next element of argv, and optind shall be incremented by
	   2.  If  the	resulting  value of optind is greater than argc, this indicates a missing
	   option-argument, and getopt() shall return an error indication.

	2. Otherwise, optarg shall point to the string following the  option  character  in  that
	   element of argv, and optind shall be incremented by 1.

       If, when getopt() is called:

	      argv[optind]  is a null pointer*
	      argv[optind]  is not the character -
	      argv[optind]  points to the string "-"

       getopt() shall return -1 without changing optind. If:

	      argv[optind]   points to the string "--"

       getopt() shall return -1 after incrementing optind.

       If  getopt()  encounters  an option character that is not contained in optstring, it shall
       return the question-mark ( '?' ) character. If it detects a  missing  option-argument,  it
       shall  return the colon character ( ':' ) if the first character of optstring was a colon,
       or a question-mark character ( '?' ) otherwise. In either case,	getopt()  shall  set  the
       variable  optopt to the option character that caused the error. If the application has not
       set the variable opterr to 0 and the first character of optstring is not a colon, getopt()
       shall  also  print  a diagnostic message to stderr in the format specified for the getopts
       utility.

       The getopt() function need not be reentrant. A function that is not required to	be  reen-
       trant is not required to be thread-safe.

RETURN VALUE
       The  getopt()  function	shall  return  the next option character specified on the command
       line.

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

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

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

ERRORS
       No errors are defined.

       The following sections are informative.

EXAMPLES
   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\n", optopt);
				  errflg++;
				  break;
		      case '?':
				  fprintf(stderr,
					  "Unrecognized option: -%c\n", 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

   Checking 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\n");
		      break;
		  case 'b':
		      printf("b is set\n");
		      break;
		  case 'f':
		      filename = optarg;
		      printf("filename is %s\n", filename);
		      break;
		  case ':':
		      printf("-%c without filename\n", optopt);
		      break;
		  case '?':
		      printf("unknown arg %c\n", optopt);
		      break;
		  }
	      }

   Selecting Options from the Command Line
       The following example selects the type of database routines the user wants to use based on
       the Options argument.

	      #include <unistd.h>
	      #include <string.h>
	      ...
	      char *Options = "hdbtl";
	      ...
	      int dbtype, i;
	      char c;
	      char *st;
	      ...
	      dbtype = 0;
	      while ((c = getopt(argc, argv, Options)) != -1) {
		  if ((st = strchr(Options, c)) != NULL) {
		      dbtype = st - Options;
		      break;
		  }
	      }

APPLICATION USAGE
       The  getopt()  function	is only required to support option characters included in Utility
       Syntax Guideline 3. Many historical implementations of getopt() support	other  characters
       as  options.  This  is  an allowed extension, but applications that use extensions are not
       maximally portable. Note that support for multi-byte option characters  is  only  possible
       when such characters can be represented as type int.

RATIONALE
       The  optopt  variable  represents historical practice and allows the application to obtain
       the identity of the invalid option.

       The description has been written to make it clear that getopt(), like the getopts utility,
       deals  with  option-arguments  whether  separated from the option by <blank>s or not. Note
       that the requirements on getopt() and getopts are more stringent than the  Utility  Syntax
       Guidelines.

       The getopt() function shall return -1, rather than EOF, so that <stdio.h> is not required.

       The  special  significance  of  a colon as the first character of optstring makes getopt()
       consistent with the getopts utility. It	allows	an  application  to  make  a  distinction
       between	a  missing  argument and an incorrect option letter without having to examine the
       option letter. It is true that a missing argument can only be detected in  one  case,  but
       that is a case that has to be considered.

FUTURE DIRECTIONS
       None.

SEE ALSO
       exec()  ,  the  Base Definitions volume of IEEE Std 1003.1-2001, <unistd.h>, the Shell and
       Utilities volume of IEEE Std 1003.1-2001

COPYRIGHT
       Portions of this text are reprinted and	reproduced  in	electronic  form  from	IEEE  Std
       1003.1,	2003  Edition,	Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003  by
       the  Institute  of  Electrical  and  Electronics Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE  and  The  Open  Group
       Standard, the original IEEE and The Open Group Standard is the referee document. The orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003					GETOPT(P)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 01:56 AM.