Provided by: manpages-de-dev_0.5-2ubuntu1_all bug

BEZEICHNUNG

       getopt - werte Kommandozeilenoptionen aus

Ü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.