


GETOPT(3)           Linux Programmer's Manual           GETOPT(3)


NNAAMMEE
       getopt - Parse command line options

SSYYNNOOPPSSIISS
       ##iinncclluuddee <<uunniissttdd..hh>>

       iinntt ggeettoopptt((iinntt _a_r_g_c,, cchhaarr ** ccoonnsstt _a_r_g_v_[_],,
                  ccoonnsstt cchhaarr **_o_p_t_s_t_r_i_n_g));;

       eexxtteerrnn cchhaarr **_o_p_t_a_r_g;;
       eexxtteerrnn iinntt _o_p_t_i_n_d,, _o_p_t_e_r_r,, _o_p_t_o_p_t;;

       ##iinncclluuddee <<ggeettoopptt..hh>>

       iinntt ggeettoopptt__lloonngg((iinntt _a_r_g_c,, cchhaarr ** ccoonnsstt _a_r_g_v_[_],,
                  ccoonnsstt cchhaarr **_o_p_t_s_t_r_i_n_g,,
                  ccoonnsstt ssttrruucctt ooppttiioonn **_l_o_n_g_o_p_t_s,, iinntt **_l_o_n_g_i_n_d_e_x));;

       iinntt ggeettoopptt__lloonngg__oonnllyy((iinntt _a_r_g_c,, cchhaarr ** ccoonnsstt _a_r_g_v_[_],,
                  ccoonnsstt cchhaarr **_o_p_t_s_t_r_i_n_g,,
                  ccoonnsstt ssttrruucctt ooppttiioonn **_l_o_n_g_o_p_t_s,, iinntt **_l_o_n_g_i_n_d_e_x));;

DDEESSCCRRIIPPTTIIOONN
       The  ggeettoopptt(())  function parses the command line arguments.
       Its arguments _a_r_g_c and _a_r_g_v are  the  argument  count  and
       array  as passed to the mmaaiinn(()) function on program invoca
       tion.  An element of _a_r_g_v that starts with `-' (and is not
       exactly "-" or "--") is an option element.  The characters
       of this element (aside from the initial  `-')  are  option
       characters.   If ggeettoopptt(()) is called repeatedly, it returns
       successively each of the option characters  from  each  of
       the option elements.

       If  ggeettoopptt(())  finds  another  option character, it returns
       that character, updating the external variable _o_p_t_i_n_d  and
       a  static  variable  _n_e_x_t_c_h_a_r  so  that  the  next call to
       ggeettoopptt(()) can resume the scan  with  the  following  option
       character or _a_r_g_v-element.

       If  there  are no more option characters, ggeettoopptt(()) returns
       EEOOFF.  Then _o_p_t_i_n_d is the index in _a_r_g_v of the first  _a_r_g_v-
       element that is not an option.

       _o_p_t_s_t_r_i_n_g  is  a  string  containing the legitimate option
       characters.  If such a character is followed by  a  colon,
       the  option  requires  an  argument,  so  ggeettoopptt  places a
       pointer to the following text in the same _a_r_g_v-element, or
       the  text  of  the following _a_r_g_v-element, in _o_p_t_a_r_g.  Two
       colons mean an option takes an optional arg; if  there  is
       text  in  the  current  _a_r_g_v-element,  it  is  returned in
       _o_p_t_a_r_g, otherwise _o_p_t_a_r_g is set to zero.  This  is  a  GNU
       extension.   If  _o_p_t_s_t_r_i_n_g  contains WW followed by a semi
       colon, then --WW ffoooo is treated as the  long  option  ----ffoooo.
       (The  --WW  option is reserved by POSIX.2 for implementation



GNU                         8 May 1998                          1





GETOPT(3)           Linux Programmer's Manual           GETOPT(3)


       extensions.)  This  behaviour  is  a  GNU  extension,  not
       available with libraries before GNU libc 2.

       By  default,  ggeettoopptt(()) permutes the contents of _a_r_g_v as it
       scans, so that eventually all the non-options are  at  the
       end.   Two other modes are also implemented.  If the first
       character of _o_p_t_s_t_r_i_n_g is `+' or the environment  variable
       POSIXLY_CORRECT  is  set,  then option processing stops as
       soon as a non-option  argument  is  encountered.   If  the
       first  character of _o_p_t_s_t_r_i_n_g is `-', then each non-option
       _a_r_g_v-element is handled as if it were the argument  of  an
       option  with  character code 1.  (This is used by programs
       that were written to expect options  and  other  _a_r_g_v-ele
       ments in any order and that care about the ordering of the
       two.)  The special argument `--' forces an end of  option-
       scanning regardless of the scanning mode.

       If  ggeettoopptt(())  does  not  recognize an option character, it
       prints an error message to stderr, stores the character in
       _o_p_t_o_p_t,  and returns `?'.  The calling program may prevent
       the error message by setting _o_p_t_e_r_r to 0.

       The ggeettoopptt__lloonngg(()) function works like ggeettoopptt(()) except that
       it  also  accepts long options, started out by two dashes.
       Long option names may be abbreviated if  the  abbreviation
       is unique or is an exact match for some defined option.  A
       long option may take a parameter, of the form  ----aarrgg==ppaarraamm
       or ----aarrgg ppaarraamm.

       _l_o_n_g_o_p_t_s  is a pointer to the first element of an array of
       ssttrruucctt ooppttiioonn declared in <<ggeettoopptt..hh>> as

          struct option {
              const char *name;
              int has_arg;
              int *flag;
              int val;
          };

       The meanings of the different fields are:

       _n_a_m_e   is the name of the long option.

       _h_a_s___a_r_g
              is: nnoo__aarrgguummeenntt (or 0) if the option does not  take
              an argument, rreeqquuiirreedd__aarrgguummeenntt (or 1) if the option
              requires an argument, or ooppttiioonnaall__aarrgguummeenntt  (or  2)
              if the option takes an optional argument.

       _f_l_a_g   specifies  how  results  are  returned  for  a long
              option.   If  _f_l_a_g  is  NNUULLLL,  then   ggeettoopptt__lloonngg(())
              returns _v_a_l.  (For example, the calling program may
              set _v_a_l to the equivalent short option  character.)
              Otherwise, ggeettoopptt__lloonngg(()) returns 0, and _f_l_a_g points



