popt.3

popt-1.7.tar.gz ninigui之MDE编译库支持文件库

code similiar to the following displays a useful error message:
.sp
.nf
fprintf(stderr, "%s: %s\\n",
        poptBadOption(optCon, POPT_BADOPTION_NOALIAS),
        poptStrerror(rc));
.fi
.sp
.SH "OPTION ALIASING"
.RB "One of the primary benefits of using popt over " getopt() " is the "
ability to use option aliasing. This lets the user specify options that 
popt expands into other options when they are specified. If the standard 
.RB "grep program made use of popt, users could add a " --text " option "
.RB "that expanded to " "-i -n -E -2" " to let them more easily find "
information in text files.
.sp
.SS "1. SPECIFYING ALIASES"
.RI "Aliases are normally specified in two places: " /etc/popt 
.RB "and the " .popt " file in the user's home directory (found through "
.RB "the " HOME " environment variable). Both files have the same format, "
an arbitrary number of lines formatted like this:
.sp
.IB appname " alias " newoption "" " expansion"
.sp
.RI "The " appname " is the name of the application, which must be the "
.RI "same as the " name " parameter passed to "
.BR poptGetContext() ". This allows each file to specify aliases for "
.RB "multiple programs. The " alias " keyword specifies that an alias is "
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.
.sp
.RB "The following entry would add a " --text " option to the grep command, "
as suggested at the beginning of this section.
.sp
.B "grep alias --text -i -n -E -2"
.SS "2. ENABLING ALIASES"
.RB "An application must enable alias expansion for a " poptContext 
.RB "before calling " poptGetNextArg() " for the first time. There are "
three functions that define aliases for a context:
.HP
.nf
.BI "int poptReadDefaultConfig(poptContext " con ", int " flags ");"
.fi
.RI "This function reads aliases from " /etc/popt " and the "
.BR .popt " file in the user's home directory. Currently, "
.IR flags " should be "
.BR NULL ", as it is provided only for future expansion."
.PP
.HP
.nf
.BI "int poptReadConfigFile(poptContext " con ", char * " fn ");"
.fi
.RI "The file specified by " fn " is opened and parsed as a popt "
configuration file. This allows programs to use program-specific 
configuration files.
.PP
.HP
.nf
.BI "int poptAddAlias(poptContext " con ", struct poptAlias " alias ",
.BI "                 int " flags ");"
.fi
Occasionally, processes want to specify aliases without having to
read them from a configuration file. This function adds a new alias
.RI "to a context. The " flags " argument should be 0, as it is "
currently reserved for future expansion. The new alias is specified 
.RB "as a " "struct poptAlias" ", which is defined as:"
.sp
.nf
struct poptAlias {
     const char * longName; /* may be NULL */
     char shortName; /* may be '\\0' */
     int argc;
     const char ** argv; /* must be free()able */
};
.fi
.sp
.RI "The first two elements, " longName " and " shortName ", specify "
.RI "the option that is aliased. The final two, " argc " and " argv ","
define the expansion to use when the aliases option is encountered.
.PP
.SH "PARSING ARGUMENT STRINGS"
Although popt is usually used for parsing arguments already divided into
.RI "an " argv "-style array, some programs need to parse strings that "
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.
.sp
.nf
.B "#include <popt.h>"
.BI "int poptParseArgvString(char * " s ", int * " argcPtr ",
.BI "                        char *** " argvPtr ");"
.BI "int poptDupArgv(int " argc ", const char ** " argv ", int * " argcPtr ",
.BI "                        const char *** " argvPtr ");"
.fi
.sp
.RI "The string s is parsed into an " argv "-style array. The integer "
.RI "pointed to by the " argcPtr " parameter contains the number of elements "
.RI "parsed, and the final " argvPtr " parameter contains the address of the"
newly created array.
.RB "The routine " poptDupArgv() " can be used to make a copy of an existing "
argument array.
.sp
.RI "The " argvPtr 
.RB "created by " poptParseArgvString() " or " poptDupArgv() " is suitable to pass directly "
.RB "to " poptGetContext() .
Both routines return a single dynamically allocated contiguous
.RB "block of storage and should be " free() "ed when the application is"
finished with the storage.
.SH "HANDLING EXTRA ARGUMENTS"
Some applications implement the equivalent of option aliasing but need
.RB "to do so through special logic. The " poptStuffArgs() " function "
allows an application to insert new arguments into the current 
.BR poptContext .
.sp
.nf
.B "#include <popt.h>"
.BI "int poptStuffArgs(poptContext "con ", const char ** " argv ");"
.fi
.sp
.RI "The passed " argv 
.RB "must have a " NULL " pointer as its final element. When "
.BR poptGetNextOpt() " is next called, the "
"stuffed" arguments are the first to be parsed. popt returns to the 
normal arguments once all the stuffed arguments have been exhausted.
.SH "EXAMPLE"
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.
.sp
.nf
#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\n", 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]* <port>");

   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);
}
.fi
.sp
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.
.SH BUGS
None presently known.
.SH AUTHOR
Erik W. Troan <[e-mail]>
.PP
This man page is derived in part from
.IR "Linux Application Development"
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.
.PP
Thanks to Robert Lynch for his extensive work on this man page.
.SH "SEE ALSO"
.BR getopt (3)
.sp
.IR "Linux Application Development" ", by Michael K. Johnson and "
Erik W. Troan (Addison-Wesley, 1998; ISBN 0-201-30821-5), Chapter 24.
.sp
.BR popt.ps " is a Postscript version of the above cited book "
chapter. It can be found in the source archive for popt available at: 
ftp://ftp.rpm.org/pub/rpm.