Provided by: manpages-de-dev_4.21.0-2_all bug

BEZEICHNUNG

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

BIBLIOTHEK

       Standard-C-Bibliothek (libc, -lc)

Ü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 Feature-Test-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 »-« oder »--«)  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. Ein berechtigtes
       Optionszeichen  ist  jedes  sichtbar  ascii(7)-Zeichen  aus einem Byte (für das isgraph(3)
       einen von Null verschiedenen Wert liefern würde), das weder »-«, »:« noch »;«  ist.  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  Suchmodi  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  »+« nicht das erste Zeichen von
       optstring ist,  wird  es  als  normale  Option  aufgefasst.  Sollte  in  diesem  Fall  ein
       POSIXLY_CORRECT-Verhalten   erforderlich   sein,  dann  wird  optstring  zwei  »+«-Symbole
       enthalten. 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()       │                       │                                       │
       └─────────────────────────┴───────────────────────┴───────────────────────────────────────┘

STANDARDS

       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  diese  Funktionen  sie  vertauschen.  Trotzdem  wird  const im Prototyp
              verwandt, 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.)

       Befehlszeilenargumente werden streng in der Reihenfolge ausgewertet.  Das  bedeutet,  dass
       eine  Option,  die  ein Argument erwartet, das nächste Argument verwenden wird, unabhängig
       davon, ob das Argument ein korrekt angegebenes Optionsargument ist oder  einfach  nur  die
       nächste  Option  (falls  der  Benutzer  die  Befehlszeile  falsch  angegeben  hat).  Falls
       beispielsweise optstring als »1n:«  festgelegt  ist  und  der  Benutzer  die  Befehlszeile
       inkorrekt  als prog -n -1 angibt, dann wird der Option -n der optarg-Wert »-1« gegeben und
       die Option -1 wird als nicht angegeben betrachtet.

BEISPIELE

   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 <stdio.h>
       #include <stdlib.h>
       #include <unistd.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, "Aufruf: %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 Funktionalitäten.

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

       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)

ÜBERSETZUNG

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

       Diese Übersetzung ist Freie Dokumentation;  lesen  Sie  die  GNU  General  Public  License
       Version  3 ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ 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 die Mailingliste der Übersetzer ⟨debian-l10n-german@lists.debian.org⟩.