getopt(3) Library Functions Manual getopt(3) BEZEICHNUNG getopt, getopt_long, getopt_long_only, optarg, optind, opterr, optopt - Befehlszeilenoptionen auswerten BIBLIOTHEK Standard-C-Bibliothek (libc, -lc) UBERSICHT #include int getopt(int argc, char *argv[], const char *optstring); extern char *optarg; extern int optind, opterr, optopt; #include 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 ubergeben. 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 zuruck. Die Variable optind ist der Index des nachsten zu verarbeitenden Elements in argv. Das System initialisiert diesen Wert mit 1. Der Aufrufende kann ihn auf 1 zurucksetzen, 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 zuruck, wobei die externe Variable optind und eine statische Variable nextchar auf neuen Stand gesetzt werden, so dass der nachste Aufruf von getopt() die Suche mit dem folgenden Optionszeichen oder argv-Element fortsetzen kann. Falls es keine weiteren Optionszeichen gibt, gibt getopt() -1 zuruck. Dann ist optind der Index des ersten argv-Elementes in argv, das keine Option ist. optstring ist eine Zeichenkette, die die gultigen Optionszeichen enthalt. Ein berechtigtes Optionszeichen ist jedes sichtbar ascii(7)-Zeichen aus einem Byte (fur das isgraph(3) einen von Null verschiedenen Wert liefern wurde), das weder >>-<<, >>:<< noch >>;<< ist. Falls solch ein Zeichen von einem Doppelpunkt gefolgt wird, benotigt 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 zuruckgegeben, anderenfalls wird optarg auf numerisch Null gesetzt. Dieses ist eine GNU-Erweiterung. Falls optstring W gefolgt von einem Semikolon enthalt, wird -W foo als lange Option --foo interpretiert. (Die Option -W ist von POSIX.2 fur die Implementierung von Erweiterungen reserviert.) Dieses Verhalten ist eine GNU-Erweiterung, die nicht in Bibliotheken vor GNU Glibc 2 verfugbar war. Standardmassig vertauscht getopt() den Inhalt von argv beim Durchsuchen, so dass schliesslich 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 ware. (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 unabhangig 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: o Standardmassig gibt getopt() eine Fehlermeldung auf der Standardfehlerausgabe aus, stellt das fehlerhafte Optionszeichen in optopt und liefert >>?<< as Funktionsergebnis zuruck. o Falls der Aufrufende die globale Variable opterr auf Null gesetzt hat, dann gibt getopt() keine Fehlermeldung aus. Der Aufrufende kann durch Testen, ob der Funktionsruckgabewert >>?<< ist, ermitteln, ob es einen Fehler gab. (Standardmassig hat opterr einen von Null verschiedenen Wert). o Falls das erste Zeichen im optstring (nach einem optionalen >>+<< oder >>-<< wie oben beschrieben) ein Doppelpunkt (>>:<<) ist, dann gibt getopt() analog auch keine Fehlermeldung aus. Zusatzlich wird es >>:<< statt >>?<< zuruckliefern, um ein fehlendes Argument anzuzeigen. Dies ermoglicht es dem Aufrufenden, die zwei Arten von Fehlern zu unterscheiden. getopt_long() und getopt_long_only() Die Funktion getopt_long() arbeitet wie getopt(), ausser dass sie auch lange Optionsnamen unterstutzt, die mit zwei Minuszeichen beginnen. (Falls das Programm nur lange Optionen unterstutzt, dann sollte optstring als leere Zeichenkette ("") und nicht als NULL angegeben werden). Lange Optionsnamen durfen abgekurzt werden, wenn die Abkurzung 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 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 benotigt oder optional_argument (oder 2) falls die Option ein optionales Argument erwartet. flag gibt an, wie fur eine lange Option Ergebnisse zuruckgegeben werden. Falls flag NULL ist, dann gibt getopt_long() val zuruck. (Zum Beispiel kann das aufrufende Programm val auf das Zeichen der aquivalenten Kurzoption setzen.) Anderenfalls gibt getopt_long() 0 zuruck und flag zeigt auf eine Variable, die auf val gesetzt wird, falls die Option gefunden wird, und die unverandert gelassen wird, falls die Option nicht gefunden wird. val ist der Wert, der zuruckzugeben oder in die Variable zu laden ist, auf die flag zeigt. Das letzte Element des Feldes muss mit Nullen gefullt 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 >>-<< anfangt (nicht >>--<<), zu keiner langen Option passt, jedoch zu einer kurzen Option, so wird sie wie eine kurze Option behandelt. RUCKGABEWERT Falls eine Option erfolgreich gefunden wurde, gibt getopt() das Optionszeichen zuruck. Falls alle Befehlszeilenargumente erfolgreich ausgewertet wurden, gibt getopt() -1 zuruck. Falls getopt() ein Optionszeichen antrifft, das nicht in optstring enthalten war, wird >>?<< zuruckgegeben. Falls getopt() auf eine Option trifft, der ein Argument fehlt, hangt der Ruckgabewert vom ersten Zeichen in optstring ab: Falls es ein >>:<< ist, wird >>:<< zuruckgegeben; anderenfalls >>?<<. getopt_long() und getopt_long_only() geben auch das Optionszeichen zuruck, wenn eine kurze Option gefunden wurde. Fur eine lange Option geben sie val zuruck, wenn flag NULL ist, anderenfalls 0. Fehler- und -1-Ruckgaben sind wie bei getopt(), zusatzlich jedoch >>-<< fur eine unzureichende Ubereinstimmung oder einen uberzahligen Parameter. UMGEBUNGSVARIABLEN POSIXLY_CORRECT Falls sie gesetzt ist, dann stoppt die Optionsbearbeitung, sobald ein Argument auftritt, das keine Option ist. __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 unterstutzt. ATTRIBUTE Siehe attributes(7) fur eine Erlauterung der in diesem Abschnitt verwandten Ausdrucke. +-------------------+-------------------------+------------------------+ |Schnittstelle | Attribut | Wert | +-------------------+-------------------------+------------------------+ |getopt(), | Multithread-Fahigkeit | MT-Unsicher | |getopt_long(), | | 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, ausser die Umgebungsvariable POSIXLY_CORRECT ist gesetzt. const wird im eigentlichen Prototyp zur Kompatibilitat 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 alteren Implementierungen wurde getopt() in deklariert. SUSv1 gestattete die Deklaration entweder in oder . POSIX.1-1995 kennzeichnete die Verwendung von zu diesem Zweck als LEGACY. POSIX.1-2001 verlangt nicht, dass diese Deklaration in enthalten ist. ANMERKUNGEN Ein Programm, das mehrere Argumentvektoren oder denselben Argumentvektor mehrfach auswertet und GNU-Erweiterungen wie beispielsweise >>+<< und >>-<< am Anfang von optstring nutzen mochte oder zwischen den Auswertungen den Wert von POSIXLY_CORRECT andert, muss getopt() neu initialisieren, indem es optind auf 0 statt des traditionellen Wertes 1 setzt. (Das Rucksetzen auf 0 erzwingt den Aufruf einer internen Initialisierungsroutine, die erneut POSIXLY_CORRECT pruft und in optstring nach GNU-Erweiterungen sucht.) Befehlszeilenargumente werden streng in der Reihenfolge ausgewertet. Das bedeutet, dass eine Option, die ein Argument erwartet, das nachste Argument verwenden wird, unabhangig davon, ob das Argument ein korrekt angegebenes Optionsargument ist oder einfach nur die nachste 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 zugehorigen Wert und -t Wert, die einen zugehorigen Wert erwartet. #include #include #include 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 Funktionalitaten. #include #include /* fur printf */ #include /* fur 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) UBERSETZUNG Die deutsche Ubersetzung dieser Handbuchseite wurde von Patrick Rother , Martin Eberhard Schauer , Mario Blattermann und Helge Kreutzmann erstellt. Diese Ubersetzung ist Freie Dokumentation; lesen Sie die GNU General Public License Version 3 oder neuer bezuglich der Copyright-Bedingungen. Es wird KEINE HAFTUNG ubernommen. Wenn Sie Fehler in der Ubersetzung dieser Handbuchseite finden, schicken Sie bitte eine E-Mail an die Mailingliste der Ubersetzer . Linux man-pages 6.06 31. Oktober 2023 getopt(3)