unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 getopts(1)							  getopts(1)




 NAME
      getopts - parse utility (command) options

 SYNOPSIS
      getopts optstring name [arg ...]

 DESCRIPTION
      getopts is used to retrieve options and option-arguments from a list
      of parameters.

      Each time it is invoked, getopts 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, getopts places 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 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
      standard error; otherwise, 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
      processing.

      If an option-argument is missing:

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

	   +  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 the standard error.
	      This condition is considered to be an error detected in the
	      way arguments are 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, getopts exits with a return
      value greater than zero.	The shell variable OPTIND is set to the
      index of the first nonoption-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
      nonoption-arguments; the name variable is set to the question-mark



 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 getopts(1)							  getopts(1)




      character.  Any of the following identifies 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 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.

    Operands
      The following operands are supported:

	   optstring	  A string containing the option characters
			  recognized by the utility invoking getopts.  If a
			  character is followed by a colon (:), the option
			  will 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
			  will interpret 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. 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 will be stripped of the option
			  character and the -.	The first character in
			  optstring will determine how getopts will behave
			  if an option character is not known or an option-
			  argument is missing.

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

      getopts by default parses positional parameters passed to the invoking
      shell procedures.	 If args are given, they are parsed instead of the
      positional parameters.

 EXTERNAL INFLUENCES
    Environment Variable
      The following environment variable affects the execution of the
      getopts utility:

	   OPTIND	  Used by getopts as the index of the next argument
			  to be processed.



 Hewlett-Packard Company	    - 2 -   HP-UX Release 11i: November 2000






 getopts(1)							  getopts(1)




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

	   +  The invoking program name will be identified in the message.
	      The invoking program name will be the value of the shell
	      special parameter 0 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 will be identified and the invalid option character
	      will be identified in the message.

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

 EXAMPLES
      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.  Functions that use
      getopts to parse their arguments should save the value of OPTIND on
      entry and restore it before returning.  However, there will be cases
      when a function must change OPTIND for the calling shell.

      The following example script parses and displays its arguments:

	   aflag=
	   bflag=

	   while getopts ab: name
	       do
		   case $name in
		   a)



 Hewlett-Packard Company	    - 3 -   HP-UX Release 11i: November 2000






 getopts(1)							  getopts(1)




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

 SEE ALSO
      getopt(1), ksh(1), sh-posix(1), sh(1), getopt(3C).

 STANDARDS CONFORMANCE
      getopts: XPG4, POSIX.2































 Hewlett-Packard Company	    - 4 -   HP-UX Release 11i: November 2000