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

NOMBRE

       getopt - Analiza las opciones de la linea de ordenes

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'ON

       La  funcion getopt() analiza los argumentos de la linea de ordenes. Sus
       argumentos argc y argv son el numero y el vector de argumentos como los
       pasados a la funcion main() cuando se ejecuta el programa.  Un elemento
       de argv que comience con '-' (y que no sea exactamente "-" ni "--")  es
       un  elemento de opcion. Los caracteres de este elemento (aparte del '-'
       inicial) son caracteres de opcion. Si getopt() se llama  repetidamente,
       devuelve sucesivamente cada uno de los caracteres de opcion de cada uno
       de los elementos de opcion.

       Si  getopt()  encuentra  otro  caracter   de   opcion,   lo   devuelve,
       actualizando  la  variable  externa  optind  y  una  variable  estatica
       nextchar de forma que la siguiente llamada a getopt() pueda  seguir  la
       busqueda en el siguiente caracter de opcion o elemento de argv.

       Si  no  hay  mas  caracteres de opcion, getopt() devuelve -1.  Entonces
       optind es el indice en argv del primer elemento de argv que no  es  una
       opcion.

       optstring   es  una  cadena  que  contiene  los  caracteres  de  opcion
       legitimos. Si un caracter de estos es seguido por el  caracter  de  dos
       puntos,  la opcion 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 opcion 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  extension  de  GNU.  Si  optstring
       contiene  W  seguido por un punto y coma, entonces -W foo se trata como
       la opcion larga --foo.  (La opcion -W esta reservada  en  POSIX.2  para
       extensiones  de  implementacion).  Este comportamiento es una extension
       de GNU, no disponible en bibliotecas anteriores a la version 2  de  GNU
       libc.

       Por  omision,  getopt()  permuta  los  contenidos  de  argv  cuando  lo
       escudrina, de modo que todo lo que no sea una  opcion  vaya  al  final.
       Estan implementados otros dos modos de operacion. Si el primer caracter
       de  optstring  es  '+'  o  esta  definida  la  variable   de   ambiente
       POSIXLY_CORRECT,  entonces  el  procesamiento  de la opcion se para tan
       pronto se encuentra un argumento que no es una opcion.   Si  el  primer
       caracter de optstring es '-', entonces cada elemento de argv que no sea
       una opcion se maneja como si fuera  el  argumento  de  una  opcion  con
       codigo  de  caracter  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 caracter de opcion, muestra un mensaje de
       error en stderr, guarda el caracter  en  optopt,  y  devuelve  '?'.  El
       programa  que  llama  a  la  funcion  puede  evitar el mensaje de error
       poniendo opterr a 0.

       Si getopt() encuentra un caracter de  opcion  en  argv  que  no  estaba
       incluido  en  optstring, o si detecta que falta un argumento de opcion,
       devuelve `?' y pone en la variable externa optopt el caracter de opcion
       real.  Si  el primer caracter de optstring es un caracter de dos puntos
       (`:'), getopt() devuelve `:' en lugar de `?'  para indicar que falta un
       argumento  de  opcion.  Si se detecta un error, y el primer caracter de
       optstring no es un caracter 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 funcion getopt_long() trabaja como getopt()  salvo  en  que  tambien
       acepta  opciones  largas, que empiezan por dos guiones.  Los nombres de
       opcion largos pueden abreviarse si la abreviatura es unica o si es  una
       concordancia exacta para alguna opcion definida. Una opcion larga puede
       tomar un parametro, 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 opcion larga.

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

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

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

       El ultimo elemento del vector tiene que ser llenado con ceros.

       Si longindex no es NULL, apunta a una variable que toma  el  valor  del
       indice de la opcion larga relativa a longopts.

       getopt_long_only()  es  como  getopt_long(),  pero  tanto `-' como `--'
       pueden indicar una opcion larga. Si una opcion que empiece por `-'  (no
       `--')  no  concordara  con  una opcion larga, pero si con una corta, se
       consideraria como tal.

VALOR DEVUELTO

       La funcion getopt() devuelve el caracter de la opcion  si  esta  se  ha
       encontrado,  ':' si faltaba un parametro de alguna de las opciones, '?'
       para un caracter de opcion desconocida, o -1 si se ha llegado al  final
       de la lista de opciones.

       getopt_long()  y getopt_long_only() tambien devuelven el caracter de la
       opcion cuendo se reconoce una corta. Para una opcion  larga,  devuelven
       val   si  flag  es NULL, y 0 en otra circunstancia. Las devoluciones de
       error y -1 son las mismas que para  getopt(),  mas  '?'  indicando  una
       concordancia ambigua o un parametro extrano.

VARIABLES DE AMBIENTE

       POSIXLY_CORRECT
              Si  esta  definida, entonces el procesamiento de las opciones se
              para tan pronto como se encuentre un argumento que  no  sea  una
              opcion.

       _<PID>_GNU_nonoption_argv_flags_
              Esta  variable  era  utilizada por bash 2.0 para comunicar a GNU
              libc que  argumentos  eran  el  resultado  de  la  expansion  de
              comodines  y,  por  tanto, no debian considerarse como opciones.
              Este comportamiento se elimino en la version 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 mayoria de sus caracteristicas.

       #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 especificacion POSIX.2 de getopt() tiene un error  tecnico  descrito
       en   la  Interpretacion  150  de  POSIX.2.  La  implementacion  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.