.\" -*- coding: UTF-8 -*- .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) .\" and Copyright 2006-2008, Michael Kerrisk .\" .\" %%%LICENSE_START(VERBATIM) .\" Permission is granted to make and distribute verbatim copies of this .\" manual provided the copyright notice and this permission notice are .\" preserved on all copies. .\" .\" Permission is granted to copy and distribute modified versions of this .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. .\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from .\" the use of the information contained herein. The author(s) may not .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. .\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" %%%LICENSE_END .\" .\" Modified Sat Jul 24 19:27:50 1993 by Rik Faith (faith@cs.unc.edu) .\" Modified Mon Aug 30 22:02:34 1995 by Jim Van Zandt .\" longindex is a pointer, has_arg can take 3 values, using consistent .\" names for optstring and longindex, "\n" in formats fixed. Documenting .\" opterr and getopt_long_only. Clarified explanations (borrowing heavily .\" from the source code). .\" Modified 8 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk) .\" Modified 990715, aeb: changed `EOF' into `-1' since that is what POSIX .\" says; moreover, EOF is not defined in . .\" Modified 2002-02-16, joey: added information about nonexistent .\" option character and colon as first option character .\" Modified 2004-07-28, Michael Kerrisk .\" Added text to explain how to order both '[-+]' and ':' at .\" the start of optstring .\" Modified 2006-12-15, mtk, Added getopt() example program. .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH GETOPT 3 "9. Juni 2020" GNU Linux\-Programmierhandbuch .SH BEZEICHNUNG getopt, getopt_long, getopt_long_only, optarg, optind, opterr, optopt \- Befehlszeilenoptionen auswerten .SH ÜBERSICHT .nf \fB#include \fP .PP \fBint getopt(int \fP\fIargc\fP\fB, char * const \fP\fIargv[]\fP\fB,\fP \fB const char *\fP\fIoptstring\fP\fB);\fP .PP \fBextern char *\fP\fIoptarg\fP\fB;\fP \fBextern int \fP\fIoptind\fP\fB, \fP\fIopterr\fP\fB, \fP\fIoptopt\fP\fB;\fP .PP \fB#include \fP .PP \fBint getopt_long(int \fP\fIargc\fP\fB, char * const \fP\fIargv[]\fP\fB,\fP \fB const char *\fP\fIoptstring\fP\fB,\fP \fB const struct option *\fP\fIlongopts\fP\fB, int *\fP\fIlongindex\fP\fB);\fP .PP \fBint getopt_long_only(int \fP\fIargc\fP\fB, char * const \fP\fIargv[]\fP\fB,\fP \fB const char *\fP\fIoptstring\fP\fB,\fP \fB const struct option *\fP\fIlongopts\fP\fB, int *\fP\fIlongindex\fP\fB);\fP .fi .PP .RS -4 Mit Glibc erforderliche Makros (siehe \fBfeature_test_macros\fP(7)): .ad l .RE .PP \fBgetopt\fP(): _POSIX_C_SOURCE\ >=\ 2 || _XOPEN_SOURCE .br \fBgetopt_long\fP(), \fBgetopt_long_only\fP(): _GNU_SOURCE .ad b .SH BESCHREIBUNG Die Funktion \fBgetopt\fP() wertet die Befehlszeilenoptionen aus. Ihre Argumente \fIargc\fP und \fIargv\fP sind die Argumentanzahl und das Argumentenfeld wie zur Funktion \fBmain\fP() bei Programmaufruf übergeben. Ein Element von \fIargv\fP, das mit \(aq\-\(aq beginnt (und nicht exakt »\-« or »\-\-«) ist, ist ein Optionselement. Die Zeichen dieses Elementes (ohne das einleitende \(aq\-\(aq) sind Optionszeichen. Falls \fBgetopt\fP() wiederholt aufgerufen wird, gibt sie aufeinanderfolgend jedes der Optionszeichen von jedem Optionselement zurück. .PP Die Variable \fIoptind\fP ist der Index des nächsten zu verarbeitenden Elements in \fIargv\fP. Das System initialisiert diesen Wert mit 1. Der Aufrufende kann ihn auf 1 zurücksetzen, um das Durchsuchen des gleichen \fIargv\fP erneut zu beginnen oder beim Durchsuchen eines neuen Argumentenfeldes. .PP Falls \fBgetopt\fP() ein weiteres Optionszeichen findet, gibt sie dieses Zeichen zurück, wobei die externe Variable \fIoptind\fP und eine statische Variable \fInextchar\fP auf neuen Stand gesetzt werden, so dass der nächste Aufruf von \fBgetopt\fP() die Suche mit dem folgenden Optionszeichen oder \fIargv\fP\-Element fortsetzen kann. .PP Falls es keine weiteren Optionszeichen gibt, gibt \fBgetopt\fP() \-1 zurück. Dann ist \fIoptind\fP der Index des ersten \fIargv\fP\-Elementes in \fIargv\fP, das keine Option ist. .PP \fIoptstring\fP 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 \fBgetopt\fP() einen Zeiger auf den folgenden Text in dem selben \fIargv\fP\-Element oder den Text des folgenden \fIargv\fP\-Elementes in \fIoptarg\fP platziert. Zwei Doppelpunkte bedeuten, dass diese Option ein optionales Argument erwartet; falls es Text im aktuellen \fIargv\fP\-Element gibt, wird er in \fIoptarg\fP zurückgegeben, anderenfalls wird \fIoptarg\fP auf numerisch Null gesetzt. Dieses ist eine GNU\-Erweiterung. Falls \fIoptstring\fP \fBW\fP gefolgt von einem Semikolon enthält, wird \fB\-W foo\fP als lange Option \fB\-\-foo\fP interpretiert. (Die Option \fB\-W\fP 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. .PP Standardmäßig vertauscht \fBgetopt\fP() den Inhalt von \fIargv\fP beim Durchsuchen, so dass schließlich alle Nichtoptionen am Ende stehen. Zwei weitere Suchmodi sind ebenfalls implementiert. Falls das erste Zeichen von \fIoptstring\fP ein \(aq+\(aq ist oder die Umgebungsvariable \fBPOSIXLY_CORRECT\fP gesetzt ist, dann stoppt die Optionsbearbeitung sobald ein Argument auftritt, das keine Option ist. Falls das erste Zeichen von \fIoptstring\fP ein \(aq\-\(aq ist, dann wird jedes Argument von \fIargv\fP, 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 \fIargv\fP\-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. .PP Beim Verarbeiten der Optionsliste kann \fBgetopt\fP() zwei Arten von Fehler erkennen: (1) ein Optionszeichen, das nicht in \fIoptstring\fP 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: .IP * 3 Standardmäßig gibt \fBgetopt\fP() eine Fehlermeldung auf der Standardfehlerausgabe aus, stellt das fehlerhafte Optionszeichen in \fIoptopt\fP und liefert »?« as Funktionsergebnis zurück. .IP * Falls der Aufrufende die globale Variable \fIopterr\fP auf Null gesetzt hat, dann gibt \fBgetopt\fP() keine Fehlermeldung aus. Der Aufrufende kann durch Testen, ob der Funktionsrückgabewert »?« ist, ermitteln, ob es einen Fehler gab. (Standardmäßig hat \fIopterr\fP einen von Null verschiedenen Wert). .IP * .\" Falls das erste Zeichen im \fIoptstring\fP (nach einem optionalen »+« oder »\-« wie oben beschrieben) ein Doppelpunkt (»:«) ist, dann gibt \fBgetopt\fP() 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. .SS "getopt_long() und getopt_long_only()" Die Funktion \fBgetopt_long\fP() arbeitet wie \fBgetopt\fP(), außer dass sie auch lange Optionsnamen unterstützt, die mit zwei Minuszeichen beginnen. (Falls das Programm nur lange Optionen unterstützt, dann sollte \fIoptstring\fP 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 \fB\-\-arg=param\fP oder \fB\-\-arg param\fP akzeptieren. .PP \fIlongopts\fP ist ein Zeiger auf das erste Element eines Feldes von Strukturen \fBstruct option\fP, die in \fB\fP deklariert ist als .PP .in +4n .EX struct option { const char *name; int has_arg; int *flag; int val; }; .EE .in .PP Die Bedeutungen der einzelnen Felder sind: .TP \fIname\fP ist der Name der langen Option. .TP \fIhas_arg\fP ist: \fBno_argument\fP (oder 0) falls die Option kein Argument erwartet, \fBrequired_argument\fP (oder 1) falls die Option ein Argument benötigt oder \fBoptional_argument\fP (oder 2) falls die Option ein optionales Argument erwartet. .TP \fIflag\fP gibt an, wie für eine lange Option Ergebnisse zurückgegeben werden. Falls \fIflag\fP NULL ist, dann gibt \fBgetopt_long\fP() \fIval\fP zurück. (Zum Beispiel kann das aufrufende Programm \fIval\fP auf das Zeichen der äquivalenten Kurzoption setzen.) Anderenfalls gibt \fBgetopt_long\fP() 0 zurück und \fIflag\fP zeigt auf eine Variable, die auf \fIval\fP gesetzt wird, falls die Option gefunden wird, und die unverändert gelassen wird, falls die Option nicht gefunden wird. .TP \fIval\fP ist der Wert, der zurückzugeben oder in die Variable zu laden ist, auf die \fIflag\fP zeigt. .PP Das letzte Element des Feldes muss mit Nullen gefüllt werden. .PP Falls \fIlongindex\fP nicht \fBNULL\fP ist, zeigt er auf eine Variable, welche auf den Index der langen Option relativ zu \fIlongopts\fP gesetzt wird. .PP \fBgetopt_long_only\fP() ist wie \fBgetopt_long\fP(), jedoch kann \(aq\-\(aq ebenso wie »\-\-« eine lange Option anzeigen. Falls eine Option, die mit \(aq\-\(aq anfängt (nicht »\-\-«), zu keiner langen Option passt, jedoch zu einer kurzen Option, so wird sie wie eine kurze Option behandelt. .SH RÜCKGABEWERT Falls eine Option erfolgreich gefunden wurde, gibt \fBgetopt\fP() das Optionszeichen zurück. Falls alle Befehlszeilenargumente erfolgreich ausgewertet wurden, gibt \fBgetopt\fP() \-1 zurück. Falls \fBgetopt\fP() ein Optionszeichen antrifft, das nicht in \fIoptstring\fP enthalten war, wird \(aq?\(aq zurückgegeben. Falls \fBgetopt\fP() auf eine Option trifft, der ein Argument fehlt, hängt der Rückgabewert vom ersten Zeichen in \fIoptstring\fP ab: Falls es ein \(aq:\(aq ist, wird \(aq:\(aq zurückgegeben; anderenfalls \(aq?\(aq. .PP \fBgetopt_long\fP() und \fBgetopt_long_only\fP() geben auch das Optionszeichen zurück, wenn eine kurze Option gefunden wurde. Für eine lange Option geben sie \fIval\fP zurück, wenn \fIflag\fP \fBNULL\fP ist, anderenfalls 0. Fehler\- und \-1\-Rückgaben sind wie bei \fBgetopt\fP(), zusätzlich jedoch \(aq\-\(aq für eine unzureichende Übereinstimmung oder einen überzähligen Parameter. .SH UMGEBUNGSVARIABLEN .TP \fBPOSIXLY_CORRECT\fP Falls sie gesetzt ist, dann stoppt die Optionsbearbeitung, sobald ein Argument auftritt, das keine Option ist. .TP \fB__GNU_nonoption_argv_flags_\fP Diese Variable wurde von der \fBbash\fP(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 \fBbash\fP(1)\-Version 2.01 entfernt, wird aber weiterhin von der Glibc unterstützt. .SH ATTRIBUTE Siehe \fBattributes\fP(7) für eine Erläuterung der in diesem Abschnitt verwandten Ausdrücke. .TS allbox; lbw24 lb lb l l l. Schnittstelle Attribut Wert T{ \fBgetopt\fP(), \fBgetopt_long\fP(), \fBgetopt_long_only\fP() T} Multithread\-Fähigkeit MT\-Unsafe race:getopt env .TE .SH "KONFORM ZU" .TP \fBgetopt\fP(): POSIX.1\-2001, POSIX.1\-2008 und POSIX.2, vorausgesetzt, die Umgebungsvariable POSIXLY_CORRECT ist gesetzt. Anderenfalls sind die Elemente von \fIargv\fP nicht wirklich \fIconst\fP, da diese Funktionen sie vertauschen. Trotzdem wird \fIconst\fP im Prototyp verwandt, um kompatibel zu anderen Systemen zu sein. .IP Die Verwendung von \(aq+\(aq und \(aq\-\(aq in \fIoptstring\fP ist eine GNU\-Erweiterung. .IP In einigen älteren Implementierungen wurde \fBgetopt\fP() in \fI\fP deklariert. SUSv1 gestattete die Deklaration entweder in \fI\fP oder \fI\fP. POSIX.1\-1995 kennzeichnete die Verwendung von \fI\fP zu diesem Zweck als LEGACY. POSIX.1\-2001 verlangt nicht, dass diese Deklaration in \fI\fP enthalten ist. .TP \fBgetopt_long\fP() und \fBgetopt_long_only\fP(): Diese Funktionen sind GNU\-Erweiterungen. .SH ANMERKUNGEN Ein Programm, das mehrere Argumentvektoren oder denselben Argumentvektor mehrfach auswertet und GNU\-Erweiterungen wie beispielsweise \(aq+\(aq und \(aq\-\(aq am Anfang von \fIoptstring\fP nutzen möchte oder zwischen den Auswertungen den Wert von \fBPOSIXLY_CORRECT\fP ändert, muss \fBgetopt\fP() neu initialisieren, indem es \fIoptind\fP auf 0 statt des traditionellen Wertes 1 setzt. (Das Rücksetzen auf 0 erzwingt den Aufruf einer internen Initialisierungsroutine, die erneut \fBPOSIXLY_CORRECT\fP prüft und in \fIoptstring\fP nach GNU\-Erweiterungen sucht.) .SH BEISPIELE .SS getopt() Das folgende triviale Beispielprogramm verwendet \fBgetopt\fP(), um zwei Programmoptionen zu verarbeiten: \fI\-n\fP ohne zugehörigen Wert und \fI\-t Wert\fP, die einen zugehörigen Wert erwartet. .PP .EX #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 \(aqn\(aq: flags = 1; break; case \(aqt\(aq: nsecs = atoi(optarg); tfnd = 1; break; default: /* \(aq?\(aq */ fprintf(stderr, "Verwendung: %s [\-t nsecs] [\-n] Name\en", argv[0]); exit(EXIT_FAILURE); } } printf("flags=%d; tfnd=%d; nsecs=%d; optind=%d\en", flags, tfnd, nsecs, optind); if (optind >= argc) { fprintf(stderr, "Nach den Optionen wurde ein Argument erwartet\en"); exit(EXIT_FAILURE); } printf("name argument = %s\en", argv[optind]); /* Weiterer Code weggelassen */ exit(EXIT_SUCCESS); } .EE .SS getopt_long() Das folgende Beispielprogramm veranschaulicht die Benutzung von \fBgetopt_long\fP() mit der Mehrzahl ihrer Funktionalitäten. .PP .EX #include /* für printf */ #include /* für exit */ #include 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, \(aqc\(aq}, {"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 ("\en"); break; case '0': case '1': case '2': if (digit_optind != 0 && digit_optind != this_option_optind) printf ( "Zahlen in zwei verschiedenen argv\-Elementen gefunden.\en"); digit_optind = this_option_optind; printf ("Option %c\en", c); break; case \(aqa\(aq: printf("Option a\en"); break; case \(aqb\(aq: printf("Option b\en"); break; case \(aqc\(aq: printf("Option c mit Wert \(aq%s\(aq\en", optarg); break; case \(aqd\(aq: printf("Option d mit Wert \(aq%s\(aq\en", optarg); break; case \(aq?\(aq: break; default: printf ("?? getopt lieferte Zeichencode 0%o zurück ??\en", c); } } if (optind < argc) { printf ("Nichtoptionselemente von ARGV: "); while (optind < argc) printf ("%s ", argv[optind++]); printf ("\en"); } exit(EXIT_SUCCESS); } .EE .SH "SIEHE AUCH" \fBgetopt\fP(1), \fBgetsubopt\fP(3) .SH KOLOPHON Diese Seite ist Teil der Veröffentlichung 5.10 des Projekts Linux\-\fIman\-pages\fP. 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/. .SH ÜBERSETZUNG Die deutsche Übersetzung dieser Handbuchseite wurde von Patrick Rother , Martin Eberhard Schauer , Mario Blättermann und Helge Kreutzmann erstellt. Diese Übersetzung ist Freie Dokumentation; lesen Sie die .UR https://www.gnu.org/licenses/gpl-3.0.html GNU General Public License Version 3 .UE 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 .MT debian-l10n-german@\:lists.\:debian.\:org Mailingliste der Übersetzer .ME .