Provided by: manpages-de-dev_4.23.1-1_all 
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 *argv[],
const char *optstring);
extern char *optarg;
extern int optind, opterr, optopt;
#include <getopt.h>
int getopt_long(int argc, char *argv[],
const char *optstring,
const struct option *longopts, int *longindex);
int getopt_long_only(int argc, char *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.
┌─────────────────────────┬───────────────────────┬───────────────────────────────────────┐
│Schnittstelle │ Attribut │ Wert │
├─────────────────────────┼───────────────────────┼───────────────────────────────────────┤
│getopt(), getopt_long(), │ Multithread-Fähigkeit │ MT-Unsicher race:getopt env │
│getopt_long_only() │ │ │
└─────────────────────────┴───────────────────────┴───────────────────────────────────────┘
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.
getopt_long()
getopt_long_only()
GNU.
Die Verwendung von »+« und »-« in optstring 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.
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, "Usage: %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, "Expected argument after options\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(" with arg %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 with value '%s'\n", optarg);
break;
case 'd':
printf("option d with value '%s'\n", optarg);
break;
case '?':
break;
default:
printf("?? getopt returned character code 0%o ??\n", c);
}
}
if (optind < argc) {
printf("non-option ARGV-elements: ");
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⟩.