Provided by: manpages-es_1.55-10_all bug

NOMBRE

       getopt - Analiza las opciones de la línea de órdenes

SINOPSIS

       #include <unistd.h>

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

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

       #define _GNU_SOURCE
       #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);

DESCRIPCIÓN

       La  función getopt() analiza los argumentos de la línea de órdenes. Sus
       argumentos argc y argv son el número y el vector de argumentos como los
       pasados a la función main() cuando se ejecuta el programa.  Un elemento
       de argv que comience con '-' (y que no sea exactamente "-" ni "--")  es
       un  elemento de opción. Los caracteres de este elemento (aparte del '-'
       inicial) son caracteres de opción. Si getopt() se llama  repetidamente,
       devuelve sucesivamente cada uno de los caracteres de opción de cada uno
       de los elementos de opción.

       Si  getopt()  encuentra  otro  carácter   de   opción,   lo   devuelve,
       actualizando  la  variable  externa  optind  y  una  variable  estática
       nextchar de forma que la siguiente llamada a getopt() pueda  seguir  la
       búsqueda en el siguiente carácter de opción o elemento de argv.

       Si  no  hay  más  caracteres de opción, getopt() devuelve -1.  Entonces
       optind es el índice en argv del primer elemento de argv que no  es  una
       opción.

       optstring   es  una  cadena  que  contiene  los  caracteres  de  opción
       legítimos. Si un carácter de éstos es seguido por el  carácter  de  dos
       puntos,  la opción necesita un argumento, de forma que getopt coloca un
       puntero al texto siguiente en el mismo elemento de  argv,  o  el  texto
       del  siguiente  elemento  de  argv,  en  optarg.  Dos caracteres de dos
       puntos significan que una opción toma un arg. opcional; si hay texto en
       el  elemento  de  argv  actual, se devuelve en optarg; si no, optarg se
       pone a cero.  Lo siguiente  es  una  extensión  de  GNU.  Si  optstring
       contiene  W  seguido por un punto y coma, entonces -W foo se trata como
       la opción larga --foo.  (La opción -W está reservada  en  POSIX.2  para
       extensiones  de  implementación).  Este comportamiento es una extensión
       de GNU, no disponible en bibliotecas anteriores a la versión 2  de  GNU
       libc.

       Por  omisión,  getopt()  permuta  los  contenidos  de  argv  cuando  lo
       escudriña, de modo que todo lo que no sea una  opción  vaya  al  final.
       Están implementados otros dos modos de operación. Si el primer carácter
       de  optstring  es  '+'  o  está  definida  la  variable   de   ambiente
       POSIXLY_CORRECT,  entonces  el  procesamiento  de la opción se para tan
       pronto se encuentra un argumento que no es una opción.   Si  el  primer
       carácter de optstring es '-', entonces cada elemento de argv que no sea
       una opción se maneja como si fuera  el  argumento  de  una  opción  con
       código  de  carácter  1.  (Esto se usa en programas que fueron escritos
       para esperar opciones y otros elementos de argv en  cualquier  orden  y
       donde  importa  el  ordenamiento de ambos).  El argumento especial '--'
       fuerza que se acabe el rastreo de las opciones sin tenerse en cuenta el
       modo.

       Si  getopt()  no  reconoce un carácter de opción, muestra un mensaje de
       error en stderr, guarda el carácter  en  optopt,  y  devuelve  '?'.  El
       programa  que  llama  a  la  función  puede  evitar el mensaje de error
       poniendo opterr a 0.

       Si getopt() encuentra un carácter de  opción  en  argv  que  no  estaba
       incluido  en  optstring, o si detecta que falta un argumento de opción,
       devuelve `?' y pone en la variable externa optopt el carácter de opción
       real.  Si  el primer carácter de optstring es un carácter de dos puntos
       (`:'), getopt() devuelve `:' en lugar de `?'  para indicar que falta un
       argumento  de  opción.  Si se detecta un error, y el primer carácter de
       optstring no es un carácter de dos puntos, y la variable externa opterr
       es  distinta de cero (que es el valor por defecto), getopt() muestra un
       mensaje de error.

       La función getopt_long() trabaja como getopt()  salvo  en  que  también
       acepta  opciones  largas, que empiezan por dos guiones.  Los nombres de
       opción largos pueden abreviarse si la abreviatura es única o si es  una
       concordancia exacta para alguna opción definida. Una opción larga puede
       tomar un parámetro, de la forma --arg=param o --arg param.

       longopts es un puntero al primer elemento de un vector de struct option
       declarado en <getopt.h> como

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

       Los significados de los diferentes campos son:

       name   es el nombre de la opción larga.

       has_arg
              es:  no_argument  (ó  0)  si  la  opción  no  toma un argumento,
              required_argument (ó 1) si la opción requiere  un  argumento,  u
              optional_argument (ó 2) si la opción toma un argumento opcional.

       flag   especifica  cómo  se  devuelven  los  resultados para una opción
              larga. Si flag es NULL,  entonces  getopt_long()  devuelve  val.
              (Por  ejemplo,  el  programa puede poner val como el carácter de
              opción corta equivalente.) De otro modo, getopt_long()  devuelve
              0,  y  flag apunta a una variable que se pone a val si la opción
              se encuentra, pero que se  deja  intacta  si  la  opción  no  se
              encuentra.

       val    es  el  valor a devolver, o a cargar en la variable apuntada por
              flag.

       El último elemento del vector tiene que ser llenado con ceros.

       Si longindex no es NULL, apunta a una variable que toma  el  valor  del
       índice de la opción larga relativa a longopts.

       getopt_long_only()  es  como  getopt_long(),  pero  tanto `-' como `--'
       pueden indicar una opción larga. Si una opción que empiece por `-'  (no
       `--')  no  concordara  con  una opción larga, pero sí con una corta, se
       consideraría como tal.

