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

FreeBSD Manual Pages

  
 
  

home | help
getopts(1)			 User Commands			    getopts(1)

NAME
       getopts - parse utility options

SYNOPSIS
       /usr/bin/getopts	optstring name [ arg...]

   sh
       getopts optstring name [argument...]

   ksh
       getopts optstring name [arg...]

DESCRIPTION
   /usr/bin/getopts
       The  getopts  utility  can be used to retrieve options and option-argu-
       ments from a list of parameters.

       Each time it is invoked,	the getopts utility places the	value  of  the
       next option in the shell	variable specified by the name operand and the
       index of	the next argument  to  be  processed  in  the  shell  variable
       OPTIND. Whenever	the shell is invoked, OPTIND is	initialized to 1.

       When the	option requires	an option-argument, the	getopts	utility	places
       it in the shell variable	OPTARG.	If no option was found,	or if the  op-
       tion that was found does	not have an option-argument, OPTARG is unset.

       If  an option character not contained in	the optstring operand is found
       where an	option character is expected, the shell	variable specified  by
       name is set to the question-mark	( ? ) character.  In this case,	if the
       first character in optstring is a colon (:, the shell  variable	OPTARG
       is set to the option character found, but no output is written to stan-
       dard error; otherwise, the shell	variable OPTARG	is unset and  a	 diag-
       nostic  message is written to standard error. This condition is consid-
       ered to be an error detected in the way arguments were presented	to the
       invoking	application, but is not	an error in getopts processing.

       If an option-argument is	missing:

	 o  If the first character of optstring	is a colon, the	shell variable
	    specified by name is set to	the  colon  character  and  the	 shell
	    variable OPTARG is set to the option character found.

	 o  Otherwise,	the  shell  variable  specified	 by name is set	to the
	    question-mark character (?), the shell variable OPTARG  is	unset,
	    and	a diagnostic message is	written	to standard error. This	condi-
	    tion is considered to be an	error detected in  the	way  arguments
	    were presented to the invoking application,	but is not an error in
	    getopts processing;	a diagnostic message is	written	as stated, but
	    the	exit status is zero.

       When  the end of	options	is encountered,	the getopts utility exits with
       a return	value greater than zero; the shell variable OPTIND is  set  to
       the index of the	first non-option-argument, where the first -- argument
       is considered to	be an option-argument if there are  no	other  non-op-
       tion-arguments appearing	before it, or the value	$# + 1 if there	are no
       non-option-arguments; the name variable is  set	to  the	 question-mark
       character. Any of the following identifies the end of options: the spe-
       cial option --, finding an argument that	does not begin with  a	-,  or
       encountering an error.

       The  shell  variables  OPTIND  and  OPTARG  are	local to the caller of
       getopts and are not exported by default.

       The shell variable specified by the name	operand, OPTIND	and OPTARG af-
       fect the	current	shell execution	environment.

       If  the application sets	OPTIND to the value 1, a new set of parameters
       can be used: either the current positional parameters or	new  arg  val-
       ues.  Any  other	 attempt  to invoke getopts multiple times in a	single
       shell execution environment with	parameters (positional	parameters  or
       arg  operands)  that  are  not  the same	in all invocations, or with an
       OPTIND value modified to	be a value other than 1, produces  unspecified
       results.

   sh
       getopts is a built-in Bourne shell command used to parse	positional pa-
       rameters	and to check for valid options.	See sh(1). It supports all ap-
       plicable	 rules	of  the	 command  syntax standard (see Rules 3-10, in-
       tro(1)).	It should be used in place of the getopt command.

       optstring must contain the option letters  the  command	using  getopts
       recognizes.  If a letter	is followed by a colon,	the option is expected
       to have an argument, or group of	arguments,  which  must	 be  separated
       from it by white	space.

       Each  time  it  is invoked, getopts places the next option in the shell
       variable	name and the index of the next argument	to be processed	in the
       shell variable OPTIND. Whenever the shell or a shell script is invoked,
       OPTIND is initialized to	1.

       When an option requires an option-argument, getopts places  it  in  the
       shell variable OPTARG.

       If an illegal option is encountered, ? is placed	in name.

       When  the  end of options is encountered, getopts exits with a non-zero
       exit status. The	special	option - can be	used to	delimit	the end	of the
       options.

       By  default,  getopts  parses the positional parameters.	If extra argu-
       ments (argument ...) are	given on the  getopts  command	line,  getopts
       parses them instead.

       /usr/lib/getoptcvt  reads  the shell script in filename,	converts it to
       use getopts instead of getopt, and writes the results on	 the  standard
       output.

       So  that	 all  new  commands  adhere to the command syntax standard de-
       scribed in intro(1), they should	use getopts or getopt to  parse	 posi-
       tional  parameters  and	check for options that are valid for that com-
       mand.

       getopts prints an error message on the standard error when  it  encoun-
       ters an option letter not included in optstring.

       Although	 the  following	command	syntax rule (see intro(1)) relaxations
       are permitted under the current implementation, they should not be used
       because	they can not be	supported in future releases of	the system. As
       in the EXAMPLES section below, -a and -b	are options, and the option -o
       requires	an option-argument.

       The  following  example	violates Rule 5: options with option-arguments
       must not	be grouped with	other options:

       example%	cmd -aboxxx filename

       The following example violates Rule 6: there must be white space	 after
       an option that takes an option-argument:

       example%	cmd -ab	oxxx filename

       Changing	 the  value  of	the shell variable OPTIND or parsing different
       sets of arguments can lead to unexpected	results.

   ksh
       Checks arg for legal options. If	arg is omitted,	the positional parame-
       ters are	used. An option	argument begins	with a + or a -. An option not
       beginning with +	or - or	the argument -	ends  the  options.  optstring
       contains	 the  letters that getopts recognizes. If a letter is followed
       by a :, that option is expected to have an argument. The	options	can be
       separated from the argument by blanks.

       getopts	places	the  next  option letter it finds inside variable name
       each time it is invoked with a +	prepended when arg begins  with	 a  +.
       The  index of the next arg is stored in OPTIND. The option argument, if
       any, gets stored	in OPTARG.

       A leading : in optstring	causes getopts to store	the letter of  an  in-
       valid  option in	OPTARG,	and to set name	to ? for an unknown option and
       to : when a required option is missing. Otherwise,  getopts  prints  an
       error  message.	The exit status	is non-zero when there are no more op-
       tions.

       getopts supports	both traditional single-character  short  options  and
       long options defined by Sun's Command Line Interface Paradigm (CLIP).

       Each  long  option  is  an alias	for a short option and is specified in
       parentheses following its equivalent short option.   For	 example,  you
       can specify the long option file	as an alias for	the short option f us-
       ing the following script	line:

       getopts "f(file)" opt

       Precede long options on the command line	with --	or ++. In the  example
       above,  --file  on  the command line would be the equivalent of -f, and
       ++file on the command line would	be the equivalent of +f.

       Each short option can have multiple long	option	equivalents,  although
       this  is	in violation of	the CLIP specification and should be used with
       caution.	You must enclose each long option equivalent  parentheses,  as
       follows:

       getopts "f:(file)(input-file)o:(output-file)"

       In  the	above example, both --file and --input-file are	the equivalent
       of -f, and --output-file	is the equivalent of -o.

       The variable name is always set to a short option. When a  long	option
       is  specified  on  the  command	line,  name is set to the short-option
       equivalent.

       For a further discussion	of the Korn shell's getopts built-in  command,
       see  the	 previous  discussion in the Bourne shell (sh) section of this
       manpage.

OPERANDS
       The following operands are supported:

       optstring       A string	containing the option characters recognised by
		       the  utility  invoking  getopts.	If a character is fol-
		       lowed by	a colon, the option is expected	to have	an ar-
		       gument,	which  should  be supplied as a	separate argu-
		       ment. Applications should specify an  option  character
		       and  its	 option-argument  as  separate	arguments, but
		       getopts interprets the characters following  an	option
		       character requiring arguments as	an argument whether or
		       not this	is done. An explicit null option-argument need
		       not  be	recognised if it is not	supplied as a separate
		       argument	when getopts is	invoked; see  getopt(3C).  The
		       characters  question-mark (?) and colon (:) must	not be
		       used as option characters by an application. The	use of
		       other  option characters	that are not alphanumeric pro-
		       duces unspecified results. If  the  option-argument  is
		       not  supplied  as  a  separate argument from the	option
		       character, the value in OPTARG is stripped of  the  op-
		       tion  character	and the	-. The first character in opt-
		       string determines how  getopts  behaves	if  an	option
		       character  is  not known	or an option-argument is miss-
		       ing.

       name	       The name	of a shell variable that is set	by the getopts
		       utility to the option character that was	found.

       The  getopts  utility by	default	parses positional parameters passed to
       the invoking shell procedure. If	args are given,	they  are  parsed  in-
       stead of	the positional parameters.

USAGE
       Since  getopts  affects	the current shell execution environment, it is
       generally provided as a shell regular built-in. If it is	 called	 in  a
       subshell	 or separate utility execution environment, such as one	of the
       following:

	     (getopts abc value	"$@")
	      nohup getopts ...
	      find . -exec getopts ... \;

       it does not affect the shell variables in the caller's environment.

       Notice that shell functions share OPTIND	with the  calling  shell  even
       though  the  positional	parameters are changed.	Functions that want to
       use getopts to parse their arguments usually want to save the value  of
       OPTIND  on  entry  and  restore it before returning. However, there are
       cases when a function wants to change OPTIND for	the calling shell.

EXAMPLES
       Example 1: Parsing and Displaying Arguments

       The following example script parses and displays	its arguments:

       aflag=
       bflag=
       while getopts ab: name
       do
	    case $name in
	    a)	    aflag=1;;
	    b)	    bflag=1
		    bval="$OPTARG";;
	    ?)	   printf "Usage: %s: [-a] [-b value] args\n"  $0
		   exit	2;;
	    esac
       done
       if [ ! -z "$aflag" ]; then
	  printf "Option -a specified\n"
       fi
       if [ ! -z "$bflag" ]; then
	    printf 'Option -b "%s" specified\n'	"$bval"
       fi
       shift $(($OPTIND	- 1))
       printf "Remaining arguments are:	%s\n" "$*"

       Example 2: Processing Arguments for a Command with Options

       The following fragment of a shell program processes the arguments for a
       command	that  can take the options -a or -b. It	also processes the op-
       tion -o,	which requires an option-argument:

       while getopts abo: c
       do
	     case $c in
	    a |	b)   FLAG=$c;;
	    o)	     OARG=$OPTARG;;
	    \?)	     echo $USAGE
	       exit 2;;
	    esac
       done
       shift `expr $OPTIND - 1`

       Example 3: Equivalent Code Expressions

       This code example accepts any of	the following as equivalent:

       cmd -a -b -o "xxx z yy" filename
       cmd -a -b -o "xxx z yy" -- filename
       cmd -ab -o xxx,z,yy filename
       cmd -ab -o "xxx z yy" filename
       cmd -o xxx,z,yy -b -a filename

