getopt man page on Gentoo

Man page or keyword search:  
man Server   6889 pages
apropos Keyword Search (all sections)
Output format
Gentoo 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 opterr, optind, 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 POSIX.1‐2008, 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  implementa‐
       tion 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[].
       If the application sets optind to zero  before  calling	getopt(),  the
       behavior	 is  unspecified.  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>  charac‐
       ter  (':')  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 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
       If the application has not set the variable  opterr  to	0,  the	 first
       character of optstring is not a <colon>, and a write error occurs while
       getopt() is printing a diagnostic message to  stderr,  then  the	 error
       indicator for stderr shall be set; but getopt() shall still succeed and
       the value of errno after getopt() is unspecified.

       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 <stdio.h>
	   #include <stdlib.h>
	   #include <unistd.h>

	   int
	   main(int argc, char *argv[ ])
	   {
	       int c;
	       int bflg = 0, aflg = 0, errflg = 0;
	       char *ifile;
	       char *ofile;
	       . . .
	       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++;
		       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

   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>
	   ...
	   const char *Options = "hdbtl";
	   ...
	   int dbtype, 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.

       While ferror(stderr) may be used to detect failures to write a diagnos‐
       tic to stderr when getopt() returns '?', the value of errno is unspeci‐
       fied in such a condition. Applications desiring more control over  han‐
       dling  write  failures should set opterr to 0 and independently perform
       output to stderr, rather than relying on getopt() to do the output.

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> characters or not. Note that the requirements on
       getopt() and getopts are more stringent than the Utility Syntax	Guide‐
       lines.

       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  opt‐
       string 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 POSIX.1‐2008, Section 12.2, Utility Syn‐
       tax Guidelines, <unistd.h>

       The Shell and Utilities volume of POSIX.1‐2008, getopts

COPYRIGHT
       Portions of this text are reprinted and reproduced in  electronic  form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX),	The  Open  Group  Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
       cal and Electronics Engineers,  Inc  and	 The  Open  Group.   (This  is
       POSIX.1-2008  with  the	2013  Technical Corrigendum 1 applied.) 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.unix.org/online.html .

       Any  typographical  or  formatting  errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files  to  man page format. To report such errors, see https://www.ker‐
       nel.org/doc/man-pages/reporting_bugs.html .

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

List of man pages available for Gentoo

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