VALOR DEVUELTO

       La función getopt() devuelve el carácter de la opción  si  ésta  se  ha
       encontrado,  ':' si faltaba un parámetro de alguna de las opciones, '?'
       para un carácter de opción desconocida, o -1 si se ha llegado al  final
       de la lista de opciones.

       getopt_long()  y getopt_long_only() también devuelven el carácter de la
       opción cuendo se reconoce una corta. Para una opción  larga,  devuelven
       val   si  flag  es NULL, y 0 en otra circunstancia. Las devoluciones de
       error y -1 son las mismas que para  getopt(),  más  '?'  indicando  una
       concordancia ambigua o un parámetro extraño.

VARIABLES DE AMBIENTE

       POSIXLY_CORRECT
              Si  está  definida, entonces el procesamiento de las opciones se
              para tan pronto como se encuentre un argumento que  no  sea  una
              opción.

       _<PID>_GNU_nonoption_argv_flags_
              Esta  variable  era  utilizada por bash 2.0 para comunicar a GNU
              libc qué  argumentos  eran  el  resultado  de  la  expansión  de
              comodines  y,  por  tanto, no debían considerarse como opciones.
              Este comportamiento se eliminó en la versión 2.01 de  bash  pero
              el soporte permanece en GNU libc.

EJEMPLO

       El siguiente programa de ejemplo ilustra el empleo de getopt_long() con
       la mayoría de sus características.

       #include <stdio.h>     /* para printf */
       #include <stdlib.h>    /* para 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 (0);
       }

FALLOS

       La especificación POSIX.2 de getopt() tiene un error  técnico  descrito
       en   la  Interpretación  150  de  POSIX.2.  La  implementación  GNU  (y
       probablemente   el   resto   de   implementaciones)    implementa    el
       comportamiento correcto en lugar del indicado.

CONFORME A

       getopt():
              POSIX.2,  supuesto  que tengamos definida la variable de entorno
              POSIXLY_CORRECT. Si no, los elementos de argv no  son  realmente
              const,  puesto  que los permutamos. Los ponemos como const en el
              prototipo para compatibilidad con otros sistemas.