GNU                         8 May 1998                          2





GETOPT(3)           Linux Programmer's Manual           GETOPT(3)


              to a variable which is set to _v_a_l if the option  is
              found,  but  left  unchanged  if  the option is not
              found.

       _v_a_l    is the value to return, or to load into  the  vari
              able pointed to by _f_l_a_g.

       The  last  element  of  the  array  has  to be filled with
       zeroes.

       If _l_o_n_g_i_n_d_e_x is not NNUULLLL, it points to a variable which is
       set  to the index of the long option relative to _l_o_n_g_o_p_t_s.

       ggeettoopptt__lloonngg__oonnllyy(()) is like ggeettoopptt__lloonngg(()), but `-' as  well
       as  `--'  can  indicate  a long option.  If an option that
       starts with `-' (not `--') doesn't match  a  long  option,
       but  does  match  a  short option, it is parsed as a short
       option instead.

RREETTUURRNN VVAALLUUEE
       The ggeettoopptt(()) function returns the option character if  the
       option  was found successfully, `:' if there was a missing
       parameter for one of  the  options,  `?'  for  an  unknown
       option character, or EEOOFF for the end of the option list.

       ggeettoopptt__lloonngg(())   and  ggeettoopptt__lloonngg__oonnllyy(())  also  return  the
       option character when a short option is recognized.  For a
       long option, they return _v_a_l if _f_l_a_g is NNUULLLL, and 0 other
       wise.  Error and EOF returns are the same as for ggeettoopptt(()),
       plus  `?'  for an ambiguous match or an extraneous parame
       ter.

EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
       PPOOSSIIXXLLYY__CCOORRRREECCTT
              If this is set, then  option  processing  stops  as
              soon as a non-option argument is encountered.

       __<<PPIIDD>>__GGNNUU__nnoonnooppttiioonn__aarrggvv__ffllaaggss__
              This  variable  was used by bbaasshh 2.0 to communicate
              to GNU libc which  arguments  are  the  results  of
              wildcard  expansion and so should not be considered
              as options.  This behaviour  was  removed  in  bbaasshh
              version  2.01, but the support remains in GNU libc.

EEXXAAMMPPLLEE
       The following  example  program,  from  the  source  code,
       illustrates the use of ggeettoopptt__lloonngg(()) with most of its fea
       tures.

       #include <stdio.h>

       int
       main (argc, argv)
            int argc;



GNU                         8 May 1998                          3





GETOPT(3)           Linux Programmer's Manual           GETOPT(3)


            char **argv;
       {
         int c;
         int digit_optind = 0;

         while (1)
           {
             int this_option_optind = optind ? optind : 1;
             int option_index = 0;
             static struct option long_options[] =
             {
               {"add", 1, 0, 0},
               {"append", 0, 0, 0},
               {"delete", 1, 0, 0},
               {"verbose", 0, 0, 0},
               {"create", 1, 0, 'c'},
               {"file", 1, 0, 0},
               {0, 0, 0, 0}
             };

             c = getopt_long (argc, argv, "abc:d:012",
                        long_options, &option_index);
             if (c == -1)
            break;

             switch (c)
               {
               case 0:
                 printf ("option %s", long_options[option_index].name);
                 if (optarg)
                   printf (" with arg %s", optarg);
                 printf ("\n");
                 break;

               case '0':
               case '1':
               case '2':
                 if (digit_optind != 0 && digit_optind != this_option_optind)
                   printf ("digits occur in two different argv-elements.\n");
                 digit_optind = this_option_optind;
                 printf ("option %c\n", c);
                 break;

               case 'a':
                 printf ("option a\n");
                 break;

               case 'b':
                 printf ("option b\n");
                 break;

               case 'c':
                 printf ("option c with value `%s'\n", optarg);
                 break;



GNU                         8 May 1998                          4





GETOPT(3)           Linux Programmer's Manual           GETOPT(3)


               case 'd':
                 printf ("option d with value `%s'\n", optarg);
                 break;

               case '?':
                 break;

               default:
                 printf ("?? getopt returned character code 0%o ??\n", c);
               }
           }

         if (optind < argc)
           {
             printf ("non-option ARGV-elements: ");
             while (optind < argc)
             printf ("%s ", argv[optind++]);
             printf ("\n");
           }

         exit (0);
       }

BBUUGGSS
       This manpage is confusing.

       The POSIX.2 specification  of  ggeettoopptt(())  has  a  technical
       error  described  in  POSIX.2 Interpretation 150.  The GNU
       implementation (and probably  all  other  implementations)
       implements  the  correct behaviour rather than that speci
       fied.

CCOONNFFOORRMMIINNGG TTOO
       ggeettoopptt(()):
              POSIX.2,   provided   the   environment    variable
              POSIXLY_CORRECT is set.  Otherwise, the elements of
              _a_r_g_v aren't really const, because we permute  them.
              We  pretend  they're  const  in the prototype to be
              compatible with other systems.


















GNU                         8 May 1998                          5


