getopt man page on SuSE

Man page or keyword search:  
man Server   14857 pages
apropos Keyword Search (all sections)
Output format
SuSE logo
[printable version]

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

PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the	 corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.

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	 Util‐
       ity  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	Guide‐
       lines.

       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[] vec‐
       tor  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 characters, 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 reentrant 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 argu‐
       ment 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 por‐
       table. Note that support for multi-byte option characters is only  pos‐
       sible 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 appli‐
       cation to make a distinction between a missing argument and  an	incor‐
       rect  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 original Standard can be obtained online
       at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group		     2003			    GETOPT(3P)
[top]

List of man pages available for SuSE

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net