getopts man page on Gentoo

Man page or keyword search:  
man Server   6889 pages
apropos Keyword Search (all sections)
Output format
Gentoo logo
[printable version]

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

PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the	 corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.

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
       POSIX.1‐2008, 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 out‐
       put  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  considered to be an error
       detected in the way arguments were presented to the  invoking  applica‐
       tion, 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 vari‐
	   able 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>  character,	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 operand, or the value "$#"+1 if	 there
       are  no operands; the name variable shall be set to the <question-mark>
       character. Any of the following shall identify the end of options:  the
       first "−−" argument that is not an option-argument, finding an argument
       that is not an option-argument and  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 Section 2.12,
       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.

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 charac‐
		 ters following an option character requiring arguments as  an
		 argument  whether  or	not  this  is  done.  An explicit null
		 option-argument 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 Interfaces volume  of
		 POSIX.1‐2008.)	 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 pro‐
		 duces unspecified results. If the option-argument is not sup‐
		 plied	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 parameters.

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 vari‐
		 ables that are unset or null. (See the Base Definitions  vol‐
		 ume  of POSIX.1‐2008, Section 8.2, Internationalization Vari‐
		 ables 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 internationalization 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	 arguments  and	 input
		 files).

       LC_MESSAGES
		 Determine the locale that should be used to affect the format
		 and contents  of  diagnostic  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 argument 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 for‐
       mat:

	*  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 Section 2.5.2, 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 iden‐
	   tified 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 identified 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>
       characters.

       The  OPTARG variable is not mentioned in the ENVIRONMENT VARIABLES sec‐
       tion 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 optstring  op‐
       erand,  it disables diagnostics concerning missing option-arguments and
       unexpected option characters. This replaces the use of the OPTERR vari‐
       able 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  implementa‐
       tions  with  superior  (``friendlier'') formats objected to the formats
       used by some historical implementations. The standard  developers  con‐
       sidered	it important that the information in the messages used be uni‐
       form 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() function, 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 formats, frequently not even indicating the option char‐
       acter found in error.

FUTURE DIRECTIONS
       None.

SEE ALSO
       Section 2.5.2, Special Parameters

       The  Base  Definitions  volume  of POSIX.1‐2008, Chapter 8, Environment
       Variables, Section 12.2, Utility Syntax Guidelines

       The System Interfaces volume of POSIX.1‐2008, getopt()

COPYRIGHT
       Portions of this text are reprinted and reproduced in  electronic  form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX),	The  Open  Group  Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
       cal and Electronics Engineers,  Inc  and	 The  Open  Group.   (This  is
       POSIX.1-2008  with  the	2013  Technical Corrigendum 1 applied.) 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 original Standard can be  obtained	online
       at http://www.unix.org/online.html .

       Any  typographical  or  formatting  errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files  to  man page format. To report such errors, see https://www.ker‐
       nel.org/doc/man-pages/reporting_bugs.html .

IEEE/The Open Group		     2013			   GETOPTS(1P)
[top]

List of man pages available for Gentoo

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net