Provided by: manpages-de-dev_0.10-1_all bug

BEZEICHNUNG

       getopt - werte Kommandozeilenoptionen aus

       Diese  Handbuchseite ist eventuell veraltet. Im Zweifelsfall ziehen Sie
       die englischsprachige Handbuchseite zu Rate, indem Sie

              man -LC 3 getopt

       eingeben.

ÜBERSICHT

       #include <unistd.h>

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

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

       #define _GNU_SOURCE
       #include <getopt.h>

       int getopt_long(int argc, char * const argv[],
                  const char *optstring,
                  const struct option *longopts, int *longindex);

       int getopt_long_only(int argc, char * const argv[],
                  const char *optstring,
                  const struct option *longopts, int *longindex);

BESCHREIBUNG

       Die Funktion  getopt()  wertet  die  Kommandozeilenoptionen  aus.  Ihre
       Argumente  argc und argv sind die Argumentanzahl und das Argumentenfeld
       wie zur Funktion main() bei Programmaufruf übergeben. Ein  Element  von
       argv  , dass mit `-' beginnt (und nicht exact "-" or "--") ist, ist ein
       Optionselement. Die Zeichen dieses Elementes (ohne das einleitende `-')
       sind Optionszeichen. Wenn getopt() wiederholt aufgerufen wird, gibt sie
       aufeinanderfolgend jedes der Optionszeichen  von  jedem  Optionselement
       zurück.

       Wenn  getopt()  ein  weiteres  Optionszeichen  findet,  gibt sie dieses
       Zeichen zurück, wobei die externe Variable optind  und  eine  statische
       Variable  nextchar  auf neuen Stand gesetzt werden, so dass der nächste
       Aufruf von getopt() die Suche mit  dem  folgenden  Optionszeichen  oder
       argv-Element fortsetzen kann.

       Wenn  es  keine  weiteren Optionszeichen gibt, gibt getopt() -1 zurück.
       Dann ist optind der Index in argv des ersten argv-Elementes, das  keine
       Option ist.

       optstring ist ein String, der die gültigen Optionszeichen enthält. Wenn
       solche ein Zeichen von einem Doppelpunkt gefolgt wird,  benötigt  diese
       Option  ein  Argument,  weswegen  getopt einen Zeiger auf den folgenden
       Text in dem selben argv-Element  oder  den  Text  des  folgenden  argv-
       Elementes  in  optarg platziert. Zwei Doppelpunkte bedeuten, dass diese
       Option ein optionales Argument nimmt; wenn es Text im  aktuellen  argv-
       Element,  wird er in optarg zurückgegeben, anderenfalls wird optarg auf
       Null gesetzt. Dieses ist eine GNU-Erweiterung. Wenn optstring W gefolgt
       von  einem Semikolon enthält, wird -W foo wie --foo interpretiert. (Die
       Option -W ist  reserviert  von  POSIX.2  für  die  Implementierung  von
       Erweiterungen.)  Dieses  Verhalten  ist eine GNU-Erweiterung, die nicht
       verfügbar war in Bibliotheken vor GNU libc 2.

       Per Vorgabe vertauscht getopt() den Inhalt von argv  beim  Durchsuchen,
       so  dass  eventuell alle Nichtoptionen am Ende stehen. Zwei andere Modi
       sind ebenfalls implementiert. Wenn das erste Zeichen von optstring  ein
       `+'  ist,  oder die Umgebungsvariable POSIXLY_CORRECT gesetzt ist, dann
       stoppt die Optionsbearbeitung sobald ein Argument auftritt, dass  keine
       Option ist. Wenn das erste Zeichen von optstring ein `-' ist, dann wird
       jedes Argument von argv, dass keine Option ist, behandelt als  wenn  es
       Argument  einer  Option mit dem Zeichencode 1 waere. (Dies wird benutzt
       von  Programmen,  die  Optionen  und  andere  argv-Elemente  in   einer
       Reihenfolge  erwarten,  und  die  Wert  auf  die Reihenfolge der beiden
       legen.) Das spezielle Argument `--' erzwingt die Beendigung  der  Suche
       nach Optionen unabhängig von der Suchmethode.

       Wenn   getopt()   ein   Optionszeichen   nicht   erkennt,   wird   eine
       Fehlernachricht  nach  stderr  ausgegeben,  das   Zeichen   in   optopt
       gespeichert  und  `?'  zurückgegeben.  Das aufrufende Programm kann die
       Fehlernachricht verhindern durch setzen von opterr auf 0.

       Die Funktion getopt_long() arbeitet wie getopt(), bis auf dass sie auch
       lange  Optionsnamen  unterstützt,  die  mit zwei Minuszeichen beginnen.
       Lange  Optionsnamen  dürfen  abgekürzt  werden,  wenn   die   Abkürzung
       eindeutig  ist,  oder  exact  einer definierten Option entspricht. Eine
       lange Option darf einen Parameter der Form --arg=param oder --arg param
       nehmen.

       longopts  ist  ein  Zeiger  auf  das  ersten  Element  eines Feldes der
       Struktur struct option, die in <getopt.h> deklariert ist als

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

       Die Bedeutungen der einzelnen Felder sind:

       name   ist der Name der langen Option.

       has_arg
              ist: no_argument (or 0) wenn die  Option  kein  Argument  nimmt,
              required_argument  (or  1) wenn die Option ein Argument braucht,
              oder optional_argument (or 2) wenn  die  Option  ein  optionales
              Argument nimmt.

       flag   gibt  an  wie  Ergebnisse  zurückgegeben  werden  für eine lange
              Option. Wenn flag NULL ist, dann gibt getopt_long() val  zurück.
              (Zum  Beispiel  kann das aufrufende Programm val auf das Zeichen
              der   äquivalenten   Kurzoption   setzen.)   Anderenfalls   gibt
              getopt_long()  0  zurück,  und flag zeigt auf eine Variable, die
              auf val gesetzt wird, wenn die Option  gefunden  wird,  und  die
              unverändert gelassen wird, wenn die Option nicht gefunden wird.

       val    ist  der  Wert,  der zurückzugeben oder in die Variable zu laden
              ist, auf die flag zeigt.

       Das letzte Element des Feldes muss mit Nullen gefüllt werden.

       Wenn longindex nicht NULL ist, zeigt er auf eine Variable,  welche  auf
       den Index der langen Option relativ zu longopts gesetzt wird.

       getopt_long_only()  ist  wie  getopt_long(),  jedoch kann `-' genau wie
       `--' eine lange Option anzeigen. Wenn eine Option, die mit `-'  anfängt
       (,not  `--'),  zu  keiner  langen  Option passt, jedoch zu einer kurzen
       Option, so wird sie wie eine kurze Option behandelt.

RÜCKGABEWERT

       Die Funktion getopt() gibt das Optionszeichen zurück  wenn  die  Option
       gefunden  wurde,  `:'  wenn ein Parameter fehlte für eine der Optionen,
       `?' für ein unbekanntes  Optionszeichen,  oder  -1  für  das  Ende  der
       Optionsliste.

       getopt_long()  und  getopt_long_only()  geben  auch  das Optionszeichen
       zurück wenn eine kurze Option gefunden wurde.  Für  eine  lange  Option
       geben  sie  val  zurück wenn flag NULL ist, anderenfalls 0. Fehler- und
       EOF-Rückgaben sind wie bei getopt(), zusätzlich  jedoch  `?'  für  eine
       unzureichende Übereinstimmung oder einen überzähligen Parameter.

UMGEBUNGSVARIABLEN

       POSIXLY_CORRECT
              Wenn dies gesetzt ist, dann stoppt die Optionsbearbeitung sobald
              eine Argument auftritt, das keine Option ist.

       _<PID>_GNU_nonoption_argv_flags_
              Diese Variable wurde in bash 2.0 verwendet, um mit der GNU  libc
              zu  kommunizieren  und  ihr  mitzuteilen,  welche  Argumente die
              Ergebnisse von Wildcard-Expandierungen sind und daher nicht  als
              Optionen  verstanden  werden  sollten. Dieses Verhalten wurde in
              bash 2.01 wieder gelöscht, der Support dafür  bleibt  jedoch  in
              der GNU libc enthalten.

BEISPIEL

       Das   folgende   Beispielprogramm  veranschaulicht  die  Benutzung  von
       getopt_long() mit der meisten ihrer Eigenschaften.

       #include <stdio.h>

       int
       main (argc, argv)
            int argc;
            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 (" mit Argument %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 mit Wert `%s'\n", optarg);
                 break;

               case 'd':
                 printf ("Option d mit Wert `%s'\n", optarg);
                 break;

               case '?':
                 break;

               default:
                 printf ("?? getopt lieferte Zeichcode 0%o zurück ??\n", c);
               }
           }

         if (optind < argc)
           {
             printf ("Nichtoptionselemente von ARGV: ");
             while (optind < argc)
             printf ("%s ", argv[optind++]);
             printf ("\n");
           }

         exit (0);
       }

FEHLER

       Die  POSIX.2-Spezifikation  von  getopt()  enthält  einen   technischen
       Fehler,  der  in  der  POSIX.2-Interpretation 150 beschrieben wird. Die
       GNU-Implementierung   (und    wahrscheinlich    auch    alle    anderen
       Implementierungen)  unterstützen  das  korrekte  Verhalten  anstatt des
       spezifizierten.

KONFORM ZU

       getopt():
              POSIX.2, vorausgesetzt,  die  Umgebungsvariable  POSIXLY_CORRECT
              ist  gesetzt.  Anderenfalls  sind  die  Elemente  von argv nicht
              wirklich  konstant,  da  wir  sie  vertauschen.  Wir  geben   im
              Prototypen  vor,  sie  seien  konstant, um kompatibel zu anderen
              Systemen zu sein.