getopt(3)

BEZEICHNUNG
getopt, optarg, optind, opterr, optopt - Befehlszeilenoptionen auswerten

BIBLIOTHEK
Standard-C-Bibliothek (libc, -lc)

ÜBERSICHT
#include <unistd.h>

int getopt(int argz, char *argv[],
           const char *optzeichenk);

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

    Mit Glibc erforderliche Feature-Test-Makros (siehe feature_test_macros(7)):

getopt():
    _POSIX_C_SOURCE >= 2 || _XOPEN_SOURCE

BESCHREIBUNG
Die Funktion getopt() wertet die Befehlszeilenoptionen aus. Ihre Argumente argz 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.

optzeichenk 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 optzeichenk 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 optzeichenk 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 optzeichenk ist, wird es als normale Option aufgefasst. Sollte in diesem Fall ein POSIXLY_CORRECT-Verhalten erforderlich sein, dann wird optzeichenk zwei »+«-Symbole enthalten. Falls das erste Zeichen von optzeichenk 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 optzeichenk 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 optfeh 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 optfeh einen von Null verschiedenen Wert).

•   Falls das erste Zeichen im optzeichenk (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.

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 optzeichenk enthalten war, wird »?« zurückgegeben. Falls getopt() auf eine Option trifft, der ein Argument fehlt, hängt der Rückgabewert vom ersten Zeichen in optzeichenk ab: Falls es ein »:« ist, wird »:« zurückgegeben; anderenfalls »?«.

UMGEBUNGSVARIABLEN

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

ATTRIBUTE
Siehe attributes(7) für eine Erläuterung der in diesem Abschnitt verwandten Ausdrücke.
Schnittstelle | Attribut | Wert
getopt() | Multithread-Fähigkeit | MT-Unsicher race:getopt env

VERSIONEN
POSIX spezifiziert, dass das Array-Argument argv vom Typ const sein soll, aber diese Funktionen permutieren ihre Elemente, außer die Umgebungsvariable POSIXLY_CORRECT ist gesetzt. const wird im eigentlichen Prototyp zur Kompatibilität mit anderen Systemen gesetzt, allerdings zeigt diese Seite den Kennzeichner nicht, um den Leser nicht durcheinanderzubringen.

STANDARDS

getopt()
    POSIX.1-2008.

    Die Verwendung von »+« und »-« in optzeichenk ist eine GNU-Erweiterung.

GESCHICHTE

getopt()
    POSIX.1-2001 und POSIX.2.

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.

Sehr alte Versionen von Glibc wurden von der Umgebungsvariablen _PID_GNU_nonoption_argv_flags_ (https://sourceware.org/git/?p=glibc.git;a=commitdiff;h=bf079e19f50d64aa5e05) beeinflusst.

ANMERKUNGEN
Ein Programm, das mehrere Argumentvektoren oder denselben Argumentvektor mehrfach auswertet und GNU-Erweiterungen wie beispielsweise »+« und »-« am Anfang von optzeichenk 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 optzeichenk 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 optzeichenk 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, "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, "Erwartete Argumente nach den Optionen\n");
            exit(EXIT_FAILURE);
        }

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

        /* Weiterer Code weggelassen */

        exit(EXIT_SUCCESS);
    }

SIEHE AUCH
getopt(1), getopt_long(3), getopt_long_only(3), 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.