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

FreeBSD Manual Pages

  
 
  

home | help
getopts(1)		    General Commands Manual		    getopts(1)

NAME
       getopts - parse utility (command) options

SYNOPSIS
       optstring name [arg ...]

DESCRIPTION
       is used to retrieve options and option-arguments	from a list of parame-
       ters.

       Each time it is invoked,	places the value of the	 next  option  in  the
       shell variable specified	by the operand and the index of	the next argu-
       ment to be processed in the shell variable Whenever the	shell  is  in-
       voked, is initialized to	1.

       When  the  option  requires  an option-argument,	places it in the shell
       variable	If no option was found,	or if the option that was  found  does
       not have	an option-argument, 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 is set to the  op-
       tion  character found, but no output is written to standard error; oth-
       erwise, the shell variable is unset and a diagnostic message is written
       to  standard  error.   This  condition is considered to be an error de-
       tected in the way arguments were	presented to the invoking application,
       but is not an error in 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 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 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 processing; a diagnostic message  is  written
		 as stated, but	the exit status	is zero.

       When  the  end  of  options  is	encountered, exits with	a return value
       greater than zero.  The shell variable is set to	the index of the first
       nonoption-argument, where the first argument is considered to be	an op-
       tion argument if	there are no other non-option arguments	appearing  be-
       fore it,	or the value + 1 if there are no nonoption-arguments; the name
       variable	is set to the question-mark 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 and are local to the	caller of and are not exported
       by default.

       The  shell  variable specified by the name operand, and affect the cur-
       rent shell execution environment.

   Operands
       The following operands are supported:

	      optstring	     A string containing the option characters	recog-
			     nized  by	the utility invoking 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 will interpret the	 char-
			     acters  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  is	 invoked. The characters ques-
			     tion-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-argu-
			     ment is not supplied as a separate	argument  from
			     the  option  character,  the  value  in  will  be
			     stripped of the  option  character	 and  the  The
			     first  character  in optstring will determine how
			     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 to
			     the option	character that was found.

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

EXTERNAL INFLUENCES
   Environment Variable
       The following environment variable affects the execution	of  the	 util-
       ity:

	      Used by	     as	 the  index  of	 the  next argument to be pro-
			     cessed.

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:

	      o	 The invoking program name will	be identified in the  message.
		 The invoking program name will	be the value of	the shell spe-
		 cial parameter	0 at the time the utility is invoked.  A  name
		 equivalent to:

		 may be	used.

	      o	 If  an	 option	 is found that was not specified in optstring,
		 this error will be identified and the invalid option  charac-
		 ter will be identified	in the message.

	      o	 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 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:

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

       Note that shell functions share with the	calling	shell even though  the
       positional  parameters  are changed.  Functions that use	to parse their
       arguments should	save the value of on entry and restore it  before  re-
       turning.	  However, there will be cases when a function must change for
       the calling shell.

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

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

STANDARDS CONFORMANCE
								    getopts(1)

NAME | SYNOPSIS | DESCRIPTION | EXTERNAL INFLUENCES | ERRORS | EXAMPLES | SEE ALSO | STANDARDS CONFORMANCE

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

home | help