.\" -*- coding: UTF-8 -*- .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) .\" .\" %%%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 "6 mars 2019" GNU "Manuel du programmeur Linux" .SH NOM getopt, getopt_long, getopt_long_only, optarg, optind, opterr, optopt \- Analyser les options de la ligne de commande .SH SYNOPSIS .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 .in -4n Exigences de macros de test de fonctionnalités pour la glibc (consulter \fBfeature_test_macros\fP(7))\ : .ad l .in .PP \fBgetopt\fP()\ : _POSIX_C_SOURCE\ >=\ 2 || _XOPEN_SOURCE .br \fBgetopt_long\fP(), \fBgetopt_long_only\fP()\ : _GNU_SOURCE .ad b .SH DESCRIPTION La fonction \fBgetopt\fP() analyse les arguments de la ligne de commande. Ses éléments \fIargc\fP et \fIargv\fP correspondent aux nombres et à la table d'arguments qui sont transmis à la fonction \fImain\fP() lors du lancement du programme. Un élément de \fIargv\fP qui commence par «\ \-\ » (et qui ne soit pas uniquement «\ \-\-\ » ou «\ \-\ ») est considéré comme une option. Les caractères à la suite du «\ \-\ » initial sont les caractères de l'option. Si \fBgetopt\fP() est appelée à plusieurs reprises, elle renverra successivement chaque caractère de chaque option. .PP La variable \fIoptind\fP est l'indice de l'élément suivant à analyser dans \fIargv\fP. Le système initialise cette valeur à 1. L'appelant peut le remettre à 1 pour recommencer l'analyse du même \fIargv\fP ou pour analyser un nouveau tableau de paramètre. .PP Si \fBgetopt\fP() trouve un autre caractère d'option, elle le renvoie, mettant à jour la variable externe \fIoptind\fP et la variable statique \fInextchar\fP, ainsi l'appel suivant à \fBgetopt\fP() peut continuer l'analyse avec le caractère suivant ou l'élément \fIargv\fP. .PP S'il n'y a plus de caractères d'option, \fBgetopt\fP() renvoie \-1. Alors, \fIoptind\fP devient l'index du premier élément de \fIargv\fP qui ne soit pas une option. .PP \fIoptstring\fP est une chaîne contenant l'ensemble des caractères d'option autorisés. Si un de ces caractères est suivi par un deux\-points («\ :\ »), l'option nécessite un argument, donc \fBgetopt\fP() placera un pointeur sur le texte suivant dans le même \fIargv\fP, ou sur le texte de l'élément \fIargv\fP suivant dans \fIoptarg\fP. Un double deux points («\ ::\ ») signifie qu'une option prend un argument optionnel. S'il existe un texte dans le même élément de \fIargv\fP (c'est\-à\-dire dans le même mot que l'option elle\-même comme «\ \-oarg\ ») alors il est renvoyé dans \fIoptarg\fP, sinon \fIoptarg\fP est défini à zéro. Il s'agit d'une extension GNU. Si \fIoptstring\fP contient \fBW\fP suivi d'un point\-virgule, alors \fB\-W foo\fP est traité comme l'option longue \fB\-\-foo\fP (l'option \fB\-W\fP est réservée par POSIX.2 pour des extensions spécifique à l'implémentation). Ce comportement, spécifique à la version GNU, n'est pas disponible avant la bibliothèque glibc\ 2. .PP Par défaut, \fBgetopt\fP() permute les éléments de \fIargv\fP au fur et à mesure de son analyse, ainsi tous les arguments éventuels ne constituant pas des options se trouvent à la fin. Deux autres modes sont également implémentés\ : Si le premier caractère de \fIoptstring\fP vaut «\ +\ », ou si la variable d'environnement \fBPOSIXLY_CORRECT\fP est valide, alors l'analyse s'arrête aussitôt qu'un argument ne constituant pas une option est rencontré. Si le premier caractère de \fIoptstring\fP vaut «\ \-\ », alors les arguments ne correspondant pas à une option sont manipulés comme s'ils étaient des arguments d'une option dont le caractère est le caractère de code 1 (ceci est utilisé par les programmes qui sont conçus pour recevoir des options et d'autres éléments de \fIargv\fP dans n'importe quel ordre mais qui prennent en compte l'ordre de ces deux types). L'argument spécial «\ \-\-\ » arrête l'analyse des options, quelque soit le mode en cours. .PP While processing the option list, \fBgetopt\fP() can detect two kinds of errors: (1) an option character that was not specified in \fIoptstring\fP and (2) a missing option argument (i.e., an option at the end of the command line without an expected argument). Such errors are handled and reported as follows: .IP * 3 By default, \fBgetopt\fP() prints an error message on standard error, places the erroneous option character in \fIoptopt\fP, and returns \(aq?\(aq as the function result. .IP * If the caller has set the global variable \fIopterr\fP to zero, then \fBgetopt\fP() does not print an error message. The caller can determine that there was an error by testing whether the function return value is \(aq?\(aq. (By default, \fIopterr\fP has a nonzero value.) .IP * .\" If the first character (following any optional \(aq+\(aq or \(aq\-\(aq described above) of \fIoptstring\fP is a colon (\(aq:\(aq), then \fBgetopt\fP() likewise does not print an error message. In addition, it returns \(aq:\(aq instead of \(aq?\(aq to indicate a missing option argument. This allows the caller to distinguish the two different types of errors. .SS "getopt_long() et getopt_long_only()" La fonction \fBgetopt_long\fP() fonctionne comme \fBgetopt\fP() sauf qu'elle accepte également des noms longs d'option, commençant par deux tirets (si le programme accepte seulement les options longues, alors \fIoptstring\fP devrait être indiquée avec une chaîne vide «\ ""\ » et non avec NULL). Les noms longs d'option peuvent être abrégés, si l'abréviation est unique, ou si elle correspond exactement à une option définie. Une option longue peut prendre un argument, de la forme \fB\-\-arg=param\fP ou \fB\-\-arg param\fP. .PP \fIlongopts\fP est un pointeur sur le premier élément d'un tableau de structures \fIstruct option\fP déclarées dans \fI\fP ainsi\ : .PP .in +4n .EX struct option { const char *name; int has_arg; int *flag; int val; }; .EE .in .PP La signification des différents champs est la suivante\ : .TP \fInom\fP est le nom de l'option longue. .TP \fIhas_arg\fP vaut\ : \fBno_argument\fP (ou 0), si l'option ne prend pas d'argument, \fBrequired_argument\fP (ou 1) si l'option prend un argument, ou \fBoptional_argument\fP (ou 2) si l'option prend un argument optionnel. .TP \fIflag\fP indique la manière de renvoyer les résultats pour une option longue. Si \fIflag\fP vaut NULL, alors \fBgetopt_long\fP() renvoie \fIval\fP (par exemple, le programme appelant peut remplir \fIval\fP avec le caractère de l'option courte correspondante). Sinon, \fBgetopt_long\fP() renvoie 0, et \fIflag\fP pointe sur une variable définie à \fIval\fP si l'option est trouvée, mais reste inchangé si l'option est absente. .TP \fIval\fP est la valeur à renvoyer, ou à charger dans la variable pointée par \fIflag\fP. .PP Le dernier élément de la table doit être rempli avec des zéros. .PP Si \fIlongindex\fP n'est pas NULL, il pointe sur une variable qui est définie avec l'index de l'option longue correspondant à \fIlongopts\fP. .PP \fBgetopt_long_only\fP() fonctionne comme \fBgetopt_long\fP(), mais «\ \-\ » tout comme «\ \-\-\ » peut indiquer une option longue. Si une option commençant par «\ \-\ » (et non «\ \-\-\ ») ne correspond pas à une option longue, mais correspond à une option courte, elle est analysée en tant qu'option courte. .SH "VALEUR RENVOYÉE" Si une option a été trouvée, alors \fBgetopt\fP() renvoie le caractère de l'option. Si toutes les options de la ligne de commande ont été lues, alors \fBgetopt\fP() renvoie \-1. Si \fBgetopt\fP() rencontre un caractère d'option qui n'est pas dans \fIoptstring\fP, alors «\ ?\ » est renvoyé. Si \fBgetopt\fP() rencontre une option avec un argument manquant, alors la valeur renvoyée dépend du premier caractère de \fIoptstring\fP\ : si c'est «\ :\ », alors ce caractère est renvoyé, sinon «\ ?\ » est renvoyé. .PP \fBgetopt_long\fP() et \fBgetopt_long_only\fP() renvoient également le caractère d'option courte s'ils en trouvent une. Pour les options longues, ils renvoient \fIval\fP si \fIflag\fP vaut NULL, et 0 sinon. Les erreurs et la fin des options sont gérées comme avec \fBgetopt\fP(), en renvoyant de surcroît «\ ?\ » pour une correspondance ambiguë, ou un paramètre en trop. .SH ENVIRONNEMENT .TP \fBPOSIXLY_CORRECT\fP Si cette variable est positionnée, l'analyse s'arrête dès qu'un argument ne constituant pas une option est rencontré. .TP \fB__GNU_nonoption_argv_flags_\fP Cette variable est utilisée par \fBbash\fP(1) 2.0 pour communiquer à la glibc les arguments résultant de l'expansion des caractères génériques, et ils ne doivent pas être considérés comme des options. Ce comportement a été supprimé de \fBbash\fP(1) version 2.01, mais il est toujours géré par la glibc. .SH ATTRIBUTS Pour une explication des termes utilisés dans cette section, consulter \fBattributes\fP(7). .TS allbox; lbw24 lb lb l l l. Interface Attribut Valeur T{ \fBgetopt\fP(), \fBgetopt_long\fP(), \fBgetopt_long_only\fP() T} Sécurité des threads MT\-Unsafe race:getopt env .TE .SH CONFORMITÉ .TP \fBgetopt\fP()\ : POSIX.1\-2001, POSIX.1\-2008, and POSIX.2, provided the environment variable \fBPOSIXLY_CORRECT\fP is set. Otherwise, the elements of \fIargv\fP aren't really \fIconst\fP, because we permute them. We pretend they're \fIconst\fP in the prototype to be compatible with other systems. .IP L'utilisation de \(aq+\(aq et \(aq\-\(aq dans \fIoptstring\fP est une extension GNU. .IP On some older implementations, \fBgetopt\fP() was declared in \fI\fP. SUSv1 permitted the declaration to appear in either \fI\fP or \fI\fP. POSIX.1\-1996 marked the use of \fI\fP for this purpose as LEGACY. POSIX.1\-2001 does not require the declaration to appear in \fI\fP. .TP \fBgetopt_long\fP() et \fBgetopt_long_only\fP()\ : Ces fonctions sont des extensions GNU. .SH NOTES Un programme qui analyse plusieurs tableaux de paramètres ou analyse de nouveau le même tableau plusieurs fois, et qui veut utiliser les extension GNU telles que \(aq+\(aq et \(aq\-\(aq au début de \fIoptstring\fP, ou changer la valeur de \fBPOSIXLY_CORRECT\fP entre les analyses, doit réinitialiser \fBgetopt\fP() en remettant \fIoptind\fP à 0, plutôt que la valeur traditionnelle de 1. La remise à 0 force l'appel d'une routine d'initialisation interne qui vérifie \fBPOSIXLY_CORRECT\fP et vérifie les extensions GNU dans \fIoptstring\fP. .SH EXEMPLE .SS getopt() Le programme d'exemple trivial suivant utilise \fBgetopt\fP() avec 2 options\ :\fI\-n\fP sans valeur associée et \fI\-t val\fP qui nécessite une valeur. .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, "Usage: %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, "Expected argument after options\en"); exit(EXIT_FAILURE); } printf("name argument = %s\en", argv[optind]); /* Other code omitted */ exit(EXIT_SUCCESS); } .EE .SS getopt_long() The following example program illustrates the use of \fBgetopt_long\fP() with most of its features. .PP .EX #include /* for printf */ #include /* for 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(" with arg %s", optarg); printf("\en"); break; case \(aq0\(aq: case \(aq1\(aq: case \(aq2\(aq: if (digit_optind != 0 && digit_optind != this_option_optind) printf("digits occur in two different argv\-elements.\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 with value \(aq%s\(aq\en", optarg); break; case \(aqd\(aq: printf("option d with value \(aq%s\(aq\en", optarg); break; case \(aq?\(aq: break; default: printf("?? getopt returned character code 0%o ??\en", c); } } if (optind < argc) { printf("non\-option ARGV\-elements: "); while (optind < argc) printf("%s ", argv[optind++]); printf("\en"); } exit(EXIT_SUCCESS); } .EE .SH "VOIR AUSSI" \fBgetopt\fP(1), \fBgetsubopt\fP(3) .SH COLOPHON Cette page fait partie de la publication\ 5.04 du projet \fIman\-pages\fP Linux. Une description du projet et des instructions pour signaler des anomalies et la dernière version de cette page peuvent être trouvées à l'adresse \%https://www.kernel.org/doc/man\-pages/. .SH TRADUCTION La traduction française de cette page de manuel a été créée par Christophe Blaess , Stéphan Rafin , Thierry Vignaud , François Micaux, Alain Portal , Jean-Philippe Guérard , Jean-Luc Coulon (f5ibh) , Julien Cristau , Thomas Huriaux , Nicolas François , Florentin Duneau , Simon Paillard , Denis Barbier et David Prévot . Cette traduction est une documentation libre ; veuillez vous reporter à la .UR https://www.gnu.org/licenses/gpl-3.0.html GNU General Public License version 3 .UE concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE. Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message à .MT debian-l10n-french@lists.debian.org .ME .