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.