unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



getopts(1)							   getopts(1)



NAME

  getopts - Parses utility options

SYNOPSIS

  getopts optstring name [arg...]

STANDARDS

  Interfaces documented	on this	reference page conform to industry standards
  as follows:

  getopts:  XCU5.0

  Refer	to the standards(5) reference page for more information	about indus-
  try standards	and associated tags.

OPTIONS

  None

OPERANDS

  optstring
      A	string containing the option characters	recognized by the utility
      invoking getopts.	 If a character	is followed by a colon (:), the
      option is	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 interprets	the
      characters following an option character requiring arguments as an
      argument whether or not this is done. An explicit	null option-argument
      is not recognized	if it is not supplied as a separate argument when
      getopts is invoked.  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	produces 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
      option character and the hyphen (-). The first character in optstring
      determines getopts behavior if an	option character is not	known or an
      option-argument is missing.

  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 instead of the
  positional parameters.





DESCRIPTION

  The getopts utility is used to retrieve flags	and flag-arguments from	a
  list of parameters.

  Each time it is invoked, the getopts utility places the value	of the next
  flag 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 flag	requires a flag-argument, the getopts utility places it	in
  the shell variable OPTARG. If	no flag	is found, or if	the flag found does
  not have a flag-argument, OPTARG is unset.

  If a flag character not contained in the optstring operand is	found where a
  flag 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 flag
  character found, but no output is written; otherwise,	the shell variable
  OPTARG is unset and a	diagnostic message written. This condition is con-
  sidered to be	an error detected in the way arguments were presented to the
  invoking application,	but is not an error in getopts processing.

  If a flag-argument is	missing, then:

    +  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 flag character found.

    +  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 condition is
       considered to be	an error detected in the way arguments were presented
       to the invoking application, but	is not an error	in getopts process-
       ing; a diagnostic message is written as stated, but the exit status is
       zero.

  When the end of flags	is encountered the getopts utility exits with:

    +  A return	value greater than zero

    +  The shell variable OPTIND set to	the index of the first non-flag-
       argument, where the first -- argument is	considered to be a flag-
       argument	if there are no	other non-flag-arguments appearing before it,
       or the value $# + 1 if there are	no non-flag-arguments

    +  The name	variable set to	the question-mark (?) character

  Any of the following identifies the end of flags:

    +  The special flag	--

    +  Finding an argument that	does not begin with a -

    +  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 affect
  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 values. Any
  other	attempt	to invoke getopts multiple times in a single shell execution
  environment with parameters (positional parameters or	flag 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.




NOTES

   1.  If getopts is called in a subshell or separate utility execution
       environment, such as one	of the following it will not affect the	shell
       variables in the	caller's environment:


	    (getopts abc value "$@")
	    nohup getopts ...

   2.  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	will usually want to save the value of OPTIND
       on entry	and restore it before returning.  However, there are cases
       when a function will want to change OPTIND for the calling shell.

RESTRICTIONS

  The getopts command is implemented as	a shell	built-in command. It is	only
  available to users of	the Korn (ksh) and POSIX shells.

  A similar capability is available to Bourne and C shell users	with the
  getopt command.

EXIT STATUS

  The following	exit values are	returned:

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

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

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









ENVIRONMENT VARIABLES

  The following	environment variables affect the execution of getopts:

  LANG
      Provides a default value for the internationalization variables that
      are unset	or null. If LANG is unset or null, the corresponding value
      from the default locale is used.	If any of the internationalization
      variables	contain	an invalid setting, the	utility	behaves	as if none of
      the variables had	been defined.

  LC_ALL
      If set to	a non-empty string value, overrides the	values of all the
      other internationalization variables.

  LC_CTYPE
      Determines 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 arguments and input files).

  LC_MESSAGES
      Determines the locale used to affect the format and contents of diag-
      nostic messages written to standard error.

  NLSPATH
      Determines the location of message catalogues for	the processing of
      LC_MESSAGES.

  OPTARG
      On exit, this variable will contain the value of a flag-argumentm	if
      one was found, otherwise it is unset.

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

SEE ALSO

  Commands:  getopt(1),	ksh(1),	sh(1p)

  Routines:  getopt(3)

  Standards:  standards(5)