Unix/Linux Go Back    


Linux 2.6 - man page for getopts (linux section 1posix)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


GETOPTS(P)			    POSIX Programmer's Manual			       GETOPTS(P)

NAME
       getopts - parse utility options

SYNOPSIS
       getopts optstring name [arg...]

DESCRIPTION
       The getopts utility shall retrieve options and option-arguments from a list of parameters.
       It shall support the Utility Syntax Guidelines 3 to 10, inclusive, described in	the  Base
       Definitions volume of IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.

       Each  time  it is invoked, the getopts utility shall place 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 shall be
       initialized to 1.

       When the option requires an option-argument, the getopts utility shall  place  it  in  the
       shell  variable	OPTARG . If no option was found, or if the option that was found does not
       have an option-argument, OPTARG shall be 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 shall be set to the question-
       mark ( '?' ) character. In this case, if the first character in optstring is a colon ( ':'
       ),  the	shell  variable  OPTARG shall be set to the option character found, but no output
       shall be written to standard error; otherwise, the shell variable OPTARG  shall	be  unset
       and  a diagnostic message shall be written to standard error. This condition shall be con-
       sidered to be an error detected in the way arguments were presented to the invoking appli-
       cation, but shall not be an error in getopts processing.

       If an option-argument is missing:

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

	* Otherwise, the shell variable specified by name shall be set to the question-mark char-
	  acter, the shell variable OPTARG shall be unset, and	a  diagnostic  message	shall  be
	  written  to  standard error. This condition shall be considered to be an error detected
	  in the way arguments were presented to the invoking application, but shall  not  be  an
	  error  in  getopts processing; a diagnostic message shall be written as stated, but the
	  exit status shall be zero.

       When the end of options is encountered, the getopts utility shall exit with a return value
       greater	than  zero; the shell variable OPTIND shall be 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-option-arguments appearing before it, or the value "$#" +1 if there
       are no non-option-arguments; the name variable shall be set to the  question-mark  charac-
       ter.  Any  of  the  following shall identify the end of options: the special option "--" ,
       finding an argument that does not begin with a '-' , or encountering an error.

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

       The  shell  variable  specified	by the name operand, OPTIND , and OPTARG shall affect the
       current shell execution environment; see 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 values. Any other attempt to invoke getopts
       multiple times in a single shell execution environment with parameters (positional parame-
       ters  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.

OPTIONS
       None.

OPERANDS
       The following operands shall be supported:

       optstring
	      A string containing the  option  characters  recognized  by  the	utility  invoking
	      getopts.	If  a  character  is followed by a colon, the option shall be expected to
	      have an argument, which should be supplied as  a	separate  argument.  Applications
	      should  specify  an option character and its option-argument as separate arguments,
	      but getopts shall interpret the characters following an option character	requiring
	      arguments as an argument whether or not this is done. An explicit null option-argu-
	      ment need not be recognized if it is not	supplied  as  a  separate  argument  when
	      getopts  is  invoked.  (See also the getopt() function defined in the System Inter-
	      faces volume of IEEE Std 1003.1-2001.)   The  characters	question-mark  and  colon
	      shall  not  be used as option characters by an application. The use of other option
	      characters that are not alphanumeric produces unspecified results. If  the  option-
	      argument	is  not  supplied  as  a separate argument from the option character, the
	      value in OPTARG shall be stripped of the option character and the '-' .  The  first
	      character in optstring determines how getopts behaves if an option character is not
	      known or an option-argument is missing.

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

       The  getopts  utility  by default shall parse positional parameters passed to the invoking
       shell procedure. If args are given, they shall be parsed instead of the positional parame-
       ters.

STDIN
       Not used.

INPUT FILES
       None.

ENVIRONMENT VARIABLES
       The following environment variables shall affect the execution of getopts:

       LANG   Provide  a  default  value for the internationalization variables that are unset or
	      null. (See the Base Definitions volume of IEEE Std 1003.1-2001, Section 8.2, Inter-
	      nationalization Variables for the precedence of internationalization variables used
	      to determine the values of locale categories.)

       LC_ALL If set to a non-empty string value, override the values of all the  other  interna-
	      tionalization variables.

       LC_CTYPE
	      Determine  the  locale for the interpretation of sequences of bytes of text data as
	      characters (for example, single-byte as opposed to multi-byte characters	in  argu-
	      ments and input files).

       LC_MESSAGES
	      Determine the locale that should be used to affect the format and contents of diag-
	      nostic messages written to standard error.

       NLSPATH
	      Determine the location of message catalogs for the processing of LC_MESSAGES .

       OPTIND This variable shall be used by the getopts utility as the index of the  next  argu-
	      ment to be processed.

ASYNCHRONOUS EVENTS
       Default.

STDOUT
       Not used.

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

	* The invoking program name shall be identified in the message. The invoking program name
	  shall be the value of the shell special parameter 0 (see Special Parameters  )  at  the
	  time the getopts utility is invoked. A name equivalent to:

	  basename "$0"

       may be used.

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

	* If an option requiring an option-argument is	found,	but  an  option-argument  is  not
	  found, this error shall be identified and the invalid option character shall be identi-
	  fied in the message.

OUTPUT FILES
       None.

EXTENDED DESCRIPTION
       None.

EXIT STATUS
       The following exit values shall be returned:

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

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

CONSEQUENCES OF ERRORS
       Default.

       The following sections are informative.

APPLICATION 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.

       Note that shell functions share OPTIND with the calling shell even though  the  positional
       parameters  are	changed.  If  the  calling shell and any of its functions uses getopts to
       parse arguments, the results are unspecified.

EXAMPLES
       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" "$*"

RATIONALE
       The getopts utility was chosen in preference  to  the  System  V  getopt  utility  because
       getopts handles option-arguments containing <blank>s.

       The  OPTARG variable is not mentioned in the ENVIRONMENT VARIABLES section because it does
       not affect the execution of getopts; it is one of the few "output-only" variables used  by
       the standard utilities.

       The  colon  is not allowed as an option character because that is not historical behavior,
       and it violates the Utility Syntax Guidelines. The colon is now specified to behave as  in
       the KornShell version of the getopts utility; when used as the first character in the opt-
       string operand, it disables diagnostics concerning missing option-arguments and unexpected
       option  characters.  This replaces the use of the OPTERR variable that was specified in an
       early proposal.

       The formats of the diagnostic messages produced by the getopts utility  and  the  getopt()
       function  are  not  fully  specified because implementations with superior (``friendlier")
       formats objected to the formats used by	some  historical  implementations.  The  standard
       developers  considered  it  important that the information in the messages used be uniform
       between getopts and getopt(). Exact duplication of the messages	might  not  be	possible,
       particularly  if  a utility is built on another system that has a different getopt() func-
       tion, but the messages must have specific information included so that the  program  name,
       invalid option character, and type of error can be distinguished by a user.

       Only  a	rare application program intercepts a getopts standard error message and wants to
       parse it. Therefore, implementations are free to choose the most usable messages they  can
       devise. The following formats are used by many historical implementations:

	      "%s: illegal option -- %c\n", <program name>, <option character>

	      "%s: option requires an argument -- %c\n", <program name>, \
		  <option character>

       Historical  shells  with built-in versions of getopt() or getopts have used different for-
       mats, frequently not even indicating the option character found in error.

FUTURE DIRECTIONS
       None.

SEE ALSO
       Special Parameters , the System Interfaces volume of IEEE Std 1003.1-2001, getopt()

COPYRIGHT
       Portions of this text are reprinted and	reproduced  in	electronic  form  from	IEEE  Std
       1003.1,	2003  Edition,	Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003  by
       the  Institute  of  Electrical  and  Electronics Engineers, Inc and The Open Group. 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 orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003				       GETOPTS(P)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 05:32 PM.