File: getopt.3

package info (click to toggle)
manpages-es 1.24a-6
  • links: PTS
  • area: main
  • in suites: potato
  • size: 4,256 kB
  • ctags: 7
  • sloc: makefile: 66; sh: 62
file content (329 lines) | stat: -rw-r--r-- 11,195 bytes parent folder | download
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.