Provided by: manpages-fr-dev_3.27fr1.4-1_all bug

NOM

       getopt, getopt_long, getopt_long_only, optarg, optind, opterr, optopt -
       Analyser les options de la ligne de commande

SYNOPSIS

       #include <unistd.h>

       int getopt(int argc, char * const argv[],
                  const char *optstring);

       extern char *optarg;
       extern int optind, opterr, optopt;

       #include <getopt.h>

       int getopt_long(int argc, char * const argv[],
                  const char *optstring,
                  const struct option *longopts, int *longindex);

       int getopt_long_only(int argc, char * const argv[],
                  const char *optstring,
                  const struct option *longopts, int *longindex);

   Exigences de macros de test de fonctionnalites  pour  la  glibc  (consultez
   feature_test_macros(7)) :

       getopt() : _POSIX_C_SOURCE >= 2 || _XOPEN_SOURCE
       getopt_long(), getopt_long_only() : _GNU_SOURCE

DESCRIPTION

       La fonction getopt() analyse les arguments de la ligne de commande. Ses
       elements  argc  et  argv  correspondent  aux  nombres  et  a  la  table
       d'arguments qui sont transmis a la fonction main() lors du lancement du
       programme. Un element de argv qui commence par << - >> (et qui ne  soit
       pas uniquement << -- >> ou << - >>) est considere comme une option. Les
       caracteres a la  suite  du  << - >>  initial  sont  les  caracteres  de
       l'option.  Si  getopt() est appelee a plusieurs reprises, elle renverra
       successivement chaque caractere de chaque option.

       La variable optind est l'indice de l'element suivant  a  analyser  dans
       argv.  Le  systeme  initialise  cette  valeur  a  1. L'appelant peut le
       remettre a 1 pour recommencer l'analyse du meme argv ou  pour  analyser
       un nouveau tableau de parametre.

       Si  getopt()  trouve  un  autre  caractere  d'option,  elle le renvoie,
       mettant a jour la variable  externe  optind  et  la  variable  statique
       nextchar,  ainsi  l'appel  suivant  a getopt() peut continuer l'analyse
       avec le caractere suivant ou l'element argv.

       S'il n'y a plus de caracteres d'option,  getopt()  renvoie  -1.  Alors,
       optind  devient  l'index du premier element de argv qui ne soit pas une
       option.

       optstring est une chaine contenant l'ensemble des  caracteres  d'option
       autorises.  Si  un  de  ces  caracteres  est  suivi  par un deux-points
       (<< : >>), l'option necessite un argument,  donc  getopt()  placera  un
       pointeur  sur  le  texte  suivant dans le meme argv, ou sur le texte de
       l'element argv suivant dans optarg. Un double  deux  points  (<< :: >>)
       signifie  qu'une  option  prend  un  argument optionnel. S'il existe un
       texte dans le meme element de argv (c'est a dire dans le meme  mot  que
       l'option elle-meme comme << -oarg >>) alors il est renvoye dans optarg,
       sinon optarg est defini a zero.  Il  s'agit  d'une  extension  GNU.  Si
       optstring  contient W suivi d'un point-virgule, alors -W foo est traite
       comme l'option longue --foo (l'option -W est reservee par POSIX.2  pour
       des   extensions   specifique  a  l'implementation).  Ce  comportement,
       specifique a la version GNU, n'est pas disponible avant la bibliotheque
       glibc 2.

       Par defaut, getopt() permute les elements de argv au fur et a mesure de
       son analyse, ainsi tous les arguments eventuels ne constituant pas  des
       options  se  trouvent  a  la  fin.  Deux  autres  modes  sont egalement
       implementes : Si le premier caractere de optstring vaut << + >>, ou  si
       la variable d'environnement POSIXLY_CORRECT est valide, alors l'analyse
       s'arrete aussitot qu'un argument ne  constituant  pas  une  option  est
       rencontre. Si le premier caractere de optstring vaut << - >>, alors les
       arguments ne correspondant pas a une option sont manipules comme  s'ils
       etaient  des  arguments d'une option dont le caractere est le caractere
       de code 1 (ceci est utilise par les programmes  qui  sont  concus  pour
       recevoir  des  options et d'autres elements de argv dans n'importe quel
       ordre  mais  qui  prennent  en  compte  l'ordre  de  ces  deux  types).
       L'argument  special << -- >> arrete l'analyse des options, quelque soit
       le mode en cours.

       Si getopt() ne reconnait pas  un  caractere  d'option,  il  affiche  un
       message  d'erreur  sur  la  sortie standard stderr, stocke le caractere
       dans optopt, et renvoie << ? >>. Le programme  appelant  peut  empecher
       l'affichage du message d'erreur en positionnant opterr a 0.

       Si  getopt()  trouve  dans  argv  un caractere d'option non inclus dans
       optstring, ou s'il manque un argument  d'option,  la  fonction  renvoie
       << ? >>  et  affecte a la variable externe optopt le caractere d'option
       courant. Si le premier caractere de optstring  (suivi  par  << + >>  ou
       << - >>)  est  un deux points (<< : >>), alors getopt() renvoie << : >>
       plutot que << ? >> pour indiquer un argument d'option manquant. Si  une
       erreur  est  detectee,  si  le premier caractere de optstring n'est pas
       deux points, et si la variable externe opterr est non nulle, (non nulle
       par defaut), alors getopt() affiche un message d'erreur.

   getopt_long() et getopt_long_only()
       La  fonction  getopt_long()  fonctionne  comme  getopt()  sauf  qu'elle
       accepte egalement des noms longs d'option, commencant par  deux  tirets
       (si le programme accepte seulement les options longues, alors optstring
       devrait etre specifiee avec une chaine vide << "" >> et non avec NULL).
       Les  noms  longs  d'option  peuvent  etre abreges, si l'abreviation est
       unique, ou si elle correspond exactement  a  une  option  definie.  Une
       option  longue  peut  prendre  un  argument, de la forme --arg=param ou
       --arg param.

       longopts est un  pointeur  sur  le  premier  element  d'un  tableau  de
       structures struct option declarees dans <getopt.h> ainsi :

           struct option {
               const char *name;
               int         has_arg;
               int        *flag;
               int         val;
           };

       La signification des differents champs est la suivante :

       name   est le nom de l'option longue.

       has_arg
              vaut :  no_argument (ou 0), si l'option ne prend pas d'argument,
              required_argument (ou 1)  si  l'option  prend  un  argument,  ou
              optional_argument   (ou   2)   si  l'option  prend  un  argument
              optionnel.

       flag   specifie la maniere de renvoyer les resultats  pour  une  option
              longue.  Si flag vaut NULL, alors getopt_long() renvoie val (par
              exemple,  le  programme  appelant  peut  remplir  val  avec   le
              caractere    de    l'option   courte   correspondante).   Sinon,
              getopt_long() renvoie 0, et flag pointe sur une variable definie
              a  val  si l'option est trouvee, mais reste inchange si l'option
              est absente.

       val    est la valeur a renvoyer, ou a charger dans la variable  pointee
              par flag.

       Le dernier element de la table doit etre rempli avec des zeros.

       Si longindex n'est pas NULL, il pointe sur une variable qui est definie
       avec l'index de l'option longue correspondant a longopts.

       getopt_long_only() fonctionne comme getopt_long(),  mais  << - >>  tout
       comme   << -- >>  peut  indiquer  une  option  longue.  Si  une  option
       commencant par << - >> (et non << -- >>) ne correspond pas a une option
       longue,  mais correspond a une option courte, elle est analysee en tant
       qu'option courte.

VALEUR RENVOY'EE

       Si une option a ete trouvee, alors getopt()  renvoie  le  caractere  de
       l'option.  Si  toutes les options de la ligne de commande ont ete lues,
       alors getopt() renvoie -1. Si getopt() rencontre un caractere  d'option
       qui  n'est  pas  dans optstring, alors << ? >> est renvoye. Si getopt()
       rencontre une  option  avec  un  argument  manquant,  alors  la  valeur
       renvoyee  depend  du premier caractere de optstring : si c'est << : >>,
       alors ce caractere est renvoye, sinon << ? >> est renvoye.

       getopt_long() et getopt_long_only() renvoient  egalement  le  caractere
       d'option  courte  s'ils  en trouvent une. Pour les options longues, ils
       renvoient val si flag vaut NULL, et 0 sinon. Les erreurs et la fin  des
       options  sont  gerees  comme  avec  getopt(),  en renvoyant de surcroit
       << ? >> pour une correspondance ambigue, ou un parametre en trop.

ENVIRONNEMENT

       POSIXLY_CORRECT
              Si cette variable est positionnee, l'analyse s'arrete des  qu'un
              argument ne constituant pas une option est rencontre.

       _<PID>_GNU_nonoption_argv_flags_
              Cette  variable  est utilisee par bash(1) 2.0 pour communiquer a
              la glibc les arguments resultant de l'expansion  des  caracteres
              generiques,  et  ils  ne  doivent  pas etre consideres comme des
              options. Ce comportement a ete supprime de bash(1) version 2.01,
              mais il est toujours gere par la glibc.

CONFORMIT'E

       getopt() :
              POSIX.2   et   POSIX.1-2001,   a   condition   que  la  variable
              d'environnement POSIXLY_CORRECT  soit  positionnee.  Sinon,  les
              elements  de  argv  ne  sont pas vraiment constants puisque l'on
              peut les permuter. On les declare << const >> dans le  prototype
              pour etre compatible avec d'autres systemes.

              L'utilisation  de  '+'  et  '-' dans optstring est une extension
              GNU.

              Sur certaines anciennes implementations, getopt() etait declaree
              dans  <stdio.h>.  SUSv1 permettait que la declaration apparaisse
              soit dans <unistd.h> ou soit dans <stdio.h>. POSIX.1-2001 marque
              l'utilisation  de  <stdio.h> comme << LEGACY >>. POSIX.1-2001 ne
              permet pas que la declaration soit dans <stdio.h>.

       getopt_long() et getopt_long_only() :
              Ces fonctions sont des extensions GNU.

NOTES

       Un programme qui analyse plusieurs tableaux de parametres ou analyse de
       nouveau  le  meme  tableau  plusieurs  fois,  et  qui veut utiliser les
       extension GNU telles que '+' et '-' au debut de optstring,  ou  changer
       la  valeur  de  POSIXLY_CORRECT  entre les analyses, doit reinitialiser
       getopt() en remettant optind a 0, plutot que la  valeur  traditionnelle
       de  1.  La  remise  a  0  force  l'appel d'une routine d'initialisation
       interne qui verifie POSIXLY_CORRECT  et verifie les extensions GNU dans
       optstring.

BOGUES

       Les specifications POSIX.2 de getopt() contiennent une erreur technique
       decrite dans  POSIX.2  interpretation  150.  L'implementation  GNU  (et
       probablement   toutes   les  autres)  adopte  un  comportement  correct
       different de la specification.

EXEMPLE

       Le  programme  d'exemple  trivial  suivant  utilise  getopt()  avec   2
       options :-n sans valeur associee et -t val qui necessite une valeur.

       #include <unistd.h>
       #include <stdlib.h>
       #include <stdio.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; optind=%d\n", flags, tfnd, optind);

           if (optind >= argc) {
               fprintf(stderr, "Expected argument after options\n");
               exit(EXIT_FAILURE);
           }

           printf("name argument = %s\n", argv[optind]);

           /* Other code omitted */

           exit(EXIT_SUCCESS);
       }

       Le  programme  suivant  illustre l'utilisation de getopt_long() avec la
       plupart de ses fonctionnalites.

       #include <stdio.h>     /* for printf */
       #include <stdlib.h>    /* for exit */
       #include <getopt.h>

       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", 1, 0, 0},
                   {"append", 0, 0, 0},
                   {"delete", 1, 0, 0},
                   {"verbose", 0, 0, 0},
                   {"create", 1, 0, 'c'},
                   {"file", 1, 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);
       }

VOIR AUSSI

       getsubopt(3), feature_test_macros(7)

COLOPHON

       Cette page fait partie de  la  publication  3.27  du  projet  man-pages
       Linux.  Une description du projet et des instructions pour signaler des
       anomalies      peuvent      etre       trouvees       a       l'adresse
       <URL:http://www.kernel.org/doc/man-pages/>.

TRADUCTION

       Depuis  2010,  cette  traduction est maintenue a l'aide de l'outil po4a
       <URL:http://po4a.alioth.debian.org/>   par   l'equipe   de   traduction
       francophone        au        sein        du       projet       perkamon
       <URL:http://perkamon.alioth.debian.org/>.

       Christophe Blaess  <URL:http://www.blaess.fr/christophe/>  (1996-2003),
       Alain  Portal  <URL:http://manpagesfr.free.fr/> (2003-2006).  Florentin
       Duneau et l'equipe francophone de traduction de Debian (2006-2009).

       Veuillez  signaler  toute  erreur   de   traduction   en   ecrivant   a
       <debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
       paquet manpages-fr.

       Vous pouvez toujours avoir acces a la version anglaise de  ce  document
       en utilisant la commande << man -L C <section> <page_de_man> >>.

GNU                             3 fevrier 2010                       GETOPT(3)