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 automatical 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 inital 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 usefull
 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 similiar 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 similiar 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.