getopt(3) optopt

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

Falls 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 durch Setzen von opterr auf 0 verhindern.

Falls getopt() ein Optionszeichen in argv findet, das nicht in optstring enthalten war oder ein fehlendes Optionsargument erkennt, gibt sie '?' zurück und setzt die externe Variable optopt auf das aktuelle Optionszeichen. Falls das erste Zeichen (einem beliebigen optionalen '+' oder '-' folgend wie oben beschrieben) von optstring ein Doppelpunkt (':') ist, gibt getopt() ':' anstelle von '?' zurück, um ein fehlendes Optionsargument anzuzeigen. Falls ein Fehler entdeckt wurde, das erste Zeichen von optstring kein Doppelpunkt und die externe Variable opterr von (dem Standardwert) null verschieden ist, gibt getopt() eine Fehlermeldung aus.

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(), getopt_long_only() Multithread-FähigkeitMT-Unsafe race:getopt env

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-2001 kennzeichnete die Verwendung von <stdio.h> zu diesem Zweck als LEGACY. POSIX.1-2001 gestattet 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);
}

KOLOPHON

Diese Seite ist Teil der Veröffentlichung 4.06 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 <[email protected]>, Helge Kreutzmann <[email protected]>, Martin Eberhard Schauer <[email protected]> und Mario Blättermann <[email protected]> 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 <[email protected]>.

TRANSLATIONS

SIEHE AUCH

LAST GESUCHT