Provided by: manpages-de-dev_2.5-1_all bug

BEZEICHNUNG

       getopt,    getopt_long,    getopt_long_only,    optarg,    optind,    opterr,   optopt   -
       Befehlszeilenoptionen auswerten

ÜBERSICHT

       #include <unistd.h>

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

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

       #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);

   Mit Glibc erforderliche Makros (siehe feature_test_macros(7)):

       getopt(): _POSIX_C_SOURCE >= 2 || _XOPEN_SOURCE
       getopt_long(), getopt_long_only(): _GNU_SOURCE

BESCHREIBUNG

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

       Die  Variable  optind  ist  der Index des nächsten zu verarbeitenden Elements in argv. Das
       System initialisiert diesen Wert mit 1. Der Aufrufende kann ihn auf 1 zurücksetzen, um das
       Durchsuchen  des  gleichen  argv  erneut  zu  beginnen  oder  beim Durchsuchen eines neuen
       Argumentenfeldes.

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

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

       optstring ist eine Zeichenkette, die die gültigen Optionszeichen enthält. Falls solch  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 erwartet; falls es Text  im  aktuellen  argv-Element  gibt,
       wird  er  in  optarg  zurückgegeben,  anderenfalls wird optarg auf numerisch Null gesetzt.
       Dieses ist eine GNU-Erweiterung. Falls optstring W gefolgt von  einem  Semikolon  enthält,
       wird  -W  foo als lange Option --foo interpretiert. (Die Option -W ist von POSIX.2 für die
       Implementierung von Erweiterungen reserviert.) Dieses Verhalten ist eine  GNU-Erweiterung,
       die nicht in Bibliotheken vor GNU Glibc 2 verfügbar war.

       Standardmäßig   vertauscht  getopt()  den  Inhalt  von  argv  beim  Durchsuchen,  so  dass
       schließlich  alle  Nichtoptionen  am  Ende  stehen.  Zwei  weitere  Modi  sind   ebenfalls
       implementiert.   Falls   das   erste   Zeichen   von   optstring  ein  '+'  ist  oder  die
       Umgebungsvariable POSIXLY_CORRECT gesetzt ist, dann stoppt die  Optionsbearbeitung  sobald
       ein Argument auftritt, das keine Option ist. Falls das erste Zeichen von optstring ein '-'
       ist, dann wird jedes Argument von argv, das keine Option ist,  so  behandelt,  als  ob  es
       Argument  einer  Option mit dem Zeichencode 1 wäre. (Dies wird von Programmen benutzt, die
       Optionen und andere argv-Elemente in beliebiger Reihenfolge erwarten, und die Wert auf die
       Reihenfolge  der  beiden  legen.)  Das besondere Argument »--« erzwingt die Beendigung der
       Suche nach Optionen unabhängig von der Suchmethode.

       Beim Verarbeiten der Optionsliste kann getopt() zwei Arten von Fehler  erkennen:  (1)  ein
       Optionszeichen,   das   nicht   in   optstring  angegeben  wurde  und  (2)  ein  fehlendes
       Optionsargument (d.h. eine Option am Ende der Befehlszeile ohne ein erwartetes  Argument).
       Solche Fehler werden wie folgt verarbeitet und berichtet:

       *  Standardmäßig  gibt  getopt()  eine  Fehlermeldung  auf  der Standardfehlerausgabe aus,
          stellt das fehlerhafte Optionszeichen in optopt und liefert  »?«  as  Funktionsergebnis
          zurück.

       *  Falls  der  Aufrufende  die  globale  Variable  opterr  auf Null gesetzt hat, dann gibt
          getopt()  keine  Fehlermeldung  aus.  Der  Aufrufende  kann  durch   Testen,   ob   der
          Funktionsrückgabewert  »?«  ist,  ermitteln, ob es einen Fehler gab. (Standardmäßig hat
          opterr einen von Null verschiedenen Wert).

       *  Falls das erste Zeichen im optstring (nach einem  optionalen  »+«  oder  »-«  wie  oben
          beschrieben)   ein  Doppelpunkt  (»:«)  ist,  dann  gibt  getopt()  analog  auch  keine
          Fehlermeldung aus. Zusätzlich wird es »:« statt »?«  zurückliefern,  um  ein  fehlendes
          Argument  anzuzeigen. Dies ermöglicht es dem Aufrufenden, die zwei Arten von Fehlern zu
          unterscheiden.

   getopt_long() und getopt_long_only()
       Die Funktion getopt_long() arbeitet wie getopt(), außer dass sie auch  lange  Optionsnamen
       unterstützt,  die  mit  zwei Minuszeichen beginnen. (Falls das Programm nur lange Optionen
       unterstützt, dann sollte  optstring  als  leere  Zeichenkette  (»«)  und  nicht  als  NULL
       angegeben  werden).  Lange  Optionsnamen  dürfen  abgekürzt  werden,  wenn  die  Abkürzung
       eindeutig ist oder genau einer definierten Option entspricht. Eine lange Option darf einen
       Parameter der Form --arg=param oder --arg param akzeptieren.

       longopts  ist  ein Zeiger auf das erste Element eines Feldes von Strukturen 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   (oder   0)   falls   die   Option   kein   Argument   erwartet,
              required_argument   (oder   1)   falls   die  Option  ein  Argument  benötigt  oder
              optional_argument (oder 2) falls die Option ein optionales Argument erwartet.

       flag   gibt an, wie für eine lange Option Ergebnisse zurückgegeben werden. Falls 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,
              falls die Option gefunden wird, und die unverändert gelassen wird, falls 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.

       Falls 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  '-' ebenso wie »--« eine lange
       Option anzeigen. Falls eine Option, die mit '-' anfängt (nicht  »--«),  zu  keiner  langen
       Option passt, jedoch zu einer kurzen Option, so wird sie wie eine kurze Option behandelt.

