.\" -*- coding: UTF-8 -*- '\" t .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) .\" and Copyright 2006-2008, Michael Kerrisk .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" 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 "20 juillet 2023" "Pages du manuel de Linux 6.05.01" .SH NOM getopt, getopt_long, getopt_long_only, optarg, optind, opterr, optopt — Analyser les options de la ligne de commande .SH BIBLIOTHÈQUE Bibliothèque C standard (\fIlibc\fP, \fI\-lc\fP) .SH SYNOPSIS .nf \fB#include \fP .PP \fBint getopt(int \fP\fIargc\fP\fB, char *\fP\fIargv\fP\fB[],\fP \fB const char *\fP\fIchaine_options\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 *\fP\fIargv\fP\fB[],\fP \fB const char *\fP\fIchaine_options\fP\fB,\fP \fB const struct option *\fP\fIlongopts\fP\fB, int *\fP\fIlongindex\fP\fB);\fP \fBint getopt_long_only(int \fP\fIargc\fP\fB, char *\fP\fIargv\fP\fB[],\fP \fB const char *\fP\fIchaine_options\fP\fB,\fP \fB const struct option *\fP\fIlongopts\fP\fB, int *\fP\fIlongindex\fP\fB);\fP .fi .PP .RS -4 Exigences de macros de test de fonctionnalités pour la glibc (consulter \fBfeature_test_macros\fP(7))\ : .RE .PP \fBgetopt\fP()\ : .nf _POSIX_C_SOURCE >= 2 || _XOPEN_SOURCE .fi .PP \fBgetopt_long\fP(), \fBgetopt_long_only\fP()\ : .nf _GNU_SOURCE .fi .SH DESCRIPTION La fonction \fBgetopt\fP() analyse les arguments de la ligne de commande. Ses arguments \fIargc\fP et \fIargv\fP correspondent au nombre et à la table d'éléments qui sont transmis à la fonction \fImain\fP() lors du lancement du programme. Un élément de \fIargv\fP qui commence par «\ \-\ » (et qui n'est pas uniquement «\ \-\-\ » ou «\ \-\ ») est considéré comme une option. Les caractères à la suite du ou des «\ \-\ » initiaux 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'index de l'élément suivant à analyser dans \fIargv\fP. Le système initialise cette valeur à\ 1. L'appelant peut la remettre à\ 1 pour recommencer l'analyse du même tableau de paramètres \fIargv\fP ou pour en analyser un nouveau. .PP Si \fBgetopt\fP() trouve un autre caractère d'option, elle renvoie ce caractère en mettant à jour la variable externe \fIoptind\fP et la variable statique \fInextchar\fP, de façon à ce que l'appel suivant à \fBgetopt\fP() puisse continuer l'analyse avec le caractère d'option suivant ou l'élément suivant de \fIargv\fP. .PP S'il n'y a plus de caractères d'option, \fBgetopt\fP() renvoie \fB\-1\fP. Alors, \fIoptind\fP devient l'index du premier élément de \fIargv\fP qui n'est pas une option. .PP \fIchaine_options\fP est une chaîne contenant l'ensemble des caractères d'option autorisés. Un caractère d'option autorisé est un caractère \fBascii\fP(7) imprimable sur 1\ octet (pour lequel \fBisgraph\fP(3) renverrait une valeur différente de zéro) autre que «\ \-\ », «\ :\ » ou «\ ;\ ». Si un de ces caractères est suivi par un deux\-points («\ :\ »), l'option nécessite un argument, donc \fBgetopt\fP() placera dans \fIoptarg\fP un pointeur sur le texte suivant dans le même élément de \fIargv\fP ou sur le texte de l'élément de \fIargv\fP suivant. Un double deux\-points («\ ::\ ») signifie qu'une option prend un argument facultatif. S'il existe un texte dans le même élément de \fIargv\fP (c'est\-à\-dire dans le même mot que le nom de l'option elle\-même comme «\ \-oarg\ »), il est renvoyé dans \fIoptarg\fP, sinon \fIoptarg\fP est défini à zéro. Il s'agit d'une extension GNU. Si \fIchaine_options\fP contient \fBW\fP suivi d'un point\-virgule, \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écifiques à l'implémentation). Ce comportement, spécifique à la version GNU, est pris en charge à partir de la version\ 2 de la bibliothèque glibc. .PP Par défaut, \fBgetopt\fP() permute les éléments de \fIargv\fP au fur et à mesure de son analyse, de façon à ce qu'en fin de compte, les arguments ne constituant pas des options se trouvent à la fin. Deux autres modes d'analyse sont également implémentés\ : si le premier caractère de \fIchaine_options\fP vaut «\ +\ » ou si la variable d'environnement \fBPOSIXLY_CORRECT\fP est définie, l'analyse s'arrête dès qu'un argument ne constituant pas une option est rencontré. Si le premier caractère de \fIchaine_options\fP est autre que «\ +\ », il est traité comme une option normale. Si le comportement induit par la définition de \fBPOSIXLY_CORRECT\fP est requis, \fIchaine_options\fP contiendra deux symboles «\ +\ ». Si le premier caractère de \fIchaine_options\fP vaut «\ \-\ », les arguments ne correspondant pas à une option sont manipulés comme s'ils étaient des arguments d'une option avec le code de caractère\ 1 (cela est utilisé par les programmes 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 d'élément). L'argument spécial «\ \-\-\ » arrête l'analyse des options, quel que soit le mode d'analyse en cours. .PP \fBgetopt\fP() peut détecter deux types d'erreur lors du traitement de la liste d'options\ : (1)\ un caractère d'option non spécifié dans \fIchaine_options\fP et (2)\ un argument d'option manquant (c'est\-à\-dire une option sans son argument attendu à la fin de la ligne de commande). Les erreurs de ce type sont traitées et signalées comme suit\ : .IP \- 3 Par défaut, \fBgetopt\fP() affiche un message d'erreur sur la sortie d'erreur standard, place le caractère d'option erroné dans \fIoptopt\fP et renvoie «\ ?\ » comme résultat. .IP \- Si l'appelant a défini la variable globale \fIopterr\fP à zéro, \fBgetopt\fP() n'affiche pas de message d'erreur. L'appelant peut détecter la présence d'une erreur en vérifiant si la fonction a renvoyé «\ ?\ » (par défaut, \fIopterr\fP possède une valeur différente de zéro). .IP \- .\" Si le premier caractère de \fIchaine_options\fP (suivant un des caractères facultatifs «\ +\ » ou «\ \-\ » décrits ci\-dessus) est un «\ :\ », là non plus, \fBgetopt\fP() n'affiche pas de message d'erreur. En outre, elle renvoie «\ :\ » au lieu de «\ ?\ » pour indiquer un argument d'option manquant, ce qui permet à l'appelant de distinguer les deux types d'erreur. .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, \fIchaine_options\fP doit ê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\ : \fBaucun_argument\fP (ou\ \fB0\fP), si l'option ne prend pas d'argument, \fBargument_requis\fP (ou\ \fB1\fP) si l'option prend un argument, ou \fBargument_facultatif\fP (ou\ \fB2\fP) 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, \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\ \fB0\fP, 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 à affecter à 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 est différent de 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, \fBgetopt\fP() renvoie le caractère de l'option. Si toutes les options de la ligne de commande ont été lues, \fBgetopt\fP() renvoie \fB\-1\fP. Si \fBgetopt\fP() rencontre un caractère d'option qui n'est pas dans \fIchaine_options\fP, «\ ?\ » est renvoyé. Si \fBgetopt\fP() rencontre une option avec un argument manquant, la valeur renvoyée dépend du premier caractère de \fIchaine_options\fP\ : si c'est «\ :\ », 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 si elles en trouvent une. Pour les options longues, elles renvoient \fIval\fP si \fIflag\fP vaut NULL, et\ \fB0\fP 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 définie, 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 ne devant donc pas être considérés comme des options. Ce comportement a été supprimé de \fBbash\fP(1)\ 2.01, mais il est toujours pris en charge par la glibc. .SH ATTRIBUTS Pour une explication des termes utilisés dans cette section, consulter \fBattributes\fP(7). .TS allbox; lb lb lbx l l l. Interface Attribut Valeur T{ .na .nh \fBgetopt\fP(), \fBgetopt_long\fP(), \fBgetopt_long_only\fP() T} Sécurité des threads T{ .na .nh MT\-Unsafe race:getopt env T} .TE .sp 1 .SH VERSIONS POSIX spécifie que l'argument du tableau \fIargv\fP doit être \fIconst\fP, mais ces fonctions permutent ses éléments si la variable d'environnement \fBPOSIXLY_CORRECT\fP n'est pas définie. Le prototype effectif utilise \fIconst\fP pour être compatible avec les autres systèmes\ ; cette page, cependant, ne montre pas le qualificateur pour éviter de perturber les lecteurs. .SH STANDARDS .TP \fBgetopt\fP() POSIX.1\-2008. .TP \fBgetopt_long\fP() .TQ \fBgetopt_long_only\fP() GNU. .IP L'utilisation de «\ +\ » et «\ \-\ » dans \fIchaine_options\fP est une extension GNU. .SH HISTORIQUE .TP \fBgetopt\fP() POSIX.1\-2001 et POSIX.2. .PP Sur certaines anciennes implémentations, \fBgetopt\fP() était déclarée dans \fI\fP. SUSv1 permettait que la déclaration apparaisse soit dans \fI\fP, soit dans \fI\fP. POSIX.1\-1996 considère la déclaration dans \fI\fP comme «\ LEGACY\ » (obsolète), et POSIX.1\-2001 n'exige pas que la déclaration soit dans \fI\fP. .SH NOTES Un programme qui analyse plusieurs tableaux de paramètres ou analyse plusieurs fois le même tableau et qui veut utiliser les extensions GNU telles que «\ +\ » et «\ \-\ » au début de \fIchaine_options\fP, ou changer la valeur de \fBPOSIXLY_CORRECT\fP entre les analyses, doit réinitialiser \fBgetopt\fP() en remettant \fIoptind\fP à\ \fB0\fP, plutôt qu'à la valeur traditionnelle de\ \fB1\fP. La remise à\ \fB0\fP force l'appel d'une routine d'initialisation interne qui revérifie la définition de \fBPOSIXLY_CORRECT\fP et recherche les extensions GNU dans \fIchaine_options\fP. .PP Les arguments de la ligne de commande sont analysés selon leur ordre strict, ce qui signifie qu'une option nécessitant un argument va consommer l'argument suivant, qu'il s'agisse de son argument correctement spécifié ou de l'option suivante (auquel cas l'utilisateur aura mal rédigé la ligne de commande). Par exemple, si \fIchaine_options\fP contient «\ 1n:\ » et si l'utilisateur fournit une ligne de commande incorrecte en spécifiant \fIprog\ \-n\ \-1\fP, l'option \fI\-n\fP se verra affecter la valeur de \fBoptarg\fP «\ \-1\ », et l'option \fI\-1\fP sera considérée comme non spécifiée. .SH EXEMPLES .SS getopt() Le programme d'exemple trivial suivant utilise \fBgetopt\fP() avec deux options\ : \fI\-n\fP sans valeur associée et \fI\-t val\fP qui nécessite une valeur. .PP .\" SRC BEGIN (getopt.c) .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 \[aq]n\[aq]: flags = 1; break; case \[aq]t\[aq]: nsecs = atoi(optarg); tfnd = 1; break; default: /* \[aq]?\[aq] */ fprintf(stderr, "Usage : %s [\-t nsecs] [\-n] nom\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, "Argument requis après les options\en"); exit(EXIT_FAILURE); } \& printf("argument nom = %s\en", argv[optind]); \& /* Le reste du code n'est pas mentionné */ \& exit(EXIT_SUCCESS); } .EE .\" SRC END .SS getopt_long() Le programme suivant montre l'utilisation de \fBgetopt_long\fP() en illustrant la plupart de ses fonctionnalités. .PP .\" SRC BEGIN (getopt_long.c) .EX #include #include /* pour printf */ #include /* pour 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", argument_requis, 0, 0 }, {"append", aucun_argument, 0, 0 }, {"delete", argument_requis, 0, 0 }, {"verbose", aucun_argument, 0, 0 }, {"create", argument_requis, 0, \[aq]c\[aq]}, {"file", argument_requis, 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(" avec l'argument %s", optarg); printf("\en"); break; \& case \[aq]0\[aq]: case \[aq]1\[aq]: case \[aq]2\[aq]: if (digit_optind != 0 && digit_optind != this_option_optind) printf("des chiffres apparaissent dans deux éléments différents de argv.\en"); digit_optind = this_option_optind; printf("option %c\en", c); break; \& case \[aq]a\[aq]: printf("option a\en"); break; \& case \[aq]b\[aq]: printf("option b\en"); break; \& case \[aq]c\[aq]: printf("option c ayant pour valeur \[aq]%s\[aq]\en", optarg); break; \& case \[aq]d\[aq]: printf("option d ayant pour valeur \[aq]%s\[aq]\en", optarg); break; \& case \[aq]?\[aq]: break; \& default: printf("?? getopt a renvoyé le caractère de code 0%o ??\en", c); } } \& if (optind < argc) { printf("éléments de argv autres que des options : "); while (optind < argc) printf("%s ", argv[optind++]); printf("\en"); } \& exit(EXIT_SUCCESS); } .EE .\" SRC END .SH "VOIR AUSSI" \fBgetopt\fP(1), \fBgetsubopt\fP(3) .PP .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 , David Prévot et Lucien Gentis . .PP 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. .PP 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 .