1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329
|
.\" (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
.\"
.\" 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.
.\" 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 <jrv@vanzandt.mv.com>
.\" 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).
.\" Translated into Spanish Wed Jan 28 1998 by Gerardo Aburruzaga
.\" Garca <gerardo.aburruzaga@uca.es>
.\" Modified 8 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk)
.\" Translation revised Tue Aug 18 1998 by Juan Piernas <piernas@ditec.um.es>
.\" Translation revised Sat Jun 26 1999 by Juan Piernas <piernas@ditec.um.es>
.\"
.TH GETOPT 3 "8 Mayo 1998" "GNU" "Manual del Programador de Linux"
.SH NOMBRE
getopt \- Analiza las opciones de la lnea de rdenes
.SH SINOPSIS
.nf
.B #include <unistd.h>
.sp
.BI "int getopt(int " argc ", char * const " argv[] ","
.BI " const char *" optstring ");"
.sp
.BI "extern char *" optarg ;
.BI "extern int " optind ", " opterr ", " optopt ;
.sp
.B #define _GNU_SOURCE
.br
.B #include <getopt.h>
.sp
.BI "int getopt_long(int " argc ", char * const " argv[] ",
.BI " const char *" optstring ,
.BI " const struct option *" longopts ", int *" longindex ");"
.sp
.BI "int getopt_long_only(int " argc ", char * const " argv[] ",
.BI " const char *" optstring ,
.BI " const struct option *" longopts ", int *" longindex ");"
.fi
.SH DESCRIPCIN
La funcin
.B getopt()
analiza los argumentos de la lnea de rdenes. Sus argumentos
.I argc
y
.I argv
son el nmero y el vector de argumentos como los pasados a la funcin
.B main()
cuando se ejecuta el programa.
Un elemento de \fIargv\fP que comience con '-' (y que no sea
exactamente "-" ni "--") es un elemento de opcin. Los caracteres de
este elemento (aparte del '-' inicial) son caracteres de opcin. Si
\fBgetopt()\fP se llama repetidamente, devuelve sucesivamente cada uno
de los caracteres de opcin de cada uno de los elementos de opcin.
.PP
Si \fBgetopt()\fP encuentra otro carcter de opcin, lo devuelve,
actualizando la variable externa \fIoptind\fP y una variable esttica
\fInextchar\fP de forma que la siguiente llamada a \fBgetopt()\fP
pueda seguir la bsqueda en el siguiente carcter de opcin o elemento
de \fIargv\fP.
.PP
Si no hay ms caracteres de opcin, \fBgetopt()\fP devuelve
\fBEOF\fP. Entonces \fIoptind\fP es el ndice en \fIargv\fP del primer
elemento de \fIargv\fP que no es una opcin.
.PP
.I optstring
es una cadena que contiene los caracteres de opcin legtimos. Si un
carcter de stos es seguido por el carcter de dos puntos, la opcin
necesita un argumento, de forma que
\fBgetopt\fP coloca un puntero al texto siguiente en el mismo elemento
de \fIargv\fP, o el texto del siguiente elemento de \fIargv\fP, en
.IR optarg .
Dos caracteres de dos puntos significan que una opcin toma un
arg. opcional; si hay texto en el elemento de \fIargv\fP actual, se
devuelve en \fIoptarg\fP; si no, \fIoptarg\fP se pone a cero.
Lo siguiente es una extensin de GNU. Si
.I optstring
contiene
.B W
seguido por un punto y coma, entonces
.B -W foo
se trata como la opcin larga
.BR --foo .
(La opcin
.B -W
est reservada en POSIX.2 para extensiones de implementacin).
Este comportamiento es una extensin de GNU, no disponible en bibliotecas
anteriores a la versin 2 de GNU libc.
.PP
Por omisin, \fBgetopt()\fP permuta los contenidos de \fIargv\fP
cuando lo escudria, de modo que todo lo que no sea una opcin vaya
al final. Estn implementados otros dos modos de operacin. Si el
primer carcter de \fIoptstring\fP es '+' o est definida la variable
de ambiente POSIXLY_CORRECT, entonces el procesamiento de la opcin se
para tan pronto se encuentra un argumento que no es una opcin.
Si el primer carcter de \fIoptstring\fP es '-', entonces cada
elemento de \fIargv\fP que no sea una opcin se maneja como si fuera
el argumento de una opcin con cdigo de carcter 1. (Esto se usa en
programas que fueron escritos para esperar opciones y otros elementos
de \fIargv\fP 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.
.PP
Si \fBgetopt()\fP no reconoce un carcter de opcin, muestra un
mensaje de error en stderr, guarda el carcter en \fIoptopt\fP, y
devuelve '?'. El programa que llama a la funcin puede evitar el
mensaje de error poniendo \fIopterr\fP a 0.
.PP
La funcin
.B getopt_long()
trabaja como
.B getopt()
salvo en que tambin acepta opciones largas, que empiezan por dos guiones.
Los nombres de opcin largos pueden abreviarse si la abreviatura es
nica o si es una concordancia exacta para alguna opcin definida. Una
opcin larga puede tomar un parmetro, de la forma
.B --arg=param
o
.BR "--arg param" .
.PP
.I longopts
es un puntero al primer elemento de un vector de
.B struct option
declarado en
.B <getopt.h>
como
.nf
.sp
.in 10
struct option {
.in 14
const char *name;
int has_arg;
int *flag;
int val;
.in 10
};
.fi
.PP
Los significados de los diferentes campos son:
.TP
.I name
es el nombre de la opcin larga.
.TP
.I has_arg
es:
\fBno_argument\fP ( 0) si la opcin no toma un argumento,
\fBrequired_argument\fP ( 1) si la opcin requiere un argumento, u
\fBoptional_argument\fP ( 2) si la opcin toma un argumento opcional.
.TP
.I flag
especifica cmo se devuelven los resultados para una opcin larga. Si
\fIflag\fP es \fBNULL\fP, entonces \fBgetopt_long()\fP devuelve
\fIval\fP. (Por ejemplo, el programa puede poner \fIval\fP como el
carcter de opcin corta equivalente.) De otro modo,
\fBgetopt_long()\fP devuelve 0, y \fIflag\fP apunta a una variable que
se pone a \fIval\fP si la opcin se encuentra, pero que se deja
intacta si la opcin no se encuentra.
.TP
\fIval\fP
es el valor a devolver, o a cargar en la variable apuntada por \fIflag\fP.
.PP
El ltimo elemento del vector tiene que ser llenado con ceros.
.PP
Si \fIlongindex\fP no es \fBNULL\fP, apunta a una variable que toma el
valor del ndice de la opcin larga relativa a
.IR longopts .
.PP
\fBgetopt_long_only()\fP es como \fBgetopt_long()\fP, pero tanto `-'
como `--' pueden indicar una opcin larga. Si una opcin que empiece
por `-' (no `--') no concordara con una opcin larga, pero s con una
corta, se considerara como tal.
.SH "VALOR DEVUELTO"
La funcin
.B getopt()
devuelve el carcter de la opcin si sta se ha encontrado, ':' si
faltaba un parmetro de alguna de las opciones, '?' para un carcter
de opcin desconocida, o \fBEOF\fP si se ha llegado al final de la
lista de opciones.
.PP
\fBgetopt_long()\fP y \fBgetopt_long_only()\fP tambin devuelven el
carcter de la opcin cuendo se reconoce una corta. Para una opcin
larga, devuelven \fIval\fP si \fIflag\fP es \fBNULL\fP, y 0 en otra
circunstancia. Las devoluciones de error y EOF son las mismas que para
\fBgetopt()\fP, ms '?' indicando una concordancia ambigua o un
parmetro extrao.
.SH "VARIABLES DE AMBIENTE"
.TP
.SM
.B POSIXLY_CORRECT
Si est definida, entonces el procesamiento de las opciones se para
tan pronto como se encuentre un argumento que no sea una opcin.
.TP
.SM
.B _<PID>_GNU_nonoption_argv_flags_
Esta variable era utilizada por
.B bash
2.0 para comunicar a GNU libc qu argumentos eran el resultado de la
expansin de comodines y, por tanto, no deban considerarse como opciones.
Este comportamiento se elimin en la versin 2.01 de
.B bash
pero el soporte permanece en GNU libc.
.SH "EJEMPLO"
El siguiente programa de ejemplo, del cdigo fuente, ilustra el empleo
de
.BR getopt_long()
con la mayora de sus caractersticas.
.nf
.sp
#include <stdio.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 ("optcin %s", long_options[option_index].name);
if (optarg)
printf (" con arg %s", optarg);
printf ("\\n");
break;
case '0':
case '1':
case '2':
if (digit_optind != 0 && digit_optind != this_option_optind)
printf ("hay dgitos en dos elementos de argv diferentes.\\n");
digit_optind = this_option_optind;
printf ("opcin %c\\n", c);
break;
case 'a':
printf ("opcin a\\n");
break;
case 'b':
printf ("opcin b\\n");
break;
case 'c':
printf ("opcin c con valor `%s'\\n", optarg);
break;
case 'd':
printf ("opcin d con valor `%s'\\n", optarg);
break;
case '?':
break;
default:
printf ("?\\? getopt() devolvi el carcter de cdigo 0%o ?\\?\\n", c);
}
}
if (optind < argc)
{
printf ("elementos de ARGV que no son opciones: ");
while (optind < argc)
printf ("%s ", argv[optind++]);
printf ("\\n");
}
return (0);
}
.fi
.SH "FALLOS"
Esta pgina de manual no hay quien la entienda.
.\"This manpage is confusing.
.PP
La especificacin POSIX.2 de
.B getopt()
tiene un error tcnico descrito en la Interpretacin 150 de POSIX.2. La
implementacin GNU (y probablemente el resto de implementaciones) implementa
el comportamiento correcto en lugar del indicado.
.SH "CONFORME A"
.TP
\fBgetopt()\fP:
POSIX.2, supuesto que tengamos definida la variable de entorno
POSIXLY_CORRECT. Si no, los elementos de \fIargv\fP no son realmente
const, puesto que los permutamos. Los ponemos como const en el
prototipo para compatibilidad con otros sistemas.
|