*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> getopts (1)              



NAME    [Toc]    [Back]

       getopts - Parses utility options

SYNOPSIS    [Toc]    [Back]

       getopts optstring name [arg...]

STANDARDS    [Toc]    [Back]

       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 industry standards and associated tags.

OPTIONS    [Toc]    [Back]


OPERANDS    [Toc]    [Back]

       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.  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    [Toc]    [Back]

       The getopts utility is used to retrieve  flags  and  flagarguments
 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 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 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 processing;
 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-flagargument,
 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 questionmark
 (?) 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    [Toc]    [Back]

       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 ...  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    [Toc]    [Back]

       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    [Toc]    [Back]

       The  following exit values are returned: An option, specified
 or unspecified by optstring,  was  found.  Successful
       completion.   The  end  of  options  was encountered or an
       error occurred.

EXAMPLES    [Toc]    [Back]

       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
            ?)  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"


       The following environment variables affect  the  execution
       of  getopts: 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.  If  set  to  a
       non-empty  string  value,  overrides the values of all the
       other  internationalization  variables.   Determines   the
       locale  for  the  interpretation  of sequences of bytes of
       text data  as  characters  (for  example,  single-byte  as
       opposed  to  multibyte  characters  in arguments and input
       files).  Determines the locale used to affect  the  format
       and  contents  of  diagnostic messages written to standard
       error.  Determines the location of message catalogues  for
       the  processing  of  LC_MESSAGES.   On exit, this variable
       will contain the value of  a  flag-argumentm  if  one  was
       found,  otherwise  it  is unset.  This variable is used by
       the getopts utility as the index of the next  argument  to
       be processed.

SEE ALSO    [Toc]    [Back]

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

       Routines:  getopt(3)

       Standards:  standards(5)

[ Back ]
 Similar pages
Name OS Title
getopts HP-UX parse utility (command) options
ap Tru64 Parses addresses RFC 822-style
mattrib Tru64 mtools utility to change DOS file attribute options
getopt Tru64 Parses command line flags and arguments
espreport IRIX 0espreport is a utility provided for viewing various reports from ESP on the command line. This utility bypass
espconfig IRIX 0espconfig is a utility provided for the configuration ESP from the command line. This utility bypasses the we
menu_opts OpenBSD set and get menu options
getsockopt FreeBSD get and set options on sockets
set_form_opts OpenBSD set and get form options
menu_opts_off OpenBSD set and get menu options
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service