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
       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 specifiy 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 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
       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	     |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