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

  man pages->OpenBSD man pages -> getopt (3)              
Title
Content
Arch
Section
 

GETOPT(3)

Contents


NAME    [Toc]    [Back]

     getopt - get option character  from  command  line  argument
list

SYNOPSIS    [Toc]    [Back]

     #include <unistd.h>

     extern char *optarg;
     extern int optind;
     extern int optopt;
     extern int opterr;
     extern int optreset;

     int
     getopt(int argc, char * const *argv, const char *optstring);

DESCRIPTION    [Toc]    [Back]

     The getopt() function incrementally parses  a  command  line
argument list
     argv and returns the next known option character.  An option
character is
     known if it has been specified in the string of accepted option characters,
 optstring.

     The  option  string optstring may contain the following elements: individual
 characters, characters followed by a colon,  and  characters followed by
     two  colons.   A  character followed by a single colon indicates that an argument
 is to follow the option on  the  command  line.   Two
colons indicates
     that the argument is optional--this is an extension not covered by POSIXFor
 example, an option string "x" recognizes an  option  -x,
and an option
     string  "x:"  recognizes an option and argument -x argument.
It does not
     matter to getopt()  if  a  following  argument  has  leading
whitespace.

     On  return  from  getopt(), optarg points to an option argument, if it is
     anticipated, and the variable optind contains the  index  to
the next argv
     argument for a subsequent call to getopt().

     The  variables  opterr and optind are both initialized to 1.
The optind
     variable may be set to another value before a set  of  calls
to getopt() in
     order to skip over more or less argv entries.

     In  order to use getopt() to evaluate multiple sets of arguments, or to
     evaluate a single set of arguments multiple times, the variable optreset
     must  be  set to 1 before the second and each additional set
of calls to
     getopt(), and the variable optind must be reinitialized.

     The getopt() function returns -1 when the argument  list  is
exhausted.
     The  interpretation  of  options in the argument list may be
cancelled by
     the option `--' (double dash) which causes getopt() to  signal the end of
     argument  processing  and  return -1.  When all options have
been processed
     (i.e., up to the first non-option  argument),  getopt()  returns -1.

RETURN VALUES    [Toc]    [Back]

     The  getopt() function returns the next known option character in
     optstring.  If getopt() encounters a character not found  in
optstring or
     if  it  detects  a  missing  option argument, it returns `?'
(question mark).
     If optstring has a leading `:' then a missing  option  argument causes `:'
     to be returned instead of `?'.  In either case, the variable
optopt is
     set to the character that caused the  error.   The  getopt()
function returns
 -1 when the argument list is exhausted.

ENVIRONMENT    [Toc]    [Back]

     POSIXLY_CORRECT    If set, a leading `-' in optstring is ignored.

EXAMPLES    [Toc]    [Back]

     extern char *optarg;
     extern int optind;
     int bflag, ch, fd;

     bflag = 0;
     while ((ch = getopt(argc, argv, "bf:")) != -1) {
             switch (ch) {
             case 'b':
                     bflag = 1;
                     break;
             case 'f':
                     if ((fd = open(optarg, O_RDONLY, 0)) < 0) {
                             (void)fprintf(stderr,
                                 "myname: %s: %s0,  optarg,  strerror(errno));
                             exit(1);
                     }
                     break;
             case '?':
             default:
                     usage();
             }
     }
     argc -= optind;
     argv += optind;

DIAGNOSTICS    [Toc]    [Back]

     If the getopt() function encounters a character not found in
the string
     optstring or detects a missing option argument it writes  an
error message
     to  stderr  and  returns `?'.  Setting opterr to a zero will
disable these
     error messages.  If optstring has a leading `:' then a missing option argument
  causes a `:' to be returned in addition to suppressing any error
     messages.

     Option arguments are allowed to begin with `-'; this is reasonable but
     reduces the amount of error checking possible.

SEE ALSO    [Toc]    [Back]

      
      
     getopt(1), getopt_long(3), getsubopt(3)

STANDARDS    [Toc]    [Back]

     The getopt() function implements a superset of the functionality specified
 by IEEE Std 1003.1 (``POSIX'').

     The following extensions are supported:

     o    The optreset variable was added to make it possible  to
call the
          getopt() function multiple times.

     o     If  the  first  character  of optstring is a plus sign
(`+'), it will be
          ignored.  This is for compatibility with GNU  getopt().

     o     If  the  first character of optstring is a dash (`-'),
non-options
          will be returned as arguments to the  option  character
`1'.  This is
          for compatibility with GNU getopt().

     o     A single dash (`-') may be specified as a character in
optstring,
          however it should never  have  an  argument  associated
with it.  This
          allows  getopt()  to  be used with programs that expect
`-' as an option
 flag.  This practice is wrong, and should  not  be
used in any
          current  development.  It is provided for backward compatibility
          only.  Care should be taken not to use `-' as the first
character in
          optstring   to  avoid  a  semantic  conflict  with  GNU
getopt() semantics
          (see above).  By default, a single dash causes getopt()
to return
          -1.

     Unlike  GNU  getopt(), OpenBSD does not permute the argument
vector to allow
 non-options to be interspersed with options on the  command line.
     Programs  requiring  this behavior should use getopt_long(3)
instead.  Because
 of this (and unlike GNU), the  OpenBSD  getopt()  supports optional
     arguments separated by whitespace.

HISTORY    [Toc]    [Back]

     The getopt() function appeared in 4.3BSD.

BUGS    [Toc]    [Back]

     The  getopt()  function was once specified to return EOF instead of -1.
     This was changed by IEEE Std  1003.2-1992  (``POSIX.2'')  to
decouple
     getopt() from <stdio.h>.

     It is possible to handle digits as option letters.  This allows getopt()
     to be used with programs that expect a number (``-3'') as an
option.
     This  practice  is wrong, and should not be used in any current development.
  It is provided for backward compatibility only.   The
following
     code fragment works in most cases.

           int ch;
           long length;
           char *p;

           while  ((ch = getopt(argc, argv, "0123456789")) != -1)
{
                   switch (ch) {
                   case '0': case '1': case '2': case  '3':  case
'4':
                   case  '5':  case '6': case '7': case '8': case
'9':
                           p = argv[optind - 1];
                           if (p[0] ==  '-'  &&  p[1]  ==  ch  &&
!p[2])
                                   length = ch - '0';
                           else
                                   length = strtol(argv[optind] +
1, NULL, 10);
                           break;
                   }
           }

OpenBSD     3.6                        December     17,      2002
[ Back ]
 Similar pages
Name OS Title
getopt_long OpenBSD get long options from command line argument list
getopt_long_only OpenBSD get long options from command line argument list
getopt_long FreeBSD get long options from command line argument list
getopt_long NetBSD get long options from command line argument list
pxfgetarg IRIX Returns a command-line argument
getarg IRIX return Fortran command-line argument
xargs HP-UX construct argument list(s) and execute command
xargs IRIX construct argument list(s) and execute command
getopt IRIX get option letter from argument vector
getopt Tru64 Get option letters from the argument vector
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service