Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
getopt(3C)		 Standard C Library Functions		    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
       #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 ap-
       plications 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 ex-
       tension 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 specifiy long-option	equivalents to	short  options
       by following the	short-option character (and optional colon) with a se-
       quence 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 fol-
	    lowing the option character	in that	argument, and optind is	incre-
	    mented 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	following  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 opt-
       string  argument	 was  a	 colon (:), in which case getopt() returns the
       colon (:) character. For	short options, getopt()	sets the variable  op-
       topt  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 en-
       counters.

       #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 se-
		       quences of bytes	as characters in optstring.

USAGE
       The getopt() function does not fully check for mandatory	arguments  be-
       cause  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 in-
       tro(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 correct
       syntax to use is:

	      cmd- ab -o filename

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |See below.		   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |Unsafe			   |
       +-----------------------------+-----------------------------+

       The Basic Utility Command syntax	is Standard. The CLIP  extensions  are
       Evolving.

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

SunOS 5.10			  13 May 2004			    getopt(3C)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | EXAMPLES | ENVIRONMENT VARIABLES | USAGE | ATTRIBUTES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=getopt&sektion=3c&manpath=SunOS+5.10>

home | help