'\" te .TH libpopt 3 "31 May 2004" "" "" .SH "NAME" libpopt \- parse command-line options .SH "" .sp .nf \f(CW#include poptContext poptGetContext(const char * name, int argc, const char ** argv, const struct poptOption * options, int flags); void poptFreeContext(poptContext con); void poptResetContext(poptContext con); int poptGetNextOpt(poptContext con); const char * poptGetOptArg(poptContext con); const char * poptGetArg(poptContext con); const char * poptPeekArg(poptContext con); const char ** poptGetArgs(poptContext con); const char *const poptStrerror(const int error); const char * poptBadOption(poptContext con, int flags); int poptReadDefaultConfig(poptContext con, int flags); int poptReadConfigFile(poptContext con, char * fn); int poptAddAlias(poptContext con, struct poptAlias alias, int flags); int poptParseArgvString(char * s, int * argcPtr, const char *** argvPtr); int poptDupArgv(int argc, const char ** argv, int * argcPtr, const char *** argvPtr); int poptStuffArgs(poptContext con, const char ** argv);\fR .fi .sp .SH "" .PP 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\&. .PP The \fBpopt\fR library has the following advantages: .sp .in +2 \(bu .mk .in +3 .rt \fBpopt\fR does not use global variables, thus enabling multiple passes in parsing \fBargv\fR\&. .sp .in -3 \(bu .mk .in +3 .rt \fBpopt\fR can parse an arbitrary array of \fBargv\fR-style elements, allowing parsing of command-line strings from any source\&. .sp .in -3 \(bu .mk .in +3 .rt \fBpopt\fR provides a standard method of option aliasing\&. This feature is discussed in detail below\&. .sp .in -3 \(bu .mk .in +3 .rt \fBpopt\fR can exec external option filters\&. .sp .in -3 \(bu .mk .in +3 .rt \fBpopt\fR can automatically generate help and usage messages for the application\&. .sp .in -3 .in -2 .PP The \fBpopt\fR library supports short and long options\&. A short option consists of a hyphen followed by a single alphanumeric character\&. A long option, common in GNU utilities, consists of two hyphens followed by a string composed of letters, numbers, and hyphens\&. Long options can optionally begin with a single hyphen, primarily to allow command-line compatibility between \fBpopt\fR applications and X toolkit applications\&. Either type of option can be followed by an argument\&. A space separates a short option from its argument\&. Either a space or an equals sign separates a long option from an argument\&. .PP The \fBpopt\fR library is highly portable and should 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\&. .PP The \fBpopt\fR library may be redistributed under the X consortium license, see the file \fBCOPYING\fR in the \fBpopt\fR source distribution for details\&. .SH "" .SS "Option Tables" .PP Each application provides \fBpopt\fR with information about the command-line options for the application, by means of an option table\&. An option table is an array of \fBstruct poptOption\fR structures, with the following format: .sp .nf \f(CW#include struct poptOption { const char * longName; /* may be NULL */ char shortName; /* may be \&'\0\&' */ int argInfo; void * arg; /* depends on argInfo */ int val; /* 0 means do not return, just update flag */ char * descrip; /* description for autohelp -- may be NULL */ char * argDescrip; /* argument description for autohelp */ };\fR .fi .sp .SS "Option Table Members" .PP Each member of the table defines a single option that may be passed to the program\&. Long and short options are considered to be a single option that can occur in two different forms\&. The option table members are as follows: .sp .ne 2 .mk \fB\fBlongName\fR\fR .in +24n .rt Defines the name of the option in a long name\&. .sp .sp 1 .in -24n .sp .ne 2 .mk \fB\fBshortName\fR\fR .in +24n .rt Defines the name of the option in a single character\&. .sp .sp 1 .in -24n .sp .ne 2 .mk \fB\fBargInfo\fR\fR .in +24n .rt Tells \fBpopt\fR what type of argument is expected after the option\&. Valid values are as follows: .sp .sp .ne 2 .mk \fBPOPT_ARG_DOUBLE\fR .in +16n .rt Double argument expected, \fBarg\fR type: \fBdouble\fR .sp .sp 2 .in -16n .sp .ne 2 .mk \fBPOPT_ARG_FLOAT\fR .in +16n .rt Float argument expected, \fBarg\fR type: \fBfloat\fR .sp .sp 1 .in -16n .sp .ne 2 .mk \fBPOPT_ARG_INT\fR .in +16n .rt Integer argument expected, \fBarg\fR type: \fBint\fR .sp .sp 1 .in -16n .sp .ne 2 .mk \fBPOPT_ARG_LONG\fR .in +16n .rt Long integer expected, \fBarg\fR type: \fBlong\fR .sp .sp 1 .in -16n .sp .ne 2 .mk \fBPOPT_ARG_NONE\fR .in +16n .rt No argument expected, \fBarg\fR type: \fBint\fR .sp .sp 1 .in -16n .sp .ne 2 .mk \fBPOPT_ARG_STRING\fR .in +16n .rt No type checking to be performed, \fBarg\fR type: \fBchar *\fR .sp .sp 1 .in -16n .sp .ne 2 .mk \fBPOPT_ARG_VAL\fR .in +16n .rt Integer value taken from val, \fBarg\fR type: \fBint\fR .sp .sp 1 .in -16n For numeric values, if the \fBargInfo\fR value is bitwise or\&'d with one of POPT_ARGFLAG_OR, POPT_ARGFLAG_AND, or POPT_ARGFLAG_XOR, 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 before saving\&. For the common operations of setting or clearing bits, POPT_BIT_SET and POPT_BIT_CLR have the appropriate flags set to perform bit operations\&. .sp If the \fBargInfo\fRvalue is bitwise or\&'d with POPT_ARGFLAG_ONEDASH, the long argument may be given with a single hyphen instead of two\&. For example, if -\fB-longopt\fR is an option with POPT_ARGFLAG_ONEDASH, -\fBlongopt\fR is also accepted\&. .sp .sp 0 .in -24n .sp .ne 2 .mk \fB\fBarg\fR\fR .in +24n .rt Allows \fBpopt\fR to automatically update program variables\&. If \fBarg\fR is NULL, \fBpopt\fR ignores \fBarg\fR and takes no special action\&. Otherwise, \fBarg\fR points to a variable of the appropriate type, as follows: .sp .in +2 \(bu .mk .in +3 .rt If \fBargInfo\fR is POPT_ARG_NONE, the variable pointed to by \fBarg\fR is set to 1 when the option is used\&. .sp .in -3 \(bu .mk .in +3 .rt If the option takes an argument, the variable pointed to by \fBarg\fR is updated to reflect the value of the argument\&. Any string is acceptable for POPT_ARG_STRING arguments\&. POPT_ARG_INT, POPT_ARG_LONG, POPT_ARG_FLOAT, and POPT_ARG_DOUBLE arguments are converted to the appropriate type, and an error returned if the conversion fails\&. .sp .in -3 .in -2 .sp POPT_ARG_VAL causes \fBarg\fR to be set to the integer value of \fBval\fR when the argument is found\&. This is useful for mutually-exclusive arguments in cases where it is not an error for multiple arguments to occur and where you want the last argument specified to take precedence, for example, \fBrm -i -f\fR\&. POPT_ARG_VAL causes the parsing function not to return a value, because the value of \fBval\fR has already been used\&. .sp If the \fBargInfo\fR value is bitwise or\&'d with POPT_ARGFLAG_OPTIONAL, the argument to the long option may be omitted\&. If the long option is used 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 that of a long option with an argument\&. .sp .sp 1 .in -24n .sp .ne 2 .mk \fB\fBval\fR\fR .in +24n .rt The value returned by the \fBpopt\fR parsing function when the option is encountered\&. If \fBval\fR is 0, the parsing function does not return a value\&. Instead, \fBpopt\fR parses the next command-line argument\&. .sp .sp 1 .in -24n .sp .ne 2 .mk \fBdescrip\fR .in +24n .rt Text description of the argument\&. Only required if automatic help messages are desired\&. Automatic usage messages can be generated without this argument\&. .sp .sp 1 .in -24n .sp .ne 2 .mk \fBargDescrip\fR .in +24n .rt Short summary of the type of arguments expected by the option, or NULL if the option does not require any arguments\&. Only required if automatic help messages are desired\&. Automatic usage messages can be generated without this argument\&. .sp .sp 1 .in -24n .PP The final structure in the table should have all pointer values set to NULL and all arithmetic values set to 0, marking the end of the table\&. The macro POPT_TABLEEND performs these tasks\&. .SS "Help and Usage Output" .PP If \fBpopt\fR should automatically provide -\fB\(miusage\fR and -\fB\(mihelp\fR options, one line in the option table should contain the macro POPT_AUTOHELP\&. This macro includes another option table, via POPT_ARG_INCLUDE_TABLE, which provides the table entries for these arguments\&. When the -\fB\(miusage\fR or -\fB\(mihelp\fR option is passed to applications that use \fBpopt\fR automatic help, \fBpopt\fR displays the appropriate message on \fBstderr\fR, and exits the application with a return code of 0\&. To use \fBpopt\fR automatic help generation in a different way, you must explicitly add the option entries to the application\&'s option table, instead of using POPT_AUTOHELP\&. .PP If the \fBargInfo\fR value is bitwise or\&'d with POPT_ARGFLAG_DOC_HIDDEN, the argument is not shown in help output\&. .PP If the \fBargInfo\fR value is bitwise or\&'d with POPT_ARGFLAG_SHOW_DEFAULT, the inital value of the \fBarg\fR is shown in help output\&. .SS "Special Option Table Entries" .PP Two types of option table entries do not specify command-line options\&. When either of these types of entries is used, the \fBlongName\fR element must be NULL and the \fBshortName\fR element must be \fB\\0\fR\&. .PP The first of these special entry types allows the application to nest another option table in the current option table\&. Such nesting may extend quite deeply, the actual depth is limited by the application stack\&. Including other option tables allows a library to provide a standard set of command-line options to every application that uses the library\&. This is often done in graphical programming toolkits, for example\&. To nest another option table, 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 help generation is used, the \fBdescrip\fR field should contain an overall description of the option table being included\&. .PP The other special option table entry type tells \fBpopt\fR to call a function when any option in that table is found\&. This callback functionality is especially useful when included option tables are used, because the application that provides the top-level option table does not need to be aware of the other options that are provided by the included table\&. When a callback is set for a table, the parsing function never returns information on an option in the table\&. Instead, option information must be retained via the callback or by having \fBpopt\fR set a variable through the option\&'s \fBarg\fR field\&. Option callbacks should match the following prototype: .sp .nf void poptCallbackType(poptContext con, const struct poptOption * opt, const char * arg, void * data); .fi .sp .PP The callback uses the following parameters: .sp .ne 2 .mk \fB\fBcon\fR\fR .in +16n .rt The context that is being parsed\&. See the next section for information on contexts\&. .sp .sp 1 .in -16n .sp .ne 2 .mk \fB\fBopt\fR\fR .in +16n .rt The option that triggered this callback\&. .sp .sp 1 .in -16n .sp .ne 2 .mk \fB\fBarg\fR\fR .in +16n .rt The argument for the \fBopt\fR option\&. If the option does not take an argument, \fBarg\fR is NULL\&. .sp .sp 1 .in -16n .sp .ne 2 .mk \fB\fBdata\fR\fR .in +16n .rt Taken from the \fBdescrip\fR field of the option table entry that defined the callback\&. As \fBdescrip\fR is a pointer, this allows you to pass an arbitrary set of data to callback functions, though a typecast must be used\&. .sp .sp 1 .in -16n .PP The option table entry that defines a callback has an \fBargInfo\fR of POPT_ARG_CALLBACK, an \fBarg\fR that points to the callback function, and a \fBdescrip\fR field that specifies an arbitrary pointer to be passed to the callback\&. .SS "Creating a Context" .PP \fBpopt\fR can interleave the parsing of multiple command-line sets\&. \fBpopt\fR allows this by keeping all of the state information for a particular set of command-line arguments in a \fBpoptContext\fR data structure, an opaque type that should not be modified outside the \fBpopt\fR library\&. .PP New \fBpopt\fR contexts are created by \fBpoptGetContext()\fR: .sp .nf \f(CWpoptContext poptGetContext(const char * name, int argc, const char ** argv, const struct poptOption * options, int flags);\fR .fi .sp .PP The \fBpoptGetContext()\fR function takes the following parameters: .sp .ne 2 .mk \fB\fBname\fR\fR .in +24n .rt Used only for alias handling\&. \fBname\fR should be the name of the application whose options are being parsed, or should be NULL if no option aliasing is desired\&. .sp .sp 1 .in -24n .sp .ne 2 .mk \fB\fBargc\fR, \fBargv\fR\fR .in +24n .rt Specifies the command-line arguments to parse\&. These arguments are generally passed to \fBpoptGetContext()\fR exactly as they were passed to the application\&'s \fBmain()\fR function\&. .sp .sp 1 .in -24n .sp .ne 2 .mk \fB\fBoptions\fR\fR .in +24n .rt Points to the table of command-line options\&. See the Option Tables section above\&. .sp .sp 1 .in -24n .sp .ne 2 .mk \fB\fBflags\fR\fR .in +24n .rt Can take one of the following values: .sp .sp .ne 2 .mk \fBPOPT_CONTEXT_NO_EXEC\fR .in +24n .rt Ignore \fBexec\fR expansions .sp .sp 2 .in -24n .sp .ne 2 .mk \fBPOPT_CONTEXT_KEEP_FIRST\fR .in +24n .rt Do not ignore \fBargv[0]\fR .sp .sp 1 .in -24n .sp .ne 2 .mk \fBPOPT_CONTEXT_POSIXMEHARDER\fR .in +24n .rt Options cannot follow arguments .sp .sp 1 .in -24n .sp 0 .in -24n .PP A \fBpoptContext\fR keeps track of which options have already been parsed and which remain to be parsed\&. If an application wishes to restart processing the options of a set of arguments, the application can reset the \fBpoptContext\fR by passing the context as the sole argument to \fBpoptResetContext()\fR\&. .PP 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 as its sole argument and frees the resources that the context is using\&. .PP Here are the prototypes of both \fBpoptResetContext()\fR and \fBpoptFreeContext()\fR: .sp .nf \f(CW#include void poptFreeContext(poptContext con); void poptResetContext(poptContext con);\fR .fi .sp .SS "Parsing the Command Line" .PP After an application has created a \fBpoptContext\fR, the \fBpoptContext\fR may begin parsing arguments\&. \fBpoptGetNextOpt()\fR performs the actual argument parsing: .sp .nf \f(CW#include int poptGetNextOpt(poptContext con);\fR .fi .sp .PP 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 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 entry for the option is not zero, the function returns that value\&. Otherwise, \fBpoptGetNextOpt()\fR continues to the next argument\&. .PP \fBpoptGetNextOpt()\fR returns \(mi1 when the final argument has been parsed, and other negative values when errors occur\&. Therefore, you should ensure that the \fBval\fR elements in the option table are greater than 0\&. .PP If all of the command-line options are handled through \fBarg\fR pointers, command-line parsing is reduced to the following line of code: .sp .nf \f(CWrc = poptGetNextOpt(poptcon);\fR .fi .sp .PP Many applications require more complex command-line parsing than this, however, and use the following structure: .sp .nf \f(CWwhile ((rc = poptGetNextOpt(poptcon)) > 0) { switch (rc) { /* specific arguments are handled here */ } }\fR .fi .sp .PP When returned options are handled, the application needs to know the value of any arguments that were specified after the option\&. There are two ways to discover these values: .sp .in +2 \(bu .mk .in +3 .rt Ask \fBpopt\fR to populate a variable with the value of the option from the option table\&'s \fBarg\fR elements\&. .sp .in -3 \(bu .mk .in +3 .rt Use \fBpoptGetOptArg()\fR: .sp .nf \f(CW#include const char * poptGetOptArg(poptContext con);\fR .fi .sp .sp .in -3 .in -2 .PP The \fBpoptGetOptArg()\fR function returns the argument given for the final option returned by \fBpoptGetNextOpt()\fR, or returns NULL if no argument was specified\&. .SS "Leftover Arguments" .PP Many applications take an arbitrary number of command-line arguments, such as a list of file names\&. When \fBpopt\fR encounters an argument that does not begin with a hyphen, \fBpopt\fR assumes that this is such an argument, and adds the argument to a list of leftover arguments\&. Three functions allow applications to access such arguments: .sp .ne 2 .mk \fB\fBconst char * poptGetArg(poptContext con);\fR\fR .sp .6 .in +4 Returns the next leftover argument and marks the argument as processed\&. .sp .sp 1 .in -4 .sp .ne 2 .mk \fB\fBconst char * poptPeekArg(poptContext con);\fR\fR .sp .6 .in +4 Returns the next leftover argument but does not mark the argument as processed\&. This allows an application to look ahead into the argument list, without modifying the list\&. .sp .sp 1 .in -4 .sp .ne 2 .mk \fB\fBconst char ** poptGetArgs(poptContext con);\fR\fR .sp .6 .in +4 Returns all of the leftover arguments in a manner identical to \fBargv\fR\&. The final element in the returned array points to NULL, indicating the end of the arguments\&. .sp .sp 1 .in -4 .SS "Automatic Help Messages" .PP The popt library can automatically generate help messages that describe the options that an application accepts\&. Two types of help messages can be generated: .sp .in +2 \(bu .mk .in +3 .rt Usage messages are short messages that list valid options, but do not describe the options\&. .sp .in -3 \(bu .mk .in +3 .rt Help messages describe each option in one or more lines, resulting in a longer but more useful message\&. .sp .in -3 .in -2 .PP Whenever automatic help messages are used, the \fBdescrip\fR and \fBargDescrip\fR members of the \fBstruct poptOption\fR structure should be populated for each option\&. .PP The POPT_AUTOHELP macro makes it easy to add usage and help messages to your application, as described earlier in this man page\&. If you need more control over your help messages, use the following functions: .sp .nf \f(CW#include void poptPrintHelp(poptContext con, FILE * f, int flags); void poptPrintUsage(poptContext con, FILE * f, int flags);\fR .fi .sp .PP \fBpoptPrintHelp()\fR displays the standard help message to the \fBstdio\fR file descriptor \fBf\fR, while \fBpoptPrintUsage()\fR displays the shorter usage message\&. Both functions currently ignore the \fBflags\fR argument, which is provided for future functionality\&. .SS "Option Aliasing" .PP One of the primary benefits of \fBpopt\fR is the ability to use option aliasing\&. Option aliasing allows the user to specify options that \fBpopt\fR expands into other options\&. For example\&. if the standard \fBgrep\fR command made use of \fBpopt\fR, 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 files\&. .SS "Specifying Aliases" .PP Aliases are normally specified in two places: .sp .in +2 \(bu .mk .in +3 .rt \fB/etc/popt\fR .sp .in -3 \(bu .mk .in +3 .rt \fB$HOME/\&.popt\fR .sp .in -3 .in -2 .PP Both files have the same format, that is, an arbitrary number of lines formatted as follows: .PP .nf \fIappname\fR alias \fInewoption\fR \fIexpansion\fR .fi .PP An alias specification is composed of the following elements: .sp .ne 2 .mk \fB\fIappname\fR\fR .in +24n .rt Specifies the name of the application, which must be the same as the \fBname\fR parameter passed to \fBpoptGetContext()\fR\&. This allows each file to specify aliases for multiple programs\&. .sp .sp 1 .in -24n .sp .ne 2 .mk \fBalias\fR .in +24n .rt Specifies that an alias is being defined\&. Currently, \fBpopt\fR configuration files support only aliases, but other abilities may be added in the future\&. .sp .sp 1 .in -24n .sp .ne 2 .mk \fB\fInewoption\fR\fR .in +24n .rt Specifies the option that should be aliased, either a short option or a long option\&. .sp .sp 1 .in -24n .sp .ne 2 .mk \fB\fIexpansion\fR\fR .in +24n .rt Specifies the expansion for the alias\&. The expansion is parsed in a similar way to a shell command: backslashes are allowed, and single quotation marks can be used for quoting\&. If a backslash is the final character on a line, the next line in the file is assumed to be a logical continuation of the line containing the backslash, just as in a shell command\&. .sp .sp 1 .in -24n .sp .PP For example, the following entry would add to the \fBgrep\fR command the -\fB\(mitext\fR option described earlier: .PP \f(CWgrep alias --text -i -n -E -2\fR .SS "Enabling Aliases" .PP An application must enable alias expansion for a \fBpoptContext\fR, before calling \fBpoptGetNextArg()\fR for the first time\&. Three functions define aliases for a context: .sp .ne 2 .mk \fBint poptReadDefaultConfig(poptContext con, int flags);\fR .sp .6 .in +4 Reads aliases from \fB/etc/popt\fR and \fB$HOME/\&.popt\fR\&. The \fBflags\fR argument should be NULL, it is provided only for future expansion\&. .sp .sp 1 .in -4 .sp .ne 2 .mk \fBint poptReadConfigFile(poptContext con, char * fn);\fR .sp .6 .in +4 Opens the file specified by \fBfn\fR and parses the file as a \fBpopt\fR configuration file\&. This allows applications to use application-specific configuration files\&. .sp .sp 1 .in -4 .sp .ne 2 .mk \fBint poptAddAlias(poptContext con, struct poptAlias alias, int flags);\fR .sp .6 .in +4 Adds a new alias to a context\&. This function is useful when processes want to specify aliases without having to read them from a configuration file\&. The \fBflags\fR argument should be 0, it is provided only for future expansion\&. The new alias is specified as a \fBstruct poptAlias\fR, which is defined as follows: .sp .sp .nf \f(CWstruct poptAlias { const char * longName; /* may be NULL */ char shortName; /* may be \&'\0\&' */ int argc; const char ** argv; /* must be free()able */ };\fR .fi .sp \fBlongName\fR and \fBshortName\fR specify the option that is aliased\&. \fBargc\fR and \fBargv\fR define the expansion to use when the aliases option is encountered\&. .sp .sp 1 .in -4 .SS "Parsing Argument Strings" .PP \fBpopt\fR usually parses arguments that are already divided into an \fBargv\fR-style array\&. However, some applications need to parse strings that are formatted identically to command lines\&. To facilitate this, \fBpopt\fR provides a function that parses a string into an array of strings, using rules similar to those of normal shell parsing: .sp .nf \f(CW#include int poptParseArgvString(char * s, int * argcPtr, char *** argvPtr); int poptDupArgv(int argc, const char ** argv, int * argcPtr, const char *** argvPtr);\fR .fi .sp .PP The string \fBs\fR is parsed into an \fBargv\fR-style array\&. The integer pointed to by the \fBargcPtr\fR parameter contains the number of elements parsed, and the final \fBargvPtr\fR parameter contains the address of the newly created array\&. The routine \fBpoptDupArgv()\fR can be used to make a copy of an existing argument array\&. .PP The \fBargvPtr\fR created by \fBpoptParseArgvString()\fR or \fBpoptDupArgv()\fR can be passed directly to \fBpoptGetContext()\fR\&. Both routines return a single dynamically allocated contiguous block of storage and should be freed using \fBfree()\fR when the application is finished with the storage\&. .SS "Handling Extra Arguments" .PP Some applications implement the equivalent of option aliasing but do so using special logic\&. The \fBpoptStuffArgs()\fR function allows an application to insert new arguments into the current \fBpoptContext\fR: .sp .nf \f(CW#include int poptStuffArgs(poptContext con, const char ** argv);\fR .fi .sp .PP The passed \fBargv\fR must have a NULL pointer as its final element\&. When \fBpoptGetNextOpt()\fR is next called, the "stuffed" arguments are the first to be parsed\&. \fBpopt\fR returns to the normal arguments when all of the stuffed arguments have been exhausted\&. .SH "" .PP All of the \fBpopt\fR functions that can return errors return integers\&. When an error occurs, a negative error code is returned\&. The following error codes can occur: .sp .ne 2 .mk \fBPOPT_ERROR_BADNUMBER\fR .in +24n .rt A string-to-number conversion failed because the string contains nonnumeric characters\&. This occurs when \fBpoptGetNextOpt()\fR is processing an argument of type POPT_ARG_INT, POPT_ARG_LONG, POPT_ARG_FLOAT, or POPT_ARG_DOUBLE\&. .sp .sp 1 .in -24n .sp .ne 2 .mk \fBPOPT_ERROR_BADOPT\fR .in +24n .rt An option was specified in \fBargv\fR but is not in the option table\&. This error can be returned only from \fBpoptGetNextOpt()\fR\&. .sp .sp 1 .in -24n .sp .ne 2 .mk \fBPOPT_ERROR_BADQUOTE\fR .in +24n .rt A parsed string has a quotation mismatch, for example, a single quotation mark\&. \fBpoptParseArgvString()\fR, \fBpoptReadConfigFile()\fR, or \fBpoptReadDefaultConfig()\fR can return this error\&. .sp .sp 1 .in -24n .sp .ne 2 .mk \fBPOPT_ERROR_ERRNO\fR .in +24n .rt A system call returned with an error, and \fBerrno\fR still contains the error from the system call\&. Both \fBpoptReadConfigFile()\fR and \fBpoptReadDefaultConfig()\fR can return this error\&. .sp .sp 1 .in -24n .sp .ne 2 .mk \fBPOPT_ERROR_NOARG\fR .in +24n .rt An option that requires an argument was specified on the command line, but no argument was given\&. This error can be returned only by \fBpoptGetNextOpt()\fR\&. .sp .sp 1 .in -24n .sp .ne 2 .mk \fBPOPT_ERROR_OPTSTOODEEP\fR .in +24n .rt A set of option aliases is nested too deeply\&. Currently, \fBpopt\fR follows options to only 10 levels, to prevent infinite recursion\&. Only \fBpoptGetNextOpt()\fR can return this error\&. .sp .sp 1 .in -24n .sp .ne 2 .mk \fBPOPT_ERROR_OVERFLOW\fR .in +24n .rt A string-to-number conversion failed because the number is too large or too small\&. This error can occur only when \fBpoptGetNextOpt()\fR is processing an argument of type POPT_ARG_INT, POPT_ARG_LONG, POPT_ARG_FLOAT, or POPT_ARG_DOUBLE\&. .sp .sp 1 .in -24n .PP Two functions allow applications to provide good error messages: .sp .ne 2 .mk \fBconst char *const poptStrerror(const int error);\fR .sp .6 .in +4 Takes a \fBpopt\fR error code and returns a string describing the error, just as with the standard \fBstrerror()\fR function\&. .sp .sp 1 .in -4 .sp .ne 2 .mk \fBconst char * poptBadOption(poptContext con, int flags);\fR .sp .6 .in +4 Returns the option that caused the error, if an error occurred during \fBpoptGetNextOpt()\fR\&. If the \fBflags\fR argument is set to POPT_BADOPTION_NOALIAS, the outermost option is returned\&. Otherwise, \fBflags\fR should be 0, and the option that is returned may have been specified through an alias\&. .sp .sp 1 .in -4 .PP These two functions ensure that \fBpopt\fR error handling is trivial for most applications\&. When an error is detected from most of the functions, an error message is printed along with the error string from \fBpoptStrerror()\fR\&. When an error occurs during argument parsing, code similar to the following displays a useful error message: .sp .nf \f(CWfprintf(stderr, "%s: %s\n", poptBadOption(optCon, POPT_BADOPTION_NOALIAS), poptStrerror(rc));\fR .fi .sp .SH "" .PP \fBExample 1: Parse Program Created From robin Program\fR .PP The following example is a simplified version of the \fBrobin\fR program that appears in Chapter 15 of "Linux Application Development" by Michael K\&. Johnson and Erik W\&. Troan (copyright 1998 by Addison Wesley Longman, Inc\&.)\&. The \fBrobin\fR program has been stripped of everything but its argument-parsing logic, slightly reworked, and renamed \fBparse\fR\&. This program illustrates some of the features of the extremely rich \fBpopt\fR library\&. .sp .nf \f(CW#include #include void usage(poptContext optCon, int exitcode, char *error, char *addl) { poptPrintUsage(optCon, stderr, 0); if (error) fprintf(stderr, "%s: %s0, error, addl); exit(exitcode); } int main(int argc, char *argv[]) { char c; /* used for argument parsing */ int i = 0; /* used for tracking options */ char *portname; int speed = 0; /* used in argument parsing to set speed */ int raw = 0; /* raw mode? */ int j; char buf[BUFSIZ+1]; poptContext optCon; /* context for parsing command-line options */ struct poptOption optionsTable[] = { { "bps", \&'b\&', POPT_ARG_INT, &speed, 0, "signaling rate in bits-per-second", "BPS" }, { "crnl", \&'c\&', 0, 0, \&'c\&', "expand cr characters to cr/lf sequences" }, { "hwflow", \&'h\&', 0, 0, \&'h\&', "use hardware (RTS/CTS) flow control" }, { "noflow", \&'n\&', 0, 0, \&'n\&', "use no flow control" }, { "raw", \&'r\&', 0, &raw, 0, "don\&'t perform any character conversions" }, { "swflow", \&'s\&', 0, 0, \&'s\&', "use software (XON/XOF) flow control" } , POPT_AUTOHELP { NULL, 0, 0, NULL, 0 } }; optCon = poptGetContext(NULL, argc, argv, optionsTable, 0); poptSetOtherOptionHelp(optCon, "[OPTIONS]* "); if (argc < 2) { poptPrintUsage(optCon, stderr, 0); exit(1); } /* Now do options processing, get portname */ while ((c = poptGetNextOpt(optCon)) >= 0) { switch (c) { case \&'c\&': buf[i++] = \&'c\&'; break; case \&'h\&': buf[i++] = \&'h\&'; break; case \&'s\&': buf[i++] = \&'s\&'; break; case \&'n\&': buf[i++] = \&'n\&'; break; } } portname = poptGetArg(optCon); if((portname == NULL) || !(poptPeekArg(optCon) == NULL)) usage(optCon, 1, "Specify a single port", "\&.e\&.g\&., /dev/cua0"); if (c < -1) { /* an error occurred during option processing */ fprintf(stderr, "%s: %s\n", poptBadOption(optCon, POPT_BADOPTION_NOALIAS), poptStrerror(c)); return 1; } /* Print out options, portname chosen */ printf("Options chosen: "); for(j = 0; j < i ; j++) printf("-%c ", buf[j]); if(raw) printf("-r "); if(speed) printf("-b %d ", speed); printf("\nPortname chosen: %s\n", portname); poptFreeContext(optCon); exit(0); } \fR .fi .sp .PP RPM, a popular Linux package management application, uses several \fBpopt\fR features\&. Many RPM command-line arguments are implemented using \fBpopt\fR aliases, which makes RPM an excellent example of how to take advantage of the \fBpopt\fR library\&. For more information about RPM, see \fBhttp://www\&.rpm\&.org\fR\&. The \fBpopt\fR source code distribution includes test programs that use all of the features of the \fBpopt\fR libraries in various ways\&. If a \fBpopt\fR feature does not work for you, check the \fBpopt\fR test code\&. .SH "" .PP The following files are used by this library: .sp .ne 2 .mk \fB\fB/usr/lib/libpopt\&.so\fR \fR .in +24n .rt Command Line Parser API shared library .sp .sp 1 .in -24n .SH "" .PP \fBgetopt\fR(3), \fBattributes\fR(5) .SH "" .PP Updated by Erwann Chenede, Sun Microsystems Inc\&., 2003\&. Written by Erik W\&. Troan (ewt@redhat\&.com), Michael K\&. Johnson, and Robert Lynch\&. ...\" created by instant / solbook-to-man, Tue 21 Aug 2012, 08:56