GETOPT man page on SmartOS

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

GETOPT(3C)							    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, SUSv3
       #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 stan‐
       dards (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  guidelines
       are  not addressed by getopt() and are the responsibility of the appli‐
       cation.

       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 Util‐
       ity Syntax Guidelines, optstring is a string of recognized option char‐
       acters. 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 specify 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 argu‐
       ment  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 following 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 fol‐
		  lowing  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	 oper‐
       and),  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 variable
       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 optstring 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\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

       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\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;
	     }
	 }

       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\n");
	     exit(0);
	 case '?':
	     if (optopt == '?') {
		 print_help();
		 exit(0);
	     }
	     if (optopt == '-')
		 fprintf(stderr,
		     "unrecognized option: %s\n", argv[optind-1]);
	     else
		 fprintf(stderr,
		     "unrecognized option: -%c\n", 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\n", argv[optind-1]);
	     else
		 fprintf(stderr,
		     "Option -%c requires an operand\n", 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_MESSAGES.

       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 manda‐
       tory argument to the -a option and not that -a is missing  a  mandatory
       argument.  Indeed, the only time a missing option-argument can be reli‐
       ably 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 │ Committed	      │
       ├────────────────────┼─────────────────┤
       │MT-Level	    │ Unsafe	      │
       ├────────────────────┼─────────────────┤
       │Standard	    │ See below.      │
       └────────────────────┴─────────────────┘

       For the Basic Utility Command syntax is Standard, see standards(5).

SEE ALSO
       Intro(1),  getopt(1),  getopts(1),  getsubopt(3C),  gettext(3C), setlo‐
       cale(3C), attributes(5), environ(5), standards(5)

				 Oct 16, 2007			    GETOPT(3C)
[top]

List of man pages available for SmartOS

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