RÜCKGABEWERT

       Falls  eine  Option  erfolgreich  gefunden wurde, gibt getopt() das Optionszeichen zurück.
       Falls alle Befehlszeilenargumente erfolgreich ausgewertet wurden, gibt getopt() -1 zurück.
       Falls getopt() ein Optionszeichen antrifft, das nicht in optstring enthalten war, wird '?'
       zurückgegeben. Falls getopt() auf eine Option trifft, der ein Argument  fehlt,  hängt  der
       Rückgabewert  vom  ersten  Zeichen  in  optstring  ab:  Falls  es  ein  ':'  ist, wird ':'
       zurückgegeben; anderenfalls '?'.

       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 -1-Rückgaben sind wie bei getopt(), zusätzlich jedoch '-'  für
       eine unzureichende Übereinstimmung oder einen überzähligen Parameter.

UMGEBUNGSVARIABLEN

       POSIXLY_CORRECT
              Falls  sie  gesetzt  ist,  dann  stoppt die Optionsbearbeitung, sobald ein Argument
              auftritt, das keine Option ist.

       _<PID>_GNU_nonoption_argv_flags_
              Diese Variable wurde von der bash(1)-Version 2.0 genutzt, um der Glibc mitzuteilen,
              welche  Argumente  Ergebnis  der  Ersetzung  von  Platzhaltern  und somit nicht als
              Optionen anzusehen  sind.  Dieses  Verhalten  wurde  in  der  bash(1)-Version  2.01
              entfernt, wird aber weiterhin von der Glibc unterstützt.

ATTRIBUTE

       Siehe attributes(7) für eine Erläuterung der in diesem Abschnitt verwandten Ausdrücke.

       ┌─────────────────────────┬───────────────────────┬───────────────────────────┐
       │SchnittstelleAttributWert                      │
       ├─────────────────────────┼───────────────────────┼───────────────────────────┤
       │getopt(), getopt_long(), │ Multithread-Fähigkeit │ MT-Unsafe race:getopt env │
       │getopt_long_only()       │                       │                           │
       └─────────────────────────┴───────────────────────┴───────────────────────────┘

KONFORM ZU

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

              Die Verwendung von '+' und '-' in optstring ist eine GNU-Erweiterung.

              In  einigen älteren Implementierungen wurde getopt() in <stdio.h> deklariert. SUSv1
              gestattete die Deklaration entweder  in  <unistd.h>  oder  <stdio.h>.  POSIX.1-1995
              kennzeichnete die Verwendung von <stdio.h> zu diesem Zweck als LEGACY. POSIX.1-2001
              verlangt nicht, dass diese Deklaration in <stdio.h> enthalten ist.

       getopt_long() und getopt_long_only():
              Diese Funktionen sind GNU-Erweiterungen.