ENVIRONMENT VARIABLES
       See environ(5) for descriptions of the following	environment  variables
       that  affect  the execution of getopts: LANG, LC_ALL, LC_CTYPE, LC_MES-
       SAGES, and NLSPATH.

       OPTIND	       This variable is	used by	getopts	as the	index  of  the
		       next argument to	be processed.

       OPTARG	       This  variable is used by getopts to store the argument
		       if an option is using arguments.

EXIT STATUS
       The following exit values are returned:

       0	An option, specified or	unspecified by optstring, was found.

       >0	The end	of options was encountered or an error occurred.

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

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWcsu			   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Standard			   |
       +-----------------------------+-----------------------------+

SEE ALSO
       intro(1), getoptcvt(1), ksh(1), sh(1), getopt(3C), attributes(5), envi-
       ron(5), standards(5)

DIAGNOSTICS
       Whenever	 an error is detected and the first character in the optstring
       operand is not a	colon (:), a diagnostic	message	is written to standard
       error with the following	information in an unspecified format:

	 o  The	invoking program name is identified in the message. The	invok-
	    ing	program	name is	the value of the shell special parameter 0  at
	    the	time the getopts utility is invoked. A name equivalent to

	    basename "$0"

	    can	be used.

	 o  If	an  option  is found that was not specified in optstring, this
	    error is identified	and the	invalid	option character is identified
	    in the message.

	 o  If an option requiring an option-argument is found,	but an option-
	    argument is	not found, this	error is identified  and  the  invalid
	    option character is	identified in the message.

SunOS 5.10			  21 Jul 2004			    getopts(1)

NAME | SYNOPSIS | DESCRIPTION | OPERANDS | USAGE | EXAMPLES | ENVIRONMENT VARIABLES | EXIT STATUS | ATTRIBUTES | SEE ALSO | DIAGNOSTICS

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

home | help