« back to all changes in this revision
Viewing changes to .pc/278402-manpage.patch/popt.3
- browse files at revision 7
- compare with another revision
- download diff
- download tarball
- view history from revision 7
- Committer: Bazaar Package Importer
- Author(s): Paul Martin
- Date: 2010-05-13 05:14:50 UTC
- mfrom: (1.1.5 upstream)
- Revision ID: james.westby@ubuntu.com-20100513051450-1qefp4e2if4hbkri
Tags: 1.16-1
* New upstream release (Closes: #581439)
* Switch to dpkg-source 3.0 (quilt) format
* Add a watch file.
* Update to standards version 3.8.4 (no changes)
* Switch to dpkg-source 3.0 (quilt) format
* Add a watch file.
* Update to standards version 3.8.4 (no changes)
added
removed
.pc/278402-manpage.patch/popt.3
1
.TH POPT 3 "June 30, 1998" "" "Linux Programmer's Manual"
2
.SH NAME
3
popt \- Parse command line options
4
.SH SYNOPSIS
5
.nf
6
.B #include <popt.h>
7
.sp
8
.BI "poptContext poptGetContext(const char * " name ", int " argc ,
9
.BI " const char ** "argv ,
10
.BI " const struct poptOption * " options ,
11
.BI " int " flags );
12
.sp
13
.BI "void poptFreeContext(poptContext " con );
14
.sp
15
.BI "void poptResetContext(poptContext " con );
16
.sp
17
.BI "int poptGetNextOpt(poptContext " con );
18
.sp
19
.BI "const char * poptGetOptArg(poptContext " con );
20
.sp
21
.BI "const char * poptGetArg(poptContext " con );
22
.sp
23
.BI "const char * poptPeekArg(poptContext " con );
24
.sp
25
.BI "const char ** poptGetArgs(poptContext " con );
26
.sp
27
.BI "const char *const poptStrerror(const int " error );
28
.sp
29
.BI "const char * poptBadOption(poptContext " con ", int " flags );
30
.sp
31
.BI "int poptReadDefaultConfig(poptContext " con ", int " flags );
32
.sp
33
.BI "int poptReadConfigFile(poptContext " con ", char * " fn );
34
.sp
35
.BI "int poptAddAlias(poptContext " con ", struct poptAlias " alias ,
36
.BI " int " flags );
37
.sp
38
.BI "int poptParseArgvString(char * " s ", int * " argcPtr ,
39
.BI " const char *** " argvPtr );
40
.sp
41
.BI "int poptDupArgv(int " argc ", const char ** " argv ", int * " argcPtr ",
42
.BI " const char *** " argvPtr ");"
43
.sp
44
.BI "int poptStuffArgs(poptContext " con ", const char ** " argv );
45
.sp
46
.fi
47
.SH DESCRIPTION
48
The popt library exists essentially for parsing command-line
49
options. It is found superior in many ways when compared to
50
parsing the argv array by hand or using the getopt functions
51
.B getopt()
52
and
53
.B getopt_long()
54
[see
55
.BR getopt "(3)]."
56
Some specific advantages of popt are: it does not utilize global
57
.RI "variables, thus enabling multiple passes in parsing " argv
58
.RI "; it can parse an arbitrary array of " argv "-style elements, "
59
allowing parsing of command-line-strings from any source;
60
it provides a standard method of option aliasing (to be
61
discussed at length below.); it can exec external option filters; and,
62
finally, it can automatically generate help and usage messages for
63
the application.
64
.sp
65
Like
66
.BR getopt_long() ,
67
the popt library supports short and long style options. Recall
68
that a
69
.B short option
70
consists of a - character followed by a single alphanumeric character.
71
A
72
.BR "long option" ,
73
common in GNU utilities, consists of two - characters followed by a
74
string made up of letters, numbers and hyphens. Long options are
75
optionally allowed to begin with a single -, primarily to allow command-line
76
compatibility between popt applications and X toolkit applications.
77
Either type of option may be followed by an argument. A space separates a
78
short option from its arguments; either a space or an = separates a long
79
option from an argument.
80
.sp
81
The popt library is highly portable and should work on any POSIX
82
platform. The latest version is distributed with rpm and is always available
83
from: ftp://ftp.rpm.org/pub/rpm/dist.
84
.sp
85
It may be redistributed under the X consortium license, see the file COPYING
86
in the popt source distribution for details.
87
.SH "BASIC POPT USAGE"
88
.SS "1. THE OPTION TABLE"
89
Applications provide popt with information on their command-line
90
options by means of an "option table," i.e., an array of
91
.B struct poptOption
92
structures:
93
.sp
94
#include <popt.h>
95
.sp
96
.nf
97
struct poptOption {
98
const char * longName; /* may be NULL */
99
char shortName; /* may be '\\0' */
100
int argInfo;
101
void * arg; /* depends on argInfo */
102
int val; /* 0 means don't return, just update flag */
103
char * descrip; /* description for autohelp -- may be NULL */
104
char * argDescrip; /* argument description for autohelp */
105
};
106
.fi
107
.sp
108
Each member of the table defines a single option that may be
109
passed to the program. Long and short options are considered
110
a single option that may occur in two different forms. The
111
first two members,
112
.IR longName " and " shortName ", define the names of the option;"
113
the first is a long name, while the latter is a single character.
114
.sp
115
The
116
.IR argInfo " member tells popt what type of argument is expected"
117
after the option. If no argument is expected,
118
.B POPT_ARG_NONE
119
should be used.
120
The rest of the valid values are shown in the following table:
121
.sp
122
.TS
123
lfB lfB lfB
124
lfB lfR lfR.
125
Value Description arg Type
126
POPT_ARG_NONE No argument expected int
127
POPT_ARG_STRING No type checking to be performed char *
128
POPT_ARG_ARGV No type checking to be performed char **
129
POPT_ARG_SHORT An short argument is expected short
130
POPT_ARG_INT An integer argument is expected int
131
POPT_ARG_LONG A long integer is expected long
132
POPT_ARG_LONGLONG A long long integer is expected long long
133
POPT_ARG_VAL Integer value taken from \f(CWval\fR int
134
POPT_ARG_FLOAT An float argument is expected float
135
POPT_ARG_DOUBLE A double argument is expected double
136
.TE
137
.sp
138
For numeric values, if the \fIargInfo\fR value is bitwise or'd with one of
139
\fBPOPT_ARGFLAG_OR\fR, \fBPOPT_ARGFLAG_AND\fR, or \fBPOPT_ARGFLAG_XOR\fR,
140
the value is saved by performing an OR, AND, or XOR.
141
If the \fIargInfo\fR value is bitwise or'd with \fBPOPT_ARGFLAG_NOT\fR,
142
the value will be negated before saving. For the common operations of
143
setting and/or clearing bits, \fBPOPT_BIT_SET\fR and \fBPOPT_BIT_CLR\fR
144
have the appropriate flags set to perform bit operations.
145
.sp
146
If the \fIargInfo\fR value is bitwise or'd with \fBPOPT_ARGFLAG_ONEDASH\fR,
147
the long argument may be given with a single - instead of two. For example,
148
if \fB--longopt\fR is an option with \fBPOPT_ARGFLAG_ONEDASH\fR, is
149
specified, \fB-longopt\fR is accepted as well.
150
.sp
151
.RI "The next element, " arg ", allows popt to automatically update "
152
.RI "program variables when the option is used. If " arg " is "
153
.BR NULL ", it is ignored and popt takes no special action. "
154
Otherwise it should point to a variable of the type indicated in the
155
.RB "right-most column of the table above. A " POPT_ARG_ARGV " arg will
156
(re-)allocate an array of char * string pointers, append the string argument, and add a
157
.BR NULL " sentinel at the end of the array as needed."
158
.RB "The target char ** address of a " POPT_ARG_ARGV " arg should be initialized to " NULL "."
159
.sp
160
.RI "If the option takes no argument (" argInfo " is "
161
.BR POPT_ARG_NONE "), the variable pointed to by "
162
.IR arg " is set to 1 when the option is used. (Incidentally, it "
163
will perhaps not escape the attention of hunt-and-peck typists that
164
.RB "the value of " POPT_ARG_NONE " is 0.) If the option does take "
165
an argument, the variable that
166
.IR arg " points to is updated to reflect the value of the argument."
167
.RB "Any string is acceptable for " POPT_ARG_STRING " and " POPT_ARG_ARGV " arguments, but "
168
.BR POPT_ARG_INT ", " POPT_ARG_SHORT ", " POPT_ARG_LONG ", " POPT_ARG_LONGLONG ", " POPT_ARG_FLOAT ", and "
169
.BR POPT_ARG_DOUBLE " are converted to the appropriate type, and an "
170
error returned if the conversion fails.
171
.sp
172
\fBPOPT_ARG_VAL\fR causes \fIarg\fP to be set to the (integer) value of
173
\fIval\fP when the argument is found. This is most often useful for
174
mutually-exclusive arguments in cases where it is not an error for
175
multiple arguments to occur and where you want the last argument
176
specified to win; for example, "rm -i -f". \fBPOPT_ARG_VAL\fP causes
177
the parsing function not to return a value, since the value of \fIval\fP
178
has already been used.
179
.sp
180
If the \fIargInfo\fR value is bitwise or'd with \fBPOPT_ARGFLAG_OPTIONAL\fR,
181
the argument to the long option may be omitted. If the long option
182
is used without an argument, a default value of zero or NULL will be saved
183
(if the arg pointer is present), otherwise behavior will be identical to
184
a long option with argument.
185
.sp
186
.RI "The next option, " val ", is the value popt's parsing function
187
should return when the option is encountered. If it is 0, the parsing
188
function does not return a value, instead parsing the next
189
command-line argument.
190
.sp
191
.RI "The last two options, " descrip " and " argDescrip " are only required
192
if automatic help messages are desired (automatic usage messages can
193
.RI "be generated without them). " descrip " is a text description of the
194
.RI "argument and " argdescrip " is a short summary of the type of arguments
195
.RI "the option expects, or NULL if the option doesn't require any
196
arguments.
197
.sp
198
.RB "If popt should automatically provide " --usage " and " --help " (" -? ")
199
.RB "options, one line in the table should be the macro " POPT_AUTOHELP ".
200
.RB "This macro includes another option table (via " POPT_ARG_INCLUDE_TABLE
201
; see below) in the main one which provides the table entries for these
202
.RB "arguments. When " --usage " or " --help " are passed to programs which
203
use popt's automatic help, popt displays the appropriate message on
204
stderr as soon as it finds the option, and exits the program with a
205
return code of 0. If you want to use popt's automatic help generation in
206
a different way, you need to explicitly add the option entries to your programs
207
.RB "option table instead of using " POPT_AUTOHELP ".
208
.sp
209
If the \fIargInfo\fR value is bitwise or'd with \fBPOPT_ARGFLAG_DOC_HIDDEN\fR,
210
the argument will not be shown in help output.
211
.sp
212
If the \fIargInfo\fR value is bitwise or'd with \fBPOPT_ARGFLAG_SHOW_DEFAULT\fR,
213
the initial value of the arg will be shown in help output.
214
.sp
215
The final structure in the table should have all the pointer values set
216
.RB "to " NULL " and all the arithmetic values set to 0, marking the "
217
.RB "end of the table. The macro " POPT_TABLEEND " is provided to do that.
218
.sp
219
There are two types of option table entries which do not specify command
220
line options. When either of these types of entries are used, the
221
\fIlongName\fR element must be \fBNULL\fR and the \fBshortName\fR element
222
must be \fB'\\0'\fR.
223
.sp
224
The first of these special entry types allows the application to nest
225
another option table in the current one; such nesting may extend quite
226
deeply (the actual depth is limited by the program's stack). Including
227
other option tables allows a library to provide a standard set of
228
command-line options to every program which uses it (this is often done
229
in graphical programming toolkits, for example). To do this, set
230
the \fIargInfo\fR field to \fBPOPT_ARG_INCLUDE_TABLE\fR and the
231
\fRarg\fR field to point to the table which is being included. If
232
automatic help generation is being used, the \fIdescrip\fR field should
233
contain a overall description of the option table being included.
234
.sp
235
The other special option table entry type tells popt to call a function (a
236
callback) when any option in that table is found. This is especially useful
237
when included option tables are being used, as the program which provides
238
the top-level option table doesn't need to be aware of the other options
239
which are provided by the included table. When a callback is set for
240
a table, the parsing function never returns information on an option in
241
the table. Instead, options information must be retained via the callback
242
or by having popt set a variable through the option's \fIarg\fR field.
243
Option callbacks should match the following prototype:
244
.sp
245
.nf
246
.BI "void poptCallbackType(poptContext con,
247
.BI " const struct poptOption * opt,
248
.BI " const char * arg, void * data);
249
.fi
250
.sp
251
The first parameter is the context which is being parsed (see the next
252
section for information on contexts), \fIopt\fR points to the option
253
which triggered this callback, and \fIarg\fR is the option's argument.
254
If the option does not take an argument, \fIarg\fR is \fBNULL\fR. The
255
final parameter, \fIdata\fR is taken from the \fIdescrip\fR field
256
of the option table entry which defined the callback. As \fIdescrip\fR
257
is a pointer, this allows callback functions to be passed an arbitrary
258
set of data (though a typecast will have to be used).
259
.sp
260
The option table entry which defines a callback has an \fIargInfo\fR of
261
\fBPOPT_ARG_CALLBACK\fR, an \fIarg\fR which points to the callback
262
function, and a \fIdescrip\fR field which specifies an arbitrary pointer
263
to be passed to the callback.
264
.SS "2. CREATING A CONTEXT"
265
popt can interleave the parsing of multiple command-line sets. It allows
266
this by keeping all the state information for a particular set of
267
command-line arguments in a
268
.BR poptContext " data structure, an opaque type that should not be "
269
modified outside the popt library.
270
.sp
271
.RB "New popt contexts are created by " poptGetContext() ":"
272
.sp
273
.nf
274
.BI "poptContext poptGetContext(const char * " name ", int "argc ",
275
.BI " const char ** "argv ",
276
.BI " const struct poptOption * "options ",
277
.BI " int "flags ");"
278
.fi
279
.sp
280
The first parameter,
281
.IR name ", is used only for alias handling (discussed later). It "
282
should be the name of the application whose options are being parsed,
283
.RB "or should be " NULL " if no option aliasing is desired. The next "
284
two arguments specify the command-line arguments to parse. These are
285
.RB "generally passed to " poptGetContext() " exactly as they were "
286
.RB "passed to the program's " main() " function. The "
287
.IR options " parameter points to the table of command-line options, "
288
which was described in the previous section. The final parameter,
289
.IR flags ,
290
can take one of three values:
291
.br
292
.TS
293
lfB lfB
294
lfB lfR.
295
Value Description
296
POPT_CONTEXT_NO_EXEC Ignore exec expansions
297
POPT_CONTEXT_KEEP_FIRST Do not ignore argv[0]
298
POPT_CONTEXT_POSIXMEHARDER Options cannot follow arguments
299
.TE
300
.sp
301
.RB "A " poptContext " keeps track of which options have already been "
302
parsed and which remain, among other things. If a program wishes to
303
restart option processing of a set of arguments, it can reset the
304
.BR poptContext " by passing the context as the sole argument to "
305
.BR poptResetContext() .
306
.sp
307
When argument processing is complete, the process should free the
308
.BR poptContext " as it contains dynamically allocated components. The "
309
.BR poptFreeContext() " function takes a "
310
.BR poptContext " as its sole argument and frees the resources the "
311
context is using.
312
.sp
313
.RB "Here are the prototypes of both " poptResetContext() " and "
314
.BR poptFreeContext() :
315
.sp
316
.nf
317
.B #include <popt.h>
318
.BI "void poptFreeContext(poptContext " con ");"
319
.BI "void poptResetContext(poptContext " con ");"
320
.fi
321
.sp
322
.SS "3. PARSING THE COMMAND LINE"
323
.RB "After an application has created a " poptContext ", it may begin "
324
.RB "parsing arguments. " poptGetNextOpt() " performs the actual "
325
argument parsing.
326
.sp
327
.nf
328
.B #include <popt.h>
329
.BI "int poptGetNextOpt(poptContext " con ");"
330
.fi
331
.sp
332
Taking the context as its sole argument, this function parses the next
333
command-line argument found. After finding the next argument in the
334
option table, the function fills in the object pointed to by the option
335
.RI "table entry's " arg
336
.RB "pointer if it is not " NULL ". If the val entry for the option is "
337
non-0, the function then returns that value. Otherwise,
338
.BR poptGetNextOpt() " continues on to the next argument."
339
.sp
340
.BR poptGetNextOpt() " returns -1 when the final argument has been "
341
parsed, and other negative values when errors occur. This makes it a
342
good idea to
343
.RI "keep the " val " elements in the options table greater than 0."
344
.sp
345
.RI "If all of the command-line options are handled through " arg
346
pointers, command-line parsing is reduced to the following line of code:
347
.sp
348
.nf
349
rc = poptGetNextOpt(poptcon);
350
.fi
351
.sp
352
Many applications require more complex command-line parsing than this,
353
however, and use the following structure:
354
.sp
355
.nf
356
while ((rc = poptGetNextOpt(poptcon)) > 0) {
357
switch (rc) {
358
/* specific arguments are handled here */
359
}
360
}
361
.fi
362
.sp
363
When returned options are handled, the application needs to know the
364
value of any arguments that were specified after the option. There are two
365
ways to discover them. One is to ask popt to fill in a variable with the
366
.RI "value of the option through the option table's " arg " elements. The "
367
.RB "other is to use " poptGetOptArg() ":"
368
.sp
369
.nf
370
.B #include <popt.h>
371
.BI "char * poptGetOptArg(poptContext " con ");"
372
.fi
373
.sp
374
This function returns the argument given for the final option returned by
375
.BR poptGetNextOpt() ", or it returns " NULL " if no argument was specified."
376
The calling function is responsible for deallocating this string.
377
.sp
378
.SS "4. LEFTOVER ARGUMENTS"
379
Many applications take an arbitrary number of command-line arguments,
380
such as a list of file names. When popt encounters an argument that does
381
not begin with a -, it assumes it is such an argument and adds it to a list
382
of leftover arguments. Three functions allow applications to access such
383
arguments:
384
.nf
385
.HP
386
.BI "const char * poptGetArg(poptContext " con ");"
387
.fi
388
This function returns the next leftover argument and marks it as
389
processed.
390
.PP
391
.nf
392
.HP
393
.BI "const char * poptPeekArg(poptContext " con ");"
394
.fi
395
The next leftover argument is returned but not marked as processed.
396
This allows an application to look ahead into the argument list,
397
without modifying the list.
398
.PP
399
.nf
400
.HP
401
.BI "const char ** poptGetArgs(poptContext " con ");"
402
.fi
403
All the leftover arguments are returned in a manner identical to
404
.IR argv ". The final element in the returned array points to "
405
.BR NULL ", indicating the end of the arguments.
406
.sp
407
.SS "5. AUTOMATIC HELP MESSAGES"
408
The \fBpopt\fR library can automatically generate help messages which
409
describe the options a program accepts. There are two types of help
410
messages which can be generated. Usage messages are a short messages
411
which lists valid options, but does not describe them. Help messages
412
describe each option on one (or more) lines, resulting in a longer, but
413
more useful, message. Whenever automatic help messages are used, the
414
\fBdescrip\fR and \fBargDescrip\fR fields \fBstruct poptOption\fR members
415
should be filled in for each option.
416
.sp
417
The \fBPOPT_AUTOHELP\fR macro makes it easy to add \fB--usage\fR and
418
\fB--help\fR messages to your program, and is described in part 1
419
of this man page. If more control is needed over your help messages,
420
the following two functions are available:
421
.sp
422
.nf
423
.B #include <popt.h>
424
.BI "void poptPrintHelp(poptContext " con ", FILE * " f ", int " flags ");
425
.BI "void poptPrintUsage(poptContext " con ", FILE * " f ", int " flags ");
426
.fi
427
.sp
428
\fBpoptPrintHelp()\fR displays the standard help message to the stdio file
429
descriptor f, while \fBpoptPrintUsage()\fR displays the shorter usage
430
message. Both functions currently ignore the \fBflags\fR argument; it is
431
there to allow future changes.
432
.sp
433
.SH "ERROR HANDLING"
434
All of the popt functions that can return errors return integers.
435
When an error occurs, a negative error code is returned. The
436
following table summarizes the error codes that occur:
437
.sp
438
.nf
439
.B " Error Description"
440
.BR "POPT_ERROR_NOARG " "Argument missing for an option."
441
.BR "POPT_ERROR_BADOPT " "Option's argument couldn't be parsed."
442
.BR "POPT_ERROR_OPTSTOODEEP " "Option aliasing nested too deeply."
443
.BR "POPT_ERROR_BADQUOTE " "Quotations do not match."
444
.BR "POPT_ERROR_BADNUMBER " "Option couldn't be converted to number."
445
.BR "POPT_ERROR_OVERFLOW " "A given number was too big or small."
446
.fi
447
.sp
448
Here is a more detailed discussion of each error:
449
.sp
450
.TP
451
.B POPT_ERROR_NOARG
452
An option that requires an argument was specified on the command
453
line, but no argument was given. This can be returned only by
454
.BR poptGetNextOpt() .
455
.sp
456
.TP
457
.B POPT_ERROR_BADOPT
458
.RI "An option was specified in " argv " but is not in the option
459
.RB "table. This error can be returned only from " poptGetNextOpt() .
460
.sp
461
.TP
462
.B POPT_ERROR_OPTSTOODEEP
463
A set of option aliases is nested too deeply. Currently, popt
464
follows options only 10 levels to prevent infinite recursion. Only
465
.BR poptGetNextOpt() " can return this error."
466
.sp
467
.TP
468
.B POPT_ERROR_BADQUOTE
469
A parsed string has a quotation mismatch (such as a single quotation
470
.RB "mark). " poptParseArgvString() ", " poptReadConfigFile() ", or "
471
.BR poptReadDefaultConfig() " can return this error."
472
.sp
473
.TP
474
.B POPT_ERROR_BADNUMBER
475
A conversion from a string to a number (int or long) failed due
476
to the string containing nonnumeric characters. This occurs when
477
.BR poptGetNextOpt() " is processing an argument of type "
478
.BR POPT_ARG_INT ", " POPT_ARG_SHORT ", " POPT_ARG_LONG ", " POPT_ARG_LONGLONG ", "
479
.RB POPT_ARG_FLOAT ", or " POPT_ARG_DOUBLE "."
480
.sp
481
.TP
482
.B POPT_ERROR_OVERFLOW
483
A string-to-number conversion failed because the number was too
484
.RB "large or too small. Like " POPT_ERROR_BADNUMBER ", this error
485
.RB "can occur only when " poptGetNextOpt() " is processing an "
486
.RB "argument of type " POPT_ARG_INT ", " POPT_ARG_SHORT ", " POPT_ARG_LONG ", " POPT_ARG_LONGLONG ", "
487
.RB POPT_ARG_FLOAT ", or " POPT_ARG_DOUBLE "."
488
.sp
489
.TP
490
.B POPT_ERROR_ERRNO
491
.RI "A system call returned with an error, and " errno " still
492
contains the error from the system call. Both
493
.BR poptReadConfigFile() " and " poptReadDefaultConfig() " can "
494
return this error.
495
.sp
496
.PP
497
Two functions are available to make it easy for applications to provide
498
good error messages.
499
.HP
500
.nf
501
.BI "const char *const poptStrerror(const int " error ");"
502
.fi
503
This function takes a popt error code and returns a string describing
504
.RB "the error, just as with the standard " strerror() " function."
505
.PP
506
.HP
507
.nf
508
.BI "const char * poptBadOption(poptContext " con ", int " flags ");"
509
.fi
510
.RB "If an error occurred during " poptGetNextOpt() ", this function "
511
.RI "returns the option that caused the error. If the " flags " argument"
512
.RB "is set to " POPT_BADOPTION_NOALIAS ", the outermost option is "
513
.RI "returned. Otherwise, " flags " should be 0, and the option that is "
514
returned may have been specified through an alias.
515
.PP
516
These two functions make popt error handling trivial for most
517
applications. When an error is detected from most of the functions,
518
an error message is printed along with the error string from
519
.BR poptStrerror() ". When an error occurs during argument parsing, "
520
code similar to the following displays a useful error message:
521
.sp
522
.nf
523
fprintf(stderr, "%s: %s\\n",
524
poptBadOption(optCon, POPT_BADOPTION_NOALIAS),
525
poptStrerror(rc));
526
.fi
527
.sp
528
.SH "OPTION ALIASING"
529
.RB "One of the primary benefits of using popt over " getopt() " is the "
530
ability to use option aliasing. This lets the user specify options that
531
popt expands into other options when they are specified. If the standard
532
.RB "grep program made use of popt, users could add a " --text " option "
533
.RB "that expanded to " "-i -n -E -2" " to let them more easily find "
534
information in text files.
535
.sp
536
.SS "1. SPECIFYING ALIASES"
537
.RI "Aliases are normally specified in two places: " /etc/popt
538
.RB "and the " .popt " file in the user's home directory (found through "
539
.RB "the " HOME " environment variable). Both files have the same format, "
540
an arbitrary number of lines formatted like this:
541
.sp
542
.IB appname " alias " newoption "" " expansion"
543
.sp
544
.RI "The " appname " is the name of the application, which must be the "
545
.RI "same as the " name " parameter passed to "
546
.BR poptGetContext() ". This allows each file to specify aliases for "
547
.RB "multiple programs. The " alias " keyword specifies that an alias is "
548
being defined; currently popt configuration files support only aliases, but
549
other abilities may be added in the future. The next option is the option
550
that should be aliased, and it may be either a short or a long option. The
551
rest of the line specifies the expansion for the alias. It is parsed
552
similarly to a shell command, which allows \\, ", and ' to be used for
553
quoting. If a backslash is the final character on a line, the next line
554
in the file is assumed to be a logical continuation of the line containing
555
the backslash, just as in shell.
556
.sp
557
.RB "The following entry would add a " --text " option to the grep command, "
558
as suggested at the beginning of this section.
559
.sp
560
.B "grep alias --text -i -n -E -2"
561
.SS "2. ENABLING ALIASES"
562
.RB "An application must enable alias expansion for a " poptContext
563
.RB "before calling " poptGetNextArg() " for the first time. There are "
564
three functions that define aliases for a context:
565
.HP
566
.nf
567
.BI "int poptReadDefaultConfig(poptContext " con ", int " flags ");"
568
.fi
569
.RI "This function reads aliases from " /etc/popt " and the "
570
.BR .popt " file in the user's home directory. Currently, "
571
.IR flags " should be "
572
.BR NULL ", as it is provided only for future expansion."
573
.PP
574
.HP
575
.nf
576
.BI "int poptReadConfigFile(poptContext " con ", char * " fn ");"
577
.fi
578
.RI "The file specified by " fn " is opened and parsed as a popt "
579
configuration file. This allows programs to use program-specific
580
configuration files.
581
.PP
582
.HP
583
.nf
584
.BI "int poptAddAlias(poptContext " con ", struct poptAlias " alias ",
585
.BI " int " flags ");"
586
.fi
587
Occasionally, processes want to specify aliases without having to
588
read them from a configuration file. This function adds a new alias
589
.RI "to a context. The " flags " argument should be 0, as it is "
590
currently reserved for future expansion. The new alias is specified
591
.RB "as a " "struct poptAlias" ", which is defined as:"
592
.sp
593
.nf
594
struct poptAlias {
595
const char * longName; /* may be NULL */
596
char shortName; /* may be '\\0' */
597
int argc;
598
const char ** argv; /* must be free()able */
599
};
600
.fi
601
.sp
602
.RI "The first two elements, " longName " and " shortName ", specify "
603
.RI "the option that is aliased. The final two, " argc " and " argv ","
604
define the expansion to use when the aliases option is encountered.
605
.PP
606
.SH "PARSING ARGUMENT STRINGS"
607
Although popt is usually used for parsing arguments already divided into
608
.RI "an " argv "-style array, some programs need to parse strings that "
609
are formatted identically to command lines. To facilitate this, popt
610
provides a function that parses a string into an array of strings,
611
using rules similar to normal shell parsing.
612
.sp
613
.nf
614
.B "#include <popt.h>"
615
.BI "int poptParseArgvString(char * " s ", int * " argcPtr ",
616
.BI " char *** " argvPtr ");"
617
.BI "int poptDupArgv(int " argc ", const char ** " argv ", int * " argcPtr ",
618
.BI " const char *** " argvPtr ");"
619
.fi
620
.sp
621
.RI "The string s is parsed into an " argv "-style array. The integer "
622
.RI "pointed to by the " argcPtr " parameter contains the number of elements "
623
.RI "parsed, and the final " argvPtr " parameter contains the address of the"
624
newly created array.
625
.RB "The routine " poptDupArgv() " can be used to make a copy of an existing "
626
argument array.
627
.sp
628
.RI "The " argvPtr
629
.RB "created by " poptParseArgvString() " or " poptDupArgv() " is suitable to pass directly "
630
.RB "to " poptGetContext() .
631
Both routines return a single dynamically allocated contiguous
632
.RB "block of storage and should be " free() "ed when the application is"
633
finished with the storage.
634
.SH "HANDLING EXTRA ARGUMENTS"
635
Some applications implement the equivalent of option aliasing but need
636
.RB "to do so through special logic. The " poptStuffArgs() " function "
637
allows an application to insert new arguments into the current
638
.BR poptContext .
639
.sp
640
.nf
641
.B "#include <popt.h>"
642
.BI "int poptStuffArgs(poptContext "con ", const char ** " argv ");"
643
.fi
644
.sp
645
.RI "The passed " argv
646
.RB "must have a " NULL " pointer as its final element. When "
647
.BR poptGetNextOpt() " is next called, the "
648
"stuffed" arguments are the first to be parsed. popt returns to the
649
normal arguments once all the stuffed arguments have been exhausted.
650
.SH "EXAMPLE"
651
The following example is a simplified version of the program "robin"
652
which appears in Chapter 15 of the text cited below. Robin has
653
been stripped of everything but its argument-parsing logic, slightly
654
reworked, and renamed "parse." It may prove useful in illustrating
655
at least some of the features of the extremely rich popt library.
656
.sp
657
.nf
658
#include <popt.h>
659
#include <stdio.h>
660
661
void usage(poptContext optCon, int exitcode, char *error, char *addl) {
662
poptPrintUsage(optCon, stderr, 0);
663
if (error) fprintf(stderr, "%s: %s\n", error, addl);
664
exit(exitcode);
665
}
666
667
int main(int argc, char *argv[]) {
668
char c; /* used for argument parsing */
669
int i = 0; /* used for tracking options */
670
char *portname;
671
int speed = 0; /* used in argument parsing to set speed */
672
int raw = 0; /* raw mode? */
673
int j;
674
char buf[BUFSIZ+1];
675
poptContext optCon; /* context for parsing command-line options */
676
677
struct poptOption optionsTable[] = {
678
{ "bps", 'b', POPT_ARG_INT, &speed, 0,
679
"signaling rate in bits-per-second", "BPS" },
680
{ "crnl", 'c', 0, 0, 'c',
681
"expand cr characters to cr/lf sequences", NULL },
682
{ "hwflow", 'h', 0, 0, 'h',
683
"use hardware (RTS/CTS) flow control", NULL },
684
{ "noflow", 'n', 0, 0, 'n',
685
"use no flow control", NULL },
686
{ "raw", 'r', 0, &raw, 0,
687
"don't perform any character conversions", NULL },
688
{ "swflow", 's', 0, 0, 's',
689
"use software (XON/XOF) flow control", NULL } ,
690
POPT_AUTOHELP
691
{ NULL, 0, 0, NULL, 0 }
692
};
693
694
optCon = poptGetContext(NULL, argc, argv, optionsTable, 0);
695
poptSetOtherOptionHelp(optCon, "[OPTIONS]* <port>");
696
697
if (argc < 2) {
698
poptPrintUsage(optCon, stderr, 0);
699
exit(1);
700
}
701
702
/* Now do options processing, get portname */
703
while ((c = poptGetNextOpt(optCon)) >= 0) {
704
switch (c) {
705
case 'c':
706
buf[i++] = 'c';
707
break;
708
case 'h':
709
buf[i++] = 'h';
710
break;
711
case 's':
712
buf[i++] = 's';
713
break;
714
case 'n':
715
buf[i++] = 'n';
716
break;
717
}
718
}
719
portname = poptGetArg(optCon);
720
if((portname == NULL) || !(poptPeekArg(optCon) == NULL))
721
usage(optCon, 1, "Specify a single port", ".e.g., /dev/cua0");
722
723
if (c < -1) {
724
/* an error occurred during option processing */
725
fprintf(stderr, "%s: %s\\n",
726
poptBadOption(optCon, POPT_BADOPTION_NOALIAS),
727
poptStrerror(c));
728
return 1;
729
}
730
731
/* Print out options, portname chosen */
732
printf("Options chosen: ");
733
for(j = 0; j < i ; j++)
734
printf("-%c ", buf[j]);
735
if(raw) printf("-r ");
736
if(speed) printf("-b %d ", speed);
737
printf("\\nPortname chosen: %s\\n", portname);
738
739
poptFreeContext(optCon);
740
exit(0);
741
}
742
.fi
743
.sp
744
RPM, a popular Linux package management program, makes heavy use
745
of popt's features. Many of its command-line arguments are implemented
746
through popt aliases, which makes RPM an excellent example of how to
747
take advantage of the popt library. For more information on RPM, see
748
http://www.rpm.org. The popt source code distribution includes test
749
program(s) which use all of the features of the popt libraries in
750
various ways. If a feature isn't working for you, the popt test code
751
is the first place to look.
752
.SH BUGS
753
None presently known.
754
.SH AUTHOR
755
Erik W. Troan <ewt@redhat.com>
756
.PP
757
This man page is derived in part from
758
.IR "Linux Application Development"
759
by Michael K. Johnson and Erik W. Troan, Copyright (c) 1998 by Addison
760
Wesley Longman, Inc., and included in the popt documentation with the
761
permission of the Publisher and the appreciation of the Authors.
762
.PP
763
Thanks to Robert Lynch for his extensive work on this man page.
764
.SH "SEE ALSO"
765
.BR getopt (3)
766
.sp
767
.IR "Linux Application Development" ", by Michael K. Johnson and "
768
Erik W. Troan (Addison-Wesley, 1998; ISBN 0-201-30821-5), Chapter 24.
769
.sp
770
.BR popt.ps " is a Postscript version of the above cited book "
771
chapter. It can be found in the source archive for popt available at:
772
ftp://ftp.rpm.org/pub/rpm.
Loggerhead is a web-based interface for Breezy
Version: 2.0.1