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.

"UBERSICHT

       #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 ubergeben.  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 zuruck.

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

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

       optstring  ist  ein  String,  der  die gultigen Optionszeichen enthalt.
       Wenn solche ein Zeichen von einem Doppelpunkt  gefolgt  wird,  benotigt
       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 zuruckgegeben, anderenfalls wird optarg
       auf Null gesetzt.  Dieses ist eine GNU-Erweiterung.  Wenn  optstring  W
       gefolgt   von   einem   Semikolon   enthalt,  wird  -W  foo  wie  --foo
       interpretiert.  (Die Option -W  ist  reserviert  von  POSIX.2  fur  die
       Implementierung  von  Erweiterungen.)   Dieses  Verhalten ist eine GNU-
       Erweiterung, die nicht verfugbar 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 unabhangig von der Suchmethode.

       Wenn   getopt()   ein   Optionszeichen   nicht   erkennt,   wird   eine
       Fehlernachricht  nach  stderr  ausgegeben,  das   Zeichen   in   optopt
       gespeichert  und  `?'  zuruckgegeben.  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  unterstutzt,  die  mit zwei Minuszeichen beginnen.
       Lange  Optionsnamen  durfen  abgekurzt  werden,  wenn   die   Abkurzung
       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  zuruckgegeben  werden  fur eine lange
              Option.  Wenn flag NULL ist, dann gibt getopt_long() val zuruck.
              (Zum  Beispiel  kann das aufrufende Programm val auf das Zeichen
              der  aquivalenten   Kurzoption   setzen.)    Anderenfalls   gibt
              getopt_long()  0  zuruck,  und flag zeigt auf eine Variable, die
              auf val gesetzt wird, wenn die Option  gefunden  wird,  und  die
              unverandert gelassen wird, wenn die Option nicht gefunden wird.

       val    ist  der  Wert,  der zuruckzugeben oder in die Variable zu laden
              ist, auf die flag zeigt.

       Das letzte Element des Feldes muss mit Nullen gefullt 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 `-' anfangt
       (,not  `--'),  zu  keiner  langen  Option passt, jedoch zu einer kurzen
       Option, so wird sie wie eine kurze Option behandelt.

R"UCKGABEWERT

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

       getopt_long()  und  getopt_long_only()  geben  auch  das Optionszeichen
       zuruck wenn eine kurze Option gefunden wurde.  Fur  eine  lange  Option
       geben  sie  val zuruck wenn flag NULL ist, anderenfalls 0.  Fehler- und
       EOF-Ruckgaben sind wie bei getopt(), zusatzlich  jedoch  `?'  fur  eine
       unzureichende Ubereinstimmung oder einen uberzahligen 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 geloscht, der Support dafur  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 zuruck ??\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()  enthalt  einen   technischen
       Fehler,  der  in  der POSIX.2-Interpretation 150 beschrieben wird.  Die
       GNU-Implementierung   (und    wahrscheinlich    auch    alle    anderen
       Implementierungen)  unterstutzen  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.