| blob | 896167029f32bc764a637e9f35d718ad14fa388c |
1 '\" te
2 .TH libpopt 3 "31 May 2004" "" ""
3 .SH "NAME"
4 libpopt \- parse
5 command-line options
6 .SH ""
7 .sp
8 .nf
9 \f(CW#include <popt\&.h>
11 poptContext poptGetContext(const char * name, int argc,
12 const char ** argv,
13 const struct poptOption * options,
14 int flags);
16 void poptFreeContext(poptContext con);
18 void poptResetContext(poptContext con);
20 int poptGetNextOpt(poptContext con);
22 const char * poptGetOptArg(poptContext con);
24 const char * poptGetArg(poptContext con);
26 const char * poptPeekArg(poptContext con);
28 const char ** poptGetArgs(poptContext con);
30 const char *const poptStrerror(const int error);
32 const char * poptBadOption(poptContext con, int flags);
34 int poptReadDefaultConfig(poptContext con, int flags);
36 int poptReadConfigFile(poptContext con, char * fn);
38 int poptAddAlias(poptContext con, struct poptAlias alias,
39 int flags);
41 int poptParseArgvString(char * s, int * argcPtr,
42 const char *** argvPtr);
44 int poptDupArgv(int argc, const char ** argv, int * argcPtr,
45 const char *** argvPtr);
47 int poptStuffArgs(poptContext con, const char ** argv);\fR
48 .fi
49 .sp
50 .SH ""
51 .PP
52 The \fBpopt\fR library parses command-line options\&. The \fBpopt\fR library provides an alternative to parsing the \fBargv\fR array by hand, or using the \fBgetopt\fR(3) functions \fBgetopt()\fR and \fBgetopt_long()\fR\&.
53 .PP
54 The \fBpopt\fR library has the following advantages:
55 .sp
56 .in +2
57 \(bu
58 .mk
59 .in +3
60 .rt
61 \fBpopt\fR does not use global variables, thus
62 enabling multiple passes in parsing \fBargv\fR\&.
63 .sp
64 .in -3
65 \(bu
66 .mk
67 .in +3
68 .rt
69 \fBpopt\fR can parse an arbitrary array of \fBargv\fR-style elements, allowing parsing of command-line strings from
70 any source\&.
71 .sp
72 .in -3
73 \(bu
74 .mk
75 .in +3
76 .rt
77 \fBpopt\fR provides a standard method of option
78 aliasing\&. This feature is discussed in detail below\&.
79 .sp
80 .in -3
81 \(bu
82 .mk
83 .in +3
84 .rt
85 \fBpopt\fR can exec external option filters\&.
86 .sp
87 .in -3
88 \(bu
89 .mk
90 .in +3
91 .rt
92 \fBpopt\fR can automatically generate help
93 and usage messages for the application\&.
94 .sp
95 .in -3
96 .in -2
97 .PP
98 The \fBpopt\fR library supports short and long options\&.
99 A short option consists of a hyphen followed by a single alphanumeric character\&.
100 A long option, common in GNU utilities, consists of two hyphens followed by
101 a string composed of letters, numbers, and hyphens\&. Long options can optionally
102 begin with a single hyphen, primarily to allow command-line compatibility
103 between \fBpopt\fR applications and X toolkit applications\&.
104 Either type of option can be followed by an argument\&. A space separates a
105 short option from its argument\&. Either a space or an equals sign separates
106 a long option from an argument\&.
107 .PP
108 The \fBpopt\fR library is highly portable and should
109 work on any POSIX platform\&. The latest version is distributed with \fBrpm\fR and is available from: \fBftp://ftp\&.rpm\&.org/pub/rpm/dist\fR\&.
110 .PP
111 The \fBpopt\fR library may be redistributed under the
112 X consortium license, see the file \fBCOPYING\fR in the \fBpopt\fR source distribution for details\&.
113 .SH ""
114 .SS "Option Tables"
115 .PP
116 Each application provides \fBpopt\fR with information
117 about the command-line options for the application, by means of an option
118 table\&. An option table is an array of \fBstruct poptOption\fR
119 structures, with the following format:
120 .sp
121 .nf
122 \f(CW#include <popt\&.h>
124 struct poptOption {
125 const char * longName; /* may be NULL */
126 char shortName; /* may be \&'\0\&' */
127 int argInfo;
128 void * arg; /* depends on argInfo */
129 int val; /* 0 means do not return, just update flag */
130 char * descrip; /* description for autohelp -- may be NULL */
131 char * argDescrip; /* argument description for autohelp */
132 };\fR
133 .fi
134 .sp
135 .SS "Option Table Members"
136 .PP
137 Each member of the table defines a single option that may be passed
138 to the program\&. Long and short options are considered to be a single option
139 that can occur in two different forms\&. The option table members are as follows:
140 .sp
141 .ne 2
142 .mk
143 \fB\fBlongName\fR\fR
144 .in +24n
145 .rt
146 Defines
147 the name of the option in a long name\&.
148 .sp
149 .sp 1
150 .in -24n
151 .sp
152 .ne 2
153 .mk
154 \fB\fBshortName\fR\fR
155 .in +24n
156 .rt
157 Defines
158 the name of the option in a single character\&.
159 .sp
160 .sp 1
161 .in -24n
162 .sp
163 .ne 2
164 .mk
165 \fB\fBargInfo\fR\fR
166 .in +24n
167 .rt
168 Tells \fBpopt\fR what type of argument is expected after the option\&. Valid
169 values are as follows:
170 .sp
171 .sp
172 .ne 2
173 .mk
174 \fBPOPT_ARG_DOUBLE\fR
175 .in +16n
176 .rt
177 Double argument
178 expected, \fBarg\fR type: \fBdouble\fR
179 .sp
180 .sp 2
181 .in -16n
182 .sp
183 .ne 2
184 .mk
185 \fBPOPT_ARG_FLOAT\fR
186 .in +16n
187 .rt
188 Float argument expected, \fBarg\fR type: \fBfloat\fR
189 .sp
190 .sp 1
191 .in -16n
192 .sp
193 .ne 2
194 .mk
195 \fBPOPT_ARG_INT\fR
196 .in +16n
197 .rt
198 Integer argument expected, \fBarg\fR type: \fBint\fR
199 .sp
200 .sp 1
201 .in -16n
202 .sp
203 .ne 2
204 .mk
205 \fBPOPT_ARG_LONG\fR
206 .in +16n
207 .rt
208 Long integer expected, \fBarg\fR type: \fBlong\fR
209 .sp
210 .sp 1
211 .in -16n
212 .sp
213 .ne 2
214 .mk
215 \fBPOPT_ARG_NONE\fR
216 .in +16n
217 .rt
218 No argument expected, \fBarg\fR type: \fBint\fR
219 .sp
220 .sp 1
221 .in -16n
222 .sp
223 .ne 2
224 .mk
225 \fBPOPT_ARG_STRING\fR
226 .in +16n
227 .rt
228 No type checking
229 to be performed, \fBarg\fR type: \fBchar *\fR
230 .sp
231 .sp 1
232 .in -16n
233 .sp
234 .ne 2
235 .mk
236 \fBPOPT_ARG_VAL\fR
237 .in +16n
238 .rt
239 Integer value taken
240 from val, \fBarg\fR type: \fBint\fR
241 .sp
242 .sp 1
243 .in -16n
244 For numeric values, if the \fBargInfo\fR
245 value is bitwise or\&'d with one of POPT_ARGFLAG_OR, POPT_ARGFLAG_AND, or POPT_ARGFLAG_XOR,
246 the value is saved by performing an OR, AND, or XOR\&. If the \fBargInfo\fR value is bitwise or\&'d with POPT_ARGFLAG_NOT, the value is negated
247 before saving\&. For the common operations of setting or clearing bits, POPT_BIT_SET
248 and POPT_BIT_CLR have the appropriate flags set to perform bit operations\&.
249 .sp
250 If the \fBargInfo\fRvalue is bitwise or\&'d with POPT_ARGFLAG_ONEDASH,
251 the long argument may be given with a single hyphen instead of two\&. For example,
252 if -\fB-longopt\fR is an option with POPT_ARGFLAG_ONEDASH, -\fBlongopt\fR is also accepted\&.
253 .sp
254 .sp 0
255 .in -24n
256 .sp
257 .ne 2
258 .mk
259 \fB\fBarg\fR\fR
260 .in +24n
261 .rt
262 Allows \fBpopt\fR to automatically update program variables\&. If \fBarg\fR is NULL, \fBpopt\fR ignores \fBarg\fR
263 and takes no special action\&. Otherwise, \fBarg\fR points to a
264 variable of the appropriate type, as follows:
265 .sp
266 .in +2
267 \(bu
268 .mk
269 .in +3
270 .rt
271 If \fBargInfo\fR is POPT_ARG_NONE, the variable
272 pointed to by \fBarg\fR is set to 1 when the option is used\&.
273 .sp
274 .in -3
275 \(bu
276 .mk
277 .in +3
278 .rt
279 If the option takes an argument, the variable pointed to by \fBarg\fR is updated to reflect the value of the argument\&. Any string
280 is acceptable for POPT_ARG_STRING arguments\&. POPT_ARG_INT, POPT_ARG_LONG,
281 POPT_ARG_FLOAT, and POPT_ARG_DOUBLE arguments are converted to the appropriate
282 type, and an error returned if the conversion fails\&.
283 .sp
284 .in -3
285 .in -2
286 .sp
287 POPT_ARG_VAL causes \fBarg\fR to be set to the integer
288 value of \fBval\fR when the argument is found\&. This is useful
289 for mutually-exclusive arguments in cases where it is not an error for multiple
290 arguments to occur and where you want the last argument specified to take
291 precedence, for example, \fBrm -i -f\fR\&. POPT_ARG_VAL causes
292 the parsing function not to return a value, because the value of \fBval\fR has already been used\&.
293 .sp
294 If the \fBargInfo\fR value is bitwise or\&'d with POPT_ARGFLAG_OPTIONAL,
295 the argument to the long option may be omitted\&. If the long option is used
296 without an argument, a default value of zero or NULL is saved if the \fBarg\fR pointer is present\&. Otherwise, the behavior is identical to
297 that of a long option with an argument\&.
298 .sp
299 .sp 1
300 .in -24n
301 .sp
302 .ne 2
303 .mk
304 \fB\fBval\fR\fR
305 .in +24n
306 .rt
307 The value
308 returned by the \fBpopt\fR parsing function when the option
309 is encountered\&. If \fBval\fR is 0, the parsing function does
310 not return a value\&. Instead, \fBpopt\fR parses the next command-line
311 argument\&.
312 .sp
313 .sp 1
314 .in -24n
315 .sp
316 .ne 2
317 .mk
318 \fBdescrip\fR
319 .in +24n
320 .rt
321 Text description of the
322 argument\&. Only required if automatic help messages are desired\&. Automatic
323 usage messages can be generated without this argument\&.
324 .sp
325 .sp 1
326 .in -24n
327 .sp
328 .ne 2
329 .mk
330 \fBargDescrip\fR
331 .in +24n
332 .rt
333 Short summary of the
334 type of arguments expected by the option, or NULL if the option does not require
335 any arguments\&. Only required if automatic help messages are desired\&. Automatic
336 usage messages can be generated without this argument\&.
337 .sp
338 .sp 1
339 .in -24n
340 .PP
341 The final structure in the table should have all pointer
342 values set to NULL and all arithmetic values set to 0, marking the end of
343 the table\&. The macro POPT_TABLEEND performs these tasks\&.
344 .SS "Help and Usage Output"
345 .PP
346 If \fBpopt\fR should automatically provide -\fB\(miusage\fR and -\fB\(mihelp\fR options, one line in the option
347 table should contain the macro POPT_AUTOHELP\&. This macro includes another
348 option table, via POPT_ARG_INCLUDE_TABLE, which provides the table entries
349 for these arguments\&. When the -\fB\(miusage\fR or -\fB\(mihelp\fR option is passed to applications that use \fBpopt\fR
350 automatic help, \fBpopt\fR displays the appropriate message
351 on \fBstderr\fR, and exits the application with a return code
352 of 0\&. To use \fBpopt\fR automatic help generation in a different
353 way, you must explicitly add the option entries to the application\&'s option
354 table, instead of using POPT_AUTOHELP\&.
355 .PP
356 If the \fBargInfo\fR value is bitwise or\&'d with POPT_ARGFLAG_DOC_HIDDEN,
357 the argument is not shown in help output\&.
358 .PP
359 If the \fBargInfo\fR value is bitwise or\&'d with POPT_ARGFLAG_SHOW_DEFAULT,
360 the inital value of the \fBarg\fR is shown in help output\&.
361 .SS "Special Option Table Entries"
362 .PP
363 Two types of option table entries do not specify command-line options\&.
364 When either of these types of entries is used, the \fBlongName\fR
365 element must be NULL and the \fBshortName\fR element must be \fB\\0\fR\&.
366 .PP
367 The first of these special entry types allows the application to nest
368 another option table in the current option table\&. Such nesting may extend
369 quite deeply, the actual depth is limited by the application stack\&. Including
370 other option tables allows a library to provide a standard set of command-line
371 options to every application that uses the library\&. This is often done in
372 graphical programming toolkits, for example\&. To nest another option table,
373 set the \fBargInfo\fR field to POPT_ARG_INCLUDE_TABLE and the \fBarg\fR field to point to the table that is being included\&. If automatic
374 help generation is used, the \fBdescrip\fR field should contain
375 an overall description of the option table being included\&.
376 .PP
377 The other special option table entry type tells \fBpopt\fR
378 to call a function when any option in that table is found\&. This callback functionality
379 is especially useful when included option tables are used, because the application
380 that provides the top-level option table does not need to be aware of the
381 other options that are provided by the included table\&. When a callback is
382 set for a table, the parsing function never returns information on an option
383 in the table\&. Instead, option information must be retained via the callback
384 or by having \fBpopt\fR set a variable through the option\&'s \fBarg\fR field\&. Option callbacks should match the following prototype:
385 .sp
386 .nf
387 void poptCallbackType(poptContext con,
388 const struct poptOption * opt,
389 const char * arg, void * data);
390 .fi
391 .sp
392 .PP
393 The callback uses the following parameters:
394 .sp
395 .ne 2
396 .mk
397 \fB\fBcon\fR\fR
398 .in +16n
399 .rt
400 The context
401 that is being parsed\&. See the next section for information on contexts\&.
402 .sp
403 .sp 1
404 .in -16n
405 .sp
406 .ne 2
407 .mk
408 \fB\fBopt\fR\fR
409 .in +16n
410 .rt
411 The option
412 that triggered this callback\&.
413 .sp
414 .sp 1
415 .in -16n
416 .sp
417 .ne 2
418 .mk
419 \fB\fBarg\fR\fR
420 .in +16n
421 .rt
422 The argument
423 for the \fBopt\fR option\&. If the option does not take an argument, \fBarg\fR is NULL\&.
424 .sp
425 .sp 1
426 .in -16n
427 .sp
428 .ne 2
429 .mk
430 \fB\fBdata\fR\fR
431 .in +16n
432 .rt
433 Taken from
434 the \fBdescrip\fR field of the option table entry that defined
435 the callback\&. As \fBdescrip\fR is a pointer, this allows you
436 to pass an arbitrary set of data to callback functions, though a typecast
437 must be used\&.
438 .sp
439 .sp 1
440 .in -16n
441 .PP
442 The option table entry that defines a callback has an \fBargInfo\fR of POPT_ARG_CALLBACK, an \fBarg\fR that points
443 to the callback function, and a \fBdescrip\fR field that specifies
444 an arbitrary pointer to be passed to the callback\&.
445 .SS "Creating a Context"
446 .PP
447 \fBpopt\fR can interleave the parsing of multiple command-line
448 sets\&. \fBpopt\fR allows this by keeping all of the state information
449 for a particular set of command-line arguments in a \fBpoptContext\fR
450 data structure, an opaque type that should not be modified outside the \fBpopt\fR library\&.
451 .PP
452 New \fBpopt\fR contexts are created by \fBpoptGetContext()\fR:
453 .sp
454 .nf
455 \f(CWpoptContext poptGetContext(const char * name, int argc,
456 const char ** argv,
457 const struct poptOption * options,
458 int flags);\fR
459 .fi
460 .sp
461 .PP
462 The \fBpoptGetContext()\fR function takes the following
463 parameters:
464 .sp
465 .ne 2
466 .mk
467 \fB\fBname\fR\fR
468 .in +24n
469 .rt
470 Used only
471 for alias handling\&. \fBname\fR should be the name of the application
472 whose options are being parsed, or should be NULL if no option aliasing is
473 desired\&.
474 .sp
475 .sp 1
476 .in -24n
477 .sp
478 .ne 2
479 .mk
480 \fB\fBargc\fR, \fBargv\fR\fR
481 .in +24n
482 .rt
483 Specifies the command-line arguments to parse\&. These arguments
484 are generally passed to \fBpoptGetContext()\fR exactly as they
485 were passed to the application\&'s \fBmain()\fR function\&.
486 .sp
487 .sp 1
488 .in -24n
489 .sp
490 .ne 2
491 .mk
492 \fB\fBoptions\fR\fR
493 .in +24n
494 .rt
495 Points
496 to the table of command-line options\&. See the Option Tables section above\&.
497 .sp
498 .sp 1
499 .in -24n
500 .sp
501 .ne 2
502 .mk
503 \fB\fBflags\fR\fR
504 .in +24n
505 .rt
506 Can take
507 one of the following values:
508 .sp
509 .sp
510 .ne 2
511 .mk
512 \fBPOPT_CONTEXT_NO_EXEC\fR
513 .in +24n
514 .rt
515 Ignore \fBexec\fR expansions
516 .sp
517 .sp 2
518 .in -24n
519 .sp
520 .ne 2
521 .mk
522 \fBPOPT_CONTEXT_KEEP_FIRST\fR
523 .in +24n
524 .rt
525 Do not ignore \fBargv[0]\fR
526 .sp
527 .sp 1
528 .in -24n
529 .sp
530 .ne 2
531 .mk
532 \fBPOPT_CONTEXT_POSIXMEHARDER\fR
533 .in +24n
534 .rt
535 Options
536 cannot follow arguments
537 .sp
538 .sp 1
539 .in -24n
540 .sp 0
541 .in -24n
542 .PP
543 A \fBpoptContext\fR keeps track of which
544 options have already been parsed and which remain to be parsed\&. If an application
545 wishes to restart processing the options of a set of arguments, the application
546 can reset the \fBpoptContext\fR by passing the context as the
547 sole argument to \fBpoptResetContext()\fR\&.
548 .PP
549 When argument processing is complete, the process should free the \fBpoptContext\fR, as it contains dynamically allocated components\&. The \fBpoptFreeContext()\fR function takes a \fBpoptContext\fR
550 as its sole argument and frees the resources that the context is using\&.
551 .PP
552 Here are the prototypes of both \fBpoptResetContext()\fR
553 and \fBpoptFreeContext()\fR:
554 .sp
555 .nf
556 \f(CW#include <popt\&.h>
557 void poptFreeContext(poptContext con);
558 void poptResetContext(poptContext con);\fR
559 .fi
560 .sp
561 .SS "Parsing the Command Line"
562 .PP
563 After an application has created a \fBpoptContext\fR, the \fBpoptContext\fR may begin parsing arguments\&. \fBpoptGetNextOpt()\fR performs the actual argument parsing:
564 .sp
565 .nf
566 \f(CW#include <popt\&.h>
567 int poptGetNextOpt(poptContext con);\fR
568 .fi
569 .sp
570 .PP
571 Taking the context as its sole argument, the \fBpoptGetNextOpt()\fR function parses the next command-line argument found\&. When \fBpoptGetNextOpt()\fR finds the next argument in the option table, the
572 function populates the object pointed to by the option table entry\&'s \fBarg\fR pointer, if the pointer is not NULL\&. If the \fBval\fR
573 entry for the option is not zero, the function returns that value\&. Otherwise, \fBpoptGetNextOpt()\fR continues to the next argument\&.
574 .PP
575 \fBpoptGetNextOpt()\fR returns \(mi1 when the final
576 argument has been parsed, and other negative values when errors occur\&. Therefore,
577 you should ensure that the \fBval\fR elements in the option table
578 are greater than 0\&.
579 .PP
580 If all of the command-line options are handled through \fBarg\fR pointers, command-line parsing is reduced to the following line
581 of code:
582 .sp
583 .nf
584 \f(CWrc = poptGetNextOpt(poptcon);\fR
585 .fi
586 .sp
587 .PP
588 Many applications require more complex command-line parsing than this,
589 however, and use the following structure:
590 .sp
591 .nf
592 \f(CWwhile ((rc = poptGetNextOpt(poptcon)) > 0) {
593 switch (rc) {
594 /* specific arguments are handled here */
595 }
596 }\fR
597 .fi
598 .sp
599 .PP
600 When returned options are handled, the application needs to know the
601 value of any arguments that were specified after the option\&. There are two
602 ways to discover these values:
603 .sp
604 .in +2
605 \(bu
606 .mk
607 .in +3
608 .rt
609 Ask \fBpopt\fR to populate a variable with
610 the value of the option from the option table\&'s \fBarg\fR elements\&.
611 .sp
612 .in -3
613 \(bu
614 .mk
615 .in +3
616 .rt
617 Use \fBpoptGetOptArg()\fR:
618 .sp
619 .nf
620 \f(CW#include <popt\&.h>
621 const char * poptGetOptArg(poptContext con);\fR
622 .fi
623 .sp
624 .sp
625 .in -3
626 .in -2
627 .PP
628 The \fBpoptGetOptArg()\fR function returns the argument
629 given for the final option returned by \fBpoptGetNextOpt()\fR,
630 or returns NULL if no argument was specified\&.
631 .SS "Leftover Arguments"
632 .PP
633 Many applications take an arbitrary number of command-line arguments,
634 such as a list of file names\&. When \fBpopt\fR encounters an
635 argument that does not begin with a hyphen, \fBpopt\fR assumes
636 that this is such an argument, and adds the argument to a list of leftover
637 arguments\&. Three functions allow applications to access such arguments:
638 .sp
639 .ne 2
640 .mk
641 \fB\fBconst char * poptGetArg(poptContext con);\fR\fR
642 .sp .6
643 .in +4
644 Returns the next leftover argument and marks the argument
645 as processed\&.
646 .sp
647 .sp 1
648 .in -4
649 .sp
650 .ne 2
651 .mk
652 \fB\fBconst char * poptPeekArg(poptContext con);\fR\fR
653 .sp .6
654 .in +4
655 Returns the next leftover argument but does not mark the argument
656 as processed\&. This allows an application to look ahead into the argument list,
657 without modifying the list\&.
658 .sp
659 .sp 1
660 .in -4
661 .sp
662 .ne 2
663 .mk
664 \fB\fBconst char ** poptGetArgs(poptContext con);\fR\fR
665 .sp .6
666 .in +4
667 Returns all of the leftover arguments in a manner identical
668 to \fBargv\fR\&. The final element in the returned array points
669 to NULL, indicating the end of the arguments\&.
670 .sp
671 .sp 1
672 .in -4
673 .SS "Automatic Help Messages"
674 .PP
675 The popt library can automatically generate help messages that describe
676 the options that an application accepts\&. Two types of help messages can be
677 generated:
678 .sp
679 .in +2
680 \(bu
681 .mk
682 .in +3
683 .rt
684 Usage messages are short messages that list valid options,
685 but do not describe the options\&.
686 .sp
687 .in -3
688 \(bu
689 .mk
690 .in +3
691 .rt
692 Help messages describe each option in one or more lines, resulting
693 in a longer but more useful message\&.
694 .sp
695 .in -3
696 .in -2
697 .PP
698 Whenever automatic help messages are used, the \fBdescrip\fR
699 and \fBargDescrip\fR members of the \fBstruct poptOption\fR structure should be populated for each option\&.
700 .PP
701 The POPT_AUTOHELP macro makes it easy to add usage and help messages
702 to your application, as described earlier in this man page\&. If you need more
703 control over your help messages, use the following functions:
704 .sp
705 .nf
706 \f(CW#include <popt\&.h>
707 void poptPrintHelp(poptContext con, FILE * f, int flags);
708 void poptPrintUsage(poptContext con, FILE * f, int flags);\fR
709 .fi
710 .sp
711 .PP
712 \fBpoptPrintHelp()\fR displays the standard help message
713 to the \fBstdio\fR file descriptor \fBf\fR, while \fBpoptPrintUsage()\fR displays the shorter usage message\&. Both functions
714 currently ignore the \fBflags\fR argument, which is provided
715 for future functionality\&.
716 .SS "Option Aliasing"
717 .PP
718 One of the primary benefits of \fBpopt\fR is the ability
719 to use option aliasing\&. Option aliasing allows the user to specify options
720 that \fBpopt\fR expands into other options\&. For example\&. if
721 the standard \fBgrep\fR command made use of \fBpopt\fR,
722 users could add a -\fB\(mitext\fR option that expanded to \fB-i -n -E -2\fR, to allow users to more easily find information in text
723 files\&.
724 .SS "Specifying Aliases"
725 .PP
726 Aliases are normally specified in two places:
727 .sp
728 .in +2
729 \(bu
730 .mk
731 .in +3
732 .rt
733 \fB/etc/popt\fR
734 .sp
735 .in -3
736 \(bu
737 .mk
738 .in +3
739 .rt
740 \fB$HOME/\&.popt\fR
741 .sp
742 .in -3
743 .in -2
744 .PP
745 Both files have the same format, that is, an arbitrary number of lines
746 formatted as follows:
747 .PP
748 .nf
749 \fIappname\fR alias \fInewoption\fR \fIexpansion\fR
750 .fi
751 .PP
752 An alias specification is composed of the following elements:
753 .sp
754 .ne 2
755 .mk
756 \fB\fIappname\fR\fR
757 .in +24n
758 .rt
759 Specifies the name of the application, which must be the same as the \fBname\fR parameter passed to \fBpoptGetContext()\fR\&. This
760 allows each file to specify aliases for multiple programs\&.
761 .sp
762 .sp 1
763 .in -24n
764 .sp
765 .ne 2
766 .mk
767 \fBalias\fR
768 .in +24n
769 .rt
770 Specifies that an alias is
771 being defined\&. Currently, \fBpopt\fR configuration files support
772 only aliases, but other abilities may be added in the future\&.
773 .sp
774 .sp 1
775 .in -24n
776 .sp
777 .ne 2
778 .mk
779 \fB\fInewoption\fR\fR
780 .in +24n
781 .rt
782 Specifies the option that should be aliased, either a short option or
783 a long option\&.
784 .sp
785 .sp 1
786 .in -24n
787 .sp
788 .ne 2
789 .mk
790 \fB\fIexpansion\fR\fR
791 .in +24n
792 .rt
793 Specifies the expansion for the alias\&. The expansion is parsed in a
794 similar way to a shell command: backslashes are allowed, and single quotation
795 marks can be used for quoting\&. If a backslash is the final character on a
796 line, the next line in the file is assumed to be a logical continuation of
797 the line containing the backslash, just as in a shell command\&.
798 .sp
799 .sp 1
800 .in -24n
801 .sp
802 .PP
803 For example, the following entry would add to the \fBgrep\fR
804 command the -\fB\(mitext\fR option described earlier:
805 .PP
806 \f(CWgrep alias --text -i -n -E -2\fR
807 .SS "Enabling Aliases"
808 .PP
809 An application must enable alias expansion for a \fBpoptContext\fR, before calling \fBpoptGetNextArg()\fR for the first
810 time\&. Three functions define aliases for a context:
811 .sp
812 .ne 2
813 .mk
814 \fBint poptReadDefaultConfig(poptContext con, int flags);\fR
815 .sp .6
816 .in +4
817 Reads aliases from \fB/etc/popt\fR and \fB$HOME/\&.popt\fR\&. The \fBflags\fR argument should be NULL,
818 it is provided only for future expansion\&.
819 .sp
820 .sp 1
821 .in -4
822 .sp
823 .ne 2
824 .mk
825 \fBint poptReadConfigFile(poptContext con, char * fn);\fR
826 .sp .6
827 .in +4
828 Opens the file specified by \fBfn\fR and parses
829 the file as a \fBpopt\fR configuration file\&. This allows applications
830 to use application-specific configuration files\&.
831 .sp
832 .sp 1
833 .in -4
834 .sp
835 .ne 2
836 .mk
837 \fBint poptAddAlias(poptContext con, struct poptAlias alias,
838 int flags);\fR
839 .sp .6
840 .in +4
841 Adds a new alias to a context\&. This function
842 is useful when processes want to specify aliases without having to read them
843 from a configuration file\&. The \fBflags\fR argument should be
844 0, it is provided only for future expansion\&. The new alias is specified as
845 a \fBstruct poptAlias\fR, which is defined as follows:
846 .sp
847 .sp
848 .nf
849 \f(CWstruct poptAlias {
850 const char * longName; /* may be NULL */
851 char shortName; /* may be \&'\0\&' */
852 int argc;
853 const char ** argv; /* must be free()able */
854 };\fR
855 .fi
856 .sp
857 \fBlongName\fR and \fBshortName\fR specify
858 the option that is aliased\&. \fBargc\fR and \fBargv\fR
859 define the expansion to use when the aliases option is encountered\&.
860 .sp
861 .sp 1
862 .in -4
863 .SS "Parsing Argument Strings"
864 .PP
865 \fBpopt\fR usually parses arguments that are already
866 divided into an \fBargv\fR-style array\&. However, some applications
867 need to parse strings that are formatted identically to command lines\&. To
868 facilitate this, \fBpopt\fR provides a function that parses a
869 string into an array of strings, using rules similar to those of normal shell
870 parsing:
871 .sp
872 .nf
873 \f(CW#include <popt\&.h>
874 int poptParseArgvString(char * s, int * argcPtr,
875 char *** argvPtr);
876 int poptDupArgv(int argc, const char ** argv, int * argcPtr,
877 const char *** argvPtr);\fR
878 .fi
879 .sp
880 .PP
881 The string \fBs\fR is parsed into an \fBargv\fR-style
882 array\&. The integer pointed to by the \fBargcPtr\fR parameter
883 contains the number of elements parsed, and the final \fBargvPtr\fR
884 parameter contains the address of the newly created array\&. The routine \fBpoptDupArgv()\fR can be used to make a copy of an existing argument
885 array\&.
886 .PP
887 The \fBargvPtr\fR created by \fBpoptParseArgvString()\fR or \fBpoptDupArgv()\fR can be passed directly to \fBpoptGetContext()\fR\&. Both routines return a single dynamically allocated
888 contiguous block of storage and should be freed using \fBfree()\fR
889 when the application is finished with the storage\&.
890 .SS "Handling Extra Arguments"
891 .PP
892 Some applications implement the equivalent of option aliasing but do
893 so using special logic\&. The \fBpoptStuffArgs()\fR function allows
894 an application to insert new arguments into the current \fBpoptContext\fR:
895 .sp
896 .nf
897 \f(CW#include <popt\&.h>
898 int poptStuffArgs(poptContext con, const char ** argv);\fR
899 .fi
900 .sp
901 .PP
902 The passed \fBargv\fR must have a NULL pointer as its final
903 element\&. When \fBpoptGetNextOpt()\fR is next called, the "stuffed"
904 arguments are the first to be parsed\&. \fBpopt\fR returns to
905 the normal arguments when all of the stuffed arguments have been exhausted\&.
906 .SH ""
907 .PP
908 All of the \fBpopt\fR functions that can return errors
909 return integers\&. When an error occurs, a negative error code is returned\&.
910 The following error codes can occur:
911 .sp
912 .ne 2
913 .mk
914 \fBPOPT_ERROR_BADNUMBER\fR
915 .in +24n
916 .rt
917 A string-to-number
918 conversion failed because the string contains nonnumeric characters\&. This
919 occurs when \fBpoptGetNextOpt()\fR is processing an argument
920 of type POPT_ARG_INT, POPT_ARG_LONG, POPT_ARG_FLOAT, or POPT_ARG_DOUBLE\&.
921 .sp
922 .sp 1
923 .in -24n
924 .sp
925 .ne 2
926 .mk
927 \fBPOPT_ERROR_BADOPT\fR
928 .in +24n
929 .rt
930 An option was
931 specified in \fBargv\fR but is not in the option table\&. This
932 error can be returned only from \fBpoptGetNextOpt()\fR\&.
933 .sp
934 .sp 1
935 .in -24n
936 .sp
937 .ne 2
938 .mk
939 \fBPOPT_ERROR_BADQUOTE\fR
940 .in +24n
941 .rt
942 A parsed string
943 has a quotation mismatch, for example, a single quotation mark\&. \fBpoptParseArgvString()\fR, \fBpoptReadConfigFile()\fR,
944 or \fBpoptReadDefaultConfig()\fR can return this error\&.
945 .sp
946 .sp 1
947 .in -24n
948 .sp
949 .ne 2
950 .mk
951 \fBPOPT_ERROR_ERRNO\fR
952 .in +24n
953 .rt
954 A system call returned
955 with an error, and \fBerrno\fR still contains the error from
956 the system call\&. Both \fBpoptReadConfigFile()\fR and \fBpoptReadDefaultConfig()\fR can return this error\&.
957 .sp
958 .sp 1
959 .in -24n
960 .sp
961 .ne 2
962 .mk
963 \fBPOPT_ERROR_NOARG\fR
964 .in +24n
965 .rt
966 An option that
967 requires an argument was specified on the command line, but no argument was
968 given\&. This error can be returned only by \fBpoptGetNextOpt()\fR\&.
969 .sp
970 .sp 1
971 .in -24n
972 .sp
973 .ne 2
974 .mk
975 \fBPOPT_ERROR_OPTSTOODEEP\fR
976 .in +24n
977 .rt
978 A set of
979 option aliases is nested too deeply\&. Currently, \fBpopt\fR
980 follows options to only 10 levels, to prevent infinite recursion\&. Only \fBpoptGetNextOpt()\fR can return this error\&.
981 .sp
982 .sp 1
983 .in -24n
984 .sp
985 .ne 2
986 .mk
987 \fBPOPT_ERROR_OVERFLOW\fR
988 .in +24n
989 .rt
990 A string-to-number
991 conversion failed because the number is too large or too small\&. This error
992 can occur only when \fBpoptGetNextOpt()\fR is processing an
993 argument of type POPT_ARG_INT, POPT_ARG_LONG, POPT_ARG_FLOAT, or POPT_ARG_DOUBLE\&.
994 .sp
995 .sp 1
996 .in -24n
997 .PP
998 Two functions allow applications to provide good error
999 messages:
1000 .sp
1001 .ne 2
1002 .mk
1003 \fBconst char *const poptStrerror(const int error);\fR
1004 .sp .6
1005 .in +4
1006 Takes a \fBpopt\fR error code and returns a string
1007 describing the error, just as with the standard \fBstrerror()\fR
1008 function\&.
1009 .sp
1010 .sp 1
1011 .in -4
1012 .sp
1013 .ne 2
1014 .mk
1015 \fBconst char * poptBadOption(poptContext con, int flags);\fR
1016 .sp .6
1017 .in +4
1018 Returns the option that caused the error, if an error
1019 occurred during \fBpoptGetNextOpt()\fR\&. If the \fBflags\fR argument is set to POPT_BADOPTION_NOALIAS, the outermost option
1020 is returned\&. Otherwise, \fBflags\fR should be 0, and the option
1021 that is returned may have been specified through an alias\&.
1022 .sp
1023 .sp 1
1024 .in -4
1025 .PP
1026 These two functions ensure that \fBpopt\fR
1027 error handling is trivial for most applications\&. When an error is detected
1028 from most of the functions, an error message is printed along with the error
1029 string from \fBpoptStrerror()\fR\&. When an error occurs during
1030 argument parsing, code similar to the following displays a useful error message:
1031 .sp
1032 .nf
1033 \f(CWfprintf(stderr, "%s: %s\n",
1034 poptBadOption(optCon, POPT_BADOPTION_NOALIAS),
1035 poptStrerror(rc));\fR
1036 .fi
1037 .sp
1038 .SH ""
1039 .PP
1040 \fBExample 1: Parse Program Created From robin Program\fR
1041 .PP
1042 The following example is a simplified version of the \fBrobin\fR program that appears in Chapter 15 of "Linux Application
1043 Development" by Michael K\&. Johnson and Erik W\&. Troan (copyright 1998
1044 by Addison Wesley Longman, Inc\&.)\&. The \fBrobin\fR program has
1045 been stripped of everything but its argument-parsing logic, slightly reworked,
1046 and renamed \fBparse\fR\&. This program illustrates some of the
1047 features of the extremely rich \fBpopt\fR library\&.
1048 .sp
1049 .nf
1050 \f(CW#include <popt\&.h>
1051 #include <stdio\&.h>
1053 void usage(poptContext optCon, int exitcode, char *error, char *addl) {
1054 poptPrintUsage(optCon, stderr, 0);
1055 if (error) fprintf(stderr, "%s: %s0, error, addl);
1056 exit(exitcode);
1057 }
1059 int main(int argc, char *argv[]) {
1060 char c; /* used for argument parsing */
1061 int i = 0; /* used for tracking options */
1062 char *portname;
1063 int speed = 0; /* used in argument parsing to set speed */
1064 int raw = 0; /* raw mode? */
1065 int j;
1066 char buf[BUFSIZ+1];
1067 poptContext optCon; /* context for parsing command-line options */
1069 struct poptOption optionsTable[] = {
1070 { "bps", \&'b\&', POPT_ARG_INT, &speed, 0,
1071 "signaling rate in bits-per-second", "BPS" },
1072 { "crnl", \&'c\&', 0, 0, \&'c\&',
1073 "expand cr characters to cr/lf sequences" },
1074 { "hwflow", \&'h\&', 0, 0, \&'h\&',
1075 "use hardware (RTS/CTS) flow control" },
1076 { "noflow", \&'n\&', 0, 0, \&'n\&',
1077 "use no flow control" },
1078 { "raw", \&'r\&', 0, &raw, 0,
1079 "don\&'t perform any character conversions" },
1080 { "swflow", \&'s\&', 0, 0, \&'s\&',
1081 "use software (XON/XOF) flow control" } ,
1082 POPT_AUTOHELP
1083 { NULL, 0, 0, NULL, 0 }
1084 };
1086 optCon = poptGetContext(NULL, argc, argv, optionsTable, 0);
1087 poptSetOtherOptionHelp(optCon, "[OPTIONS]* <port>");
1089 if (argc < 2) {
1090 poptPrintUsage(optCon, stderr, 0);
1091 exit(1);
1092 }
1094 /* Now do options processing, get portname */
1095 while ((c = poptGetNextOpt(optCon)) >= 0) {
1096 switch (c) {
1097 case \&'c\&':
1098 buf[i++] = \&'c\&';
1099 break;
1100 case \&'h\&':
1101 buf[i++] = \&'h\&';
1102 break;
1103 case \&'s\&':
1104 buf[i++] = \&'s\&';
1105 break;
1106 case \&'n\&':
1107 buf[i++] = \&'n\&';
1108 break;
1109 }
1110 }
1111 portname = poptGetArg(optCon);
1112 if((portname == NULL) || !(poptPeekArg(optCon) == NULL))
1113 usage(optCon, 1, "Specify a single port", "\&.e\&.g\&., /dev/cua0");
1115 if (c < -1) {
1116 /* an error occurred during option processing */
1117 fprintf(stderr, "%s: %s\n",
1118 poptBadOption(optCon, POPT_BADOPTION_NOALIAS),
1119 poptStrerror(c));
1120 return 1;
1121 }
1123 /* Print out options, portname chosen */
1124 printf("Options chosen: ");
1125 for(j = 0; j < i ; j++)
1126 printf("-%c ", buf[j]);
1127 if(raw) printf("-r ");
1128 if(speed) printf("-b %d ", speed);
1129 printf("\nPortname chosen: %s\n", portname);
1131 poptFreeContext(optCon);
1132 exit(0);
1133 }
1134 \fR
1135 .fi
1136 .sp
1137 .PP
1138 RPM, a popular Linux package management application, uses several \fBpopt\fR features\&. Many RPM command-line arguments are implemented
1139 using \fBpopt\fR aliases, which makes RPM an excellent example
1140 of how to take advantage of the \fBpopt\fR library\&. For more
1141 information about RPM, see \fBhttp://www\&.rpm\&.org\fR\&. The \fBpopt\fR source code distribution includes test programs that use all
1142 of the features of the \fBpopt\fR libraries in various ways\&.
1143 If a \fBpopt\fR feature does not work for you, check the \fBpopt\fR test code\&.
1144 .SH ""
1145 .PP
1146 The following files are used by this library:
1147 .sp
1148 .ne 2
1149 .mk
1150 \fB\fB/usr/lib/libpopt\&.so\fR \fR
1151 .in +24n
1152 .rt
1153 Command Line Parser API shared library
1154 .sp
1155 .sp 1
1156 .in -24n
1157 .SH ""
1158 .PP
1159 \fBgetopt\fR(3),
1160 \fBattributes\fR(5)
1161 .SH ""
1162 .PP
1163 Updated by Erwann Chenede, Sun Microsystems Inc\&., 2003\&. Written by Erik
1164 W\&. Troan (ewt@redhat\&.com), Michael K\&. Johnson, and Robert Lynch\&.
1165 ...\" created by instant / solbook-to-man, Tue 21 Aug 2012, 08:56