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