ANMERKUNGEN

       Ein  Programm,  das  mehrere  Argumentvektoren  oder  denselben  Argumentvektor   mehrfach
       auswertet  und  GNU-Erweiterungen  wie  beispielsweise '+' und '-' am Anfang von optstring
       nutzen möchte oder zwischen den Auswertungen den Wert  von  POSIXLY_CORRECT  ändert,  muss
       getopt()  neu  initialisieren,  indem  es  optind  auf 0 statt des traditionellen Wertes 1
       setzt. (Das Rücksetzen auf 0 erzwingt den Aufruf einer  internen  Initialisierungsroutine,
       die erneut POSIXLY_CORRECT prüft und in optstring nach GNU-Erweiterungen sucht.)

BEISPIEL

   getopt()
       Das  folgende  triviale  Beispielprogramm  verwendet getopt(), um zwei Programmoptionen zu
       verarbeiten: -n ohne zugehörigen Wert und -t Wert, die einen zugehörigen Wert erwartet.

       #include <unistd.h>
       #include <stdlib.h>
       #include <stdio.h>

       int
       main(int argc, char *argv[])
       {
           int flags, opt;
           int nsecs, tfnd;

           nsecs = 0;
           tfnd = 0;
           flags = 0;
           while ((opt = getopt(argc, argv, "nt:")) != -1) {
               switch (opt) {
               case 'n':
                   flags = 1;
                   break;
               case 't':
                   nsecs = atoi(optarg);
                   tfnd = 1;
                   break;
               default: /* '?' */
                   fprintf(stderr, "Verwendung: %s [-t nsecs] [-n] Name\n",
                           argv[0]);
                   exit(EXIT_FAILURE);
               }
           }

           printf("flags=%d; tfnd=%d; nsecs=%d; optind=%d\n",
                   flags, tfnd, nsecs, optind);

           if (optind >= argc) {
               fprintf(stderr,
                       "Nach den Optionen wurde ein Argument erwartet\n");
               exit(EXIT_FAILURE);
           }

           printf("name argument = %s\n", argv[optind]);

           /* Weiterer Code weggelassen */

           exit(EXIT_SUCCESS);
       }

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

       #include <stdio.h> /* für printf */ #include <stdlib.h> /* für exit */ #include <getopt.h>

       int main(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",     required_argument, 0,  0 },
                   {"append",  no_argument,       0,  0 },
                   {"delete",  required_argument, 0,  0 },
                   {"verbose", no_argument,       0,  0 },
                   {"create",  required_argument, 0, 'c'},
                   {"file",    required_argument, 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 (
                     "Zahlen in zwei verschiedenen argv-Elementen gefunden.\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 Zeichencode 0%o zurück ??\n", c);
               }
           }

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

           exit(EXIT_SUCCESS); }

SIEHE AUCH

       getopt(1), getsubopt(3)

KOLOPHON

       Diese  Seite  ist  Teil  der  Veröffentlichung  4.15  des  Projekts  Linux-man-pages. Eine
       Beschreibung des Projekts, Informationen, wie Fehler  gemeldet  werden  können  sowie  die
       aktuelle Version dieser Seite finden sich unter https://www.kernel.org/doc/man-pages/.

ÜBERSETZUNG

       Die  deutsche  Übersetzung  dieser  Handbuchseite wurde von Patrick Rother <krd@gulu.net>,
       Helge Kreutzmann <debian@helgefjell.de>, Martin Eberhard Schauer <Martin.E.Schauer@gmx.de>
       und Mario Blättermann <mario.blaettermann@gmail.com> erstellt.

       Diese  Übersetzung  ist  Freie  Dokumentation;  lesen  Sie  die GNU General Public License
       Version  3  oder  neuer  bezüglich  der  Copyright-Bedingungen.  Es  wird  KEINE   HAFTUNG
       übernommen.

       Wenn Sie Fehler in der Übersetzung dieser Handbuchseite finden, schicken Sie bitte eine E-
       Mail an <debian-l10n-german@lists.debian.org>.