Content-type: text/html Manpage of POPT

POPT

Section: Linux Programmer's Manual (3)
Updated: June 30, 1998
Index Return to Main Contents

NAME

popt - Parse command line options

SYNOPSIS

#include <popt.h>

poptContext poptGetContext(char * name, int argc,
                           char ** argv,
                           struct poptOption * options,
                           int flags);

void poptFreeContext(poptContext con);

void poptResetContext(poptContext con);

int poptGetNextOpt(poptContext con);

char * poptGetOptArg(poptContext con);

char * poptGetArg(poptContext con);

char * poptPeekArg(poptContext con);

char ** poptGetArgs(poptContext con);

const char * poptStrerror(const int error);

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,
                        char *** argvPtr);

int poptStuffArgs(poptContext con, char ** argv);

DESCRIPTION

The popt library exists essentially for parsing command-line options. It is found superior in many ways when compared to parsing the argv array by hand or using the getopt functions getopt() and getopt_long() [see getopt(3)]. Some specific advantages of popt are: it does not utilize global variables, thus enabling multiple passes in parsing argv ; it can parse an arbitrary array of argv-style elements, allowing parsing of command-line-strings from any source; it provides a standard method of option aliasing (to be discussed at length below.); it can exec external option filters; and, finally, it can automatically generate help and usage messages for the application.

Like getopt_long(), the popt library supports short and long style options. Recall that a short option consists of a - character followed by a single alphanumeric character. A long option, common in GNU utilities, consists of two - characters followed by a string made up of letters, numbers and hyphens. Long options are optionally allowed to begin with a single -, primarily to allow command-line compatibility between popt applications and X toolkit applications. Either type of option may be followed by an argument. A space separates a short option from its arguments; either a space or an = separates a long option from an argument.

The popt library is highly portable and should work on any POSIX platform. The latest version is always available from: ftp://ftp.redhat.com/pub/redhat/code/popt.

It may be redistributed under either the GNU General Public License or the GNU Library General Public License, at the distributor's discretion.

BASIC POPT USAGE

1. THE OPTION TABLE

Applications provide popt with information on their command-line options by means of an "option table," i.e., an array of struct poptOption structures:

#include <popt.h>

struct poptOption {
    const char * longName; /* may be NULL */
    char shortName;        /* may be '\0' */
    int argInfo;
    void * arg;            /* depends on argInfo */
    int val;               /* 0 means don't return, just update flag */
    char * descrip;        /* description for autohelp -- may be NULL */
    char * argDescrip;     /* argument description for autohelp */
};

Each member of the table defines a single option that may be passed to the program. Long and short options are considered a single option that may occur in two different forms. The first two members, longName and shortName, define the names of the option; the first is a long name, while the latter is a single character.

The argInfo member tells popt what type of argument is expected after the argument. If no option is expected, POPT_ARG_NONE should be used. The rest of the valid values are shown in the following table:

If the argInfo value is bitwise or'd with POPT_ARGFLAG_ONEDASH,

the long argument may be given with a single - instead of two. For example,





































appropriate type, and an error returned if the conversion fails.

POPT_ARG_VAL causes arg to be set to the (integer) value of

val when the argument is found. This is most often 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 win; for example, "rm -i -f". POPT_ARG_VAL causes

the parsing function not to return a value, since the value of val

has already been used.

should return when the option is encountered. If it is 0, the parsing

function does not return a value, instead parsing the next

command-line argument.

if automatic help messages are desired (automatic usage messages can

arguments.

see below) in the main one which provides the table entries for these

use popt's automatical help, popt displays the appropriate message on

stderr as soon as it finds the option, and exits the program with a

return code of 0. If you want to use popt's automatic help generation in

a different way, you need to explicitly add the option entries to your programs

If the argInfo value is bitwise or'd with POPT_ARGFLAG_DOC_HIDDEN,

the argument will not be shown in help output.

The final structure in the table should have all the pointer values set

end of the table.

There are two types of option table entries which do not specify command

line options. When either of these types of entries are used, the

longName element must be NULL and the shortName element

must be '\0'.

The first of these special entry types allows the application to nest

another option table in the current one; such nesting may extend quite

deeply (the actual depth is limited by the program's stack). Including

other option tables allows a library to provide a standard set of

command-line options to every program which uses it (this is often done

in graphical programming toolkits, for example). To do this, set

the argInfo field to POPT_ARG_INCLUDE_TABLE and the

arg field to point to the table which is being included. If

automatic help generation is being used, the descrip field should

contain a overall description of the option table being included.

The other special option table entry type tells popt to call a function (a

callback) when any option in that table is found. This is especially usefull

when included option tables are being used, as the program which provides

the top-level option table doesn't need to be aware of the other options

which 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, options information must be retained via the callback

or by having popt set a variable through the option's arg field.

Option callbacks should match the following prototype:

The first parameter is the context which is being parsed (see the next

section for information on contexts), opt points to the option

which triggered this callback, and arg is the option's argument.

If the option does not take an argument, arg is NULL. The

final parameter, data is taken from the descrip field

of the option table entry which defined the callback. As descrip

is a pointer, this allows callback functions to be passed an arbitrary

set of data (though a typecast will have to be used).

The option table entry which defines a callback has an argInfo of

POPT_ARG_CALLBACK, an arg which points to the callback

function, and a descrip field which specifies an arbitrary pointer

to be passed to the callback.

popt can interleave the parsing of multiple command-line sets. It allows

this by keeping all the state information for a particular set of

command-line arguments in a

modified outside the popt library.

The first parameter,

should be the name of the application whose options are being parsed,

two arguments specify the command-line arguments to parse. These are

which was described in the previous section. The final parameter,

0 for compatibility with future versions of the popt library.

parsed and which remain, among other things. If a program wishes to

restart option processing of a set of arguments, it can reset the

When argument processing is complete, the process should free the

context is using.

argument parsing.

Taking the context as its sole argument, this function parses the next

command-line argument found. After finding the next argument in the

option table, the function fills in the object pointed to by the option

non-0, the function then returns that value. Otherwise,

parsed, and other negative values when errors occur. This makes it a

good idea to

pointers, command-line parsing is reduced to the following line of code:

rc = poptGetNextOpt(poptcon);

Many applications require more complex command-line parsing than this,

however, and use the following structure:

while ((rc = poptGetNextOpt(poptcon)) > 0) {

     switch (rc) {

          /* specific arguments are handled here */

     }

}

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 them. One is to ask popt to fill in a variable with the

This function returns the argument given for the final option returned by

Many applications take an arbitrary number of command-line arguments,

such as a list of file names. When popt encounters an argument that does

not begin with a -, it assumes it is such an argument and adds it to a list

of leftover arguments. Three functions allow applications to access such

arguments:

This function returns the next leftover argument and marks it as

processed.

The next leftover argument is returned but not marked as processed.

This allows an application to look ahead into the argument list,

without modifying the list.

All the leftover arguments are returned in a manner identical to

The popt library can automatically generate help messages which

describe the options a program accepts. There are two types of help

messages which can be generated. Usage messages are a short messages

which lists valid options, but does not describe them. Help messages

describe each option on one (or more) lines, resulting in a longer, but

more useful, message. Whenever automatic help messages are used, the

descrip and argDescrip fields struct poptOption members

should be filled in for each option.

The POPT_AUTOHELP macro makes it easy to add --usage and

--help messages to your program, and is described in part 1

of this man page. If more control is needed over your help messages,

the following two functions are available:

poptPrintHelp() displays the standard help message to the stdio file

descriptor f, while poptPrintUsage() displays the shorter usage

message. Both functions currently ignore the flags argument; it is

there to allow future changes.

All of the popt functions that can return errors return integers.

When an error occurs, a negative error code is returned. The

following table summarizes the error codes that occur:

Here is a more detailed discussion of each error:

An option that requires an argument was specified on the command

line, but no argument was given. This can be returned only by

A set of option aliases is nested too deeply. Currently, popt

follows options only 10 levels to prevent infinite recursion. Only

A parsed string has a quotation mismatch (such as a single quotation

A conversion from a string to a number (int or long) failed due

to the string containing nonnumeric characters. This occurs when

A string-to-number conversion failed because the number was too

contains the error from the system call. Both

return this error.

Two functions are available to make it easy for applications to provide

good error messages.

This function takes a popt error code and returns a string describing

returned may have been specified through an alias.

These two functions make popt error handling 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

code similiar to the following displays a useful error message:

fprintf(stderr, "%s: %s\n",

        poptBadOption(optCon, POPT_BADOPTION_NOALIAS),

        poptStrerror(rc));

ability to use option aliasing. This lets the user specify options that

popt expands into other options when they are specified. If the standard

information in text files.

an arbitrary number of lines formatted like this:

being defined; currently popt configuration files support only aliases, but

other abilities may be added in the future. The next option is the option

that should be aliased, and it may be either a short or a long option. The

rest of the line specifies the expansion for the alias. It is parsed

similarly to a shell command, which allows \, ", and ' to 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 shell.

as suggested at the beginning of this section.

three functions that define aliases for a context:

configuration file. This allows programs to use program-specific

configuration files.

Occasionally, processes want to specify aliases without having to

read them from a configuration file. This function adds a new alias

currently reserved for future expansion. The new alias is specified

struct poptAlias {

     char * longName; /* may be NULL */

     char shortName; /* may be '\0' */

     int argc;

     char ** argv; /* must be free()able */

};

define the expansion to use when the aliases option is encountered.

Although popt is usually used for parsing arguments already divided into

are formatted identically to command lines. To facilitate this, popt

provides a function that parses a string into an array of strings,

using rules similiar to normal shell parsing.

of elements parsed, and the pointer pointed to by the final parameter is

set to point to the newly created array. The array is dynamically

with it.

Some applications implement the equivalent of option aliasing but need

allows an application to insert new arguments into the current

"stuffed" arguments are the first to be parsed. popt returns to the

normal arguments once all the stuffed arguments have been exhausted.

The following example is a simplified version of the program "robin"

which appears in Chapter 15 of the text cited below. Robin has

been stripped of everything but its argument-parsing logic, slightly

reworked, and renamed "parse." It may prove useful in illustrating

at least some of the features of the extremely rich popt library.

#include <popt.h>

#include <stdio.h>

void usage(poptContext optCon, int exitcode, char *error, char *addl) {

    poptPrintUsage(optCon, stderr, 0);

    if (error) fprintf(stderr, "%s: %s, 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[] = {

   };

   optCon = poptGetContext(NULL, argc, argv, optionsTable, 0);

   poptSetOtherOptionHelp(optCon, "[OPTIONS]* <port>");

   if (argc < 2) {

   }

   /* 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);

}

RPM, a popular Linux package management program, makes heavy use

of popt's features. Many of its command-line arguments are implemented

through popt aliases, which makes RPM an excellent example of how to

take advantage of the popt library. For more information on RPM, see

http://www.rpm.org. The popt source code distribution includes test

program(s) which use all of the features of the popt libraries in

various ways. If a feature isn't working for you, the popt test code

is the first place to look.

None presently known.

Erik W. Troan <ewt@redhat.com>

This man page is derived in part from

by Michael K. Johnson and Erik W. Troan, Copyright (c) 1998 by Addison

Wesley Longman, Inc., and included in the popt documentation with the

permission of the Publisher and the appreciation of the Authors.

Thanks to Robert Lynch for his extensive work on this man page.

Erik W. Troan (Addison-Wesley, 1998; ISBN 0-201-30821-5), Chapter 24.

chapter. It can be found in the source archive for popt available at:

ftp://ftp.redhat.com/pub/redhat/code/popt

Index

1. THE OPTION TABLE

This document was created by man2html, using the manual pages.
Time: 18:20:03 GMT, October 29, 1999