Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
POPT(3) 		    Linux Programmer's Manual			 POPT(3)

NAME
     popt - Parse command line options

SYNOPSIS
     #include <popt.h>

     poptContext poptGetContext(const char * name, int argc,
				const char ** argv,
				const struct poptOption * options,
				unsigned 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 * 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);

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 dis-
     cussed at length below.); it can exec external  option  filters;  and,  fi-
     nally, it can automatically generate help and usage messages for the appli-
     cation.

     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 argu-
     ment.  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 distributed with rpm and is	always	available  from:
     ftp://ftp.rpm.org/pub/rpm/dist.

     It  may be redistributed under the X consortium license, see the file COPY-
     ING in the popt source distribution for details.

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' */
	 unsigned int argInfo;	  /* type of argument expected after the option */
	 void * arg;		  /* depends on argInfo */
	 int val;		  /* 0 means don't return, just update arg */
	 const char * descrip;	  /* description for autohelp -- may be NULL */
	 const char * argDescrip; /* argument description for autohelp -- may be NULL*/
     };

     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  short-
     Name,  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
     option.   If  no  argument  is expected, POPT_ARG_NONE should be used.  The
     valid values of argInfo are shown in the following table:

     Value		 Description			    arg Type
     POPT_ARG_NONE	 No argument expected		    int
     POPT_ARG_STRING	 No type checking to be performed   char *
     POPT_ARG_ARGV	 No type checking to be performed   char **
     POPT_ARG_SHORT	 A short argument is expected	    short
     POPT_ARG_INT	 An integer argument is expected    int
     POPT_ARG_LONG	 A long integer is expected	    long
     POPT_ARG_LONGLONG	 A long long integer is expected    long long
     POPT_ARG_VAL	 Integer value taken from val	    int
     POPT_ARG_FLOAT	 A float argument is expected	    float
     POPT_ARG_DOUBLE	 A double argument is expected	    double

     For numeric values, if the argInfo  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 argInfo	value  is  bitwise  or'd
     with  POPT_ARGFLAG_NOT,  the  value  will be negated before saving. For the
     common  operations  of  setting  and/or  clearing	bits,  POPT_BIT_SET  and
     POPT_BIT_CLR have the appropriate flags set to perform bit operations.

     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,  if
     --longopt is an option with POPT_ARGFLAG_ONEDASH, is specified, -longopt is
     accepted as well.

     The  next	element,  arg, allows popt to automatically update program vari-
     ables when the option is used. If arg is NULL, it is ignored and popt takes
     no special action.  Otherwise it should point to a variable of the type in-
     dicated in the right-most column of the table above.  A  POPT_ARG_ARGV  arg
     will  (re-)allocate  an  array of char * string pointers, append the string
     argument, and add a NULL sentinel at the end of the array as  needed.   The
     target  char  **  address	of  a POPT_ARG_ARGV arg should be initialized to
     NULL.

     If the option takes no argument (argInfo is  POPT_ARG_NONE),  the	variable
     pointed  to  by arg is set to 1 when the option is used.  (Incidentally, it
     will perhaps not escape the attention of  hunt-and-peck  typists  that  the
     value  of	POPT_ARG_NONE  is  0.)	If the option does take an argument, the
     variable that arg points to is updated to reflect the value  of  the  argu-
     ment.  Any string is acceptable for POPT_ARG_STRING and POPT_ARG_ARGV argu-
     ments,  but POPT_ARG_INT, POPT_ARG_SHORT, POPT_ARG_LONG, POPT_ARG_LONGLONG,
     POPT_ARG_FLOAT, and POPT_ARG_DOUBLE are converted to the 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  argu-
     ments 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.

     If the argInfo value is bitwise or'd with POPT_ARGFLAG_OPTIONAL, the  argu-
     ment  to the long option may be omitted. If the long option is used without
     an argument, a default value of zero or NULL will	be  saved  (if	the  arg
     pointer  is present), otherwise behavior will be identical to a long option
     with argument.

     The next option, val, is the value popt's parsing	function  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.

     The last two options, descrip and argDescrip are only required if automatic
     help messages are desired (automatic usage messages can be generated  with-
     out  them). descrip is a text description of the argument and argDescrip is
     a short summary of the type of arguments the option expects, or NULL if the
     option doesn't require any arguments.

     If popt should automatically provide --usage and --help (-?)  options,  one
     line  in  the table should be the macro POPT_AUTOHELP.  This macro includes
     another option table (via POPT_ARG_INCLUDE_TABLE ; see below) in  the  main
     one  which  provides the table entries for these arguments. When --usage or
     --help are passed to programs which use popt's automatic  help,  popt  dis-
     plays 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 auto-
     matic help generation in a different way, you need to  explicitly	add  the
     option  entries  to  your programs option table instead of using POPT_AUTO-
     HELP.

     If the argInfo value is bitwise or'd with POPT_ARGFLAG_DOC_HIDDEN, the  ar-
     gument will not be shown in help output.

     If  the  argInfo  value is bitwise or'd with POPT_ARGFLAG_SHOW_DEFAULT, the
     initial value of the arg will be shown in help output.

     The final structure in the table should have all the pointer values set  to
     NULL  and all the arithmetic values set to 0, marking the end of the table.
     The macro POPT_TABLEEND is provided to do that.

     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  an-
     other option table in the current one; such nesting may extend quite deeply
     (the  actual  depth is limited by the program's stack). Including other op-
     tion tables allows a library to provide a standard set of command-line  op-
     tions  to every program which uses it (this is often done in graphical pro-
     gramming 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 be-
     ing included. If automatic help generation is being used, the descrip field
     should contain an 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 useful
     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  ta-
     ble, the parsing function never returns information on an option in the ta-
     ble.  Instead,  options information must be retained via the callback or by
     having popt set a variable through the option's arg  field.   Option  call-
     backs should match the following prototype:

     void poptCallbackType(poptContext con,
			   const struct poptOption * opt,
			   const char * arg, void * data);

     The first parameter is the context which is being parsed (see the next sec-
     tion 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  de-
     scrip  is	a  pointer, this allows callback functions to be passed an arbi-
     trary 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 de-
     scrip field which specifies an arbitrary pointer to be passed to the  call-
     back.

   2. CREATING A CONTEXT
     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 poptContext data structure, an opaque type that should
     not be modified outside the popt library.

     New popt contexts are created by poptGetContext():

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

     The first parameter, name, is  used  only	for  alias  handling  (discussed
     later).  It  should  be the name of the application whose options are being
     parsed, or should be NULL if no option aliasing is desired.  The  next  two
     arguments	specify the command-line arguments to parse. These are generally
     passed to poptGetContext() exactly as they were  passed  to  the  program's
     main()  function. The options parameter points to the table of command-line
     options, which was described in the previous section. The final  parameter,
     flags, can be any bitwise or combination of the following four values:
     Value			  Description
     POPT_CONTEXT_NO_EXEC	  Ignore exec expansions
     POPT_CONTEXT_KEEP_FIRST	  Do not ignore argv[0]
     POPT_CONTEXT_POSIXMEHARDER   Options cannot follow arguments
     POPT_CONTEXT_ARG_OPTS	  Return the arguments as options of value 0

     A	poptContext  keeps  track  of which options have already been parsed and
     which remain, among other things. If a program  wishes  to  restart  option
     processing  of  a set of arguments, it can reset the poptContext by passing
     the context as the sole argument to poptResetContext().

     When argument processing is complete, the process should free the	poptCon-
     text as it contains dynamically allocated components. The poptFreeContext()
     function  takes  a poptContext as its sole argument and frees the resources
     the context is using.

     Here are the prototypes of both poptResetContext() and poptFreeContext():

     #include <popt.h>
     void poptFreeContext(poptContext con);
     void poptResetContext(poptContext con);

   3. PARSING THE COMMAND LINE
     After an application has created a poptContext, it may begin parsing  argu-
     ments. poptGetNextOpt() performs the actual argument parsing.

     #include <popt.h>
     int poptGetNextOpt(poptContext con);

     Taking the context as its sole argument, this function parses the next com-
     mand-line argument found. After finding the next argument in the option ta-
     ble,  the	function  fills in the object pointed to by the option table en-
     try's arg pointer if it is not NULL. If the val entry  for  the  option  is
     non-0,  the  function  then returns that value. Otherwise, poptGetNextOpt()
     continues on to the next argument.

     poptGetNextOpt() returns -1 when the final argument has  been  parsed,  and
     other  negative values when errors occur. This makes it a good idea to keep
     the val elements in the options table greater than 0.

     If all of the command-line options are handled through arg  pointers,  com-
     mand-line parsing is reduced to the following line of code:

     rc = poptGetNextOpt(poptcon);

     Many applications require more complex command-line parsing than this, how-
     ever, 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 value
     of the option through the option table's arg elements. The other is to  use
     poptGetOptArg():

     #include <popt.h>
     char * poptGetOptArg(poptContext con);

     This  function  returns the argument given for the final option returned by
     poptGetNextOpt(), or it returns NULL if no  argument  was	specified.   The
     calling function is responsible for deallocating this string.

   4. LEFTOVER ARGUMENTS
     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 be-
     gin 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 argu-
     ments:

     const char * poptGetArg(poptContext con);
	    This  function  returns  the  next leftover argument and marks it as
	    processed.

     const char * poptPeekArg(poptContext con);
	    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.

     const char ** poptGetArgs(poptContext con);
	    All the leftover arguments are returned in	a  manner  identical  to
	    argv.  The final element in the returned array points to NULL, indi-
	    cating the end of the arguments.

   5. AUTOMATIC HELP MESSAGES
     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 op-
     tions,  but  does	not describe them. Help messages describe each option on
     one (or more) lines, resulting in a longer, but more useful, message. When-
     ever 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  avail-
     able:

     #include <popt.h>
     void poptPrintHelp(poptContext con, FILE * f, int flags);
     void poptPrintUsage(poptContext con, FILE * f, int flags);

     poptPrintHelp()  displays	the  standard help message to the stdio file de-
     scriptor f, while poptPrintUsage() displays the shorter usage message. Both
     functions currently ignore the flags argument; it is there to allow  future
     changes.

ERROR HANDLING
     All  of the popt functions that can return errors return integers.  When an
     error occurs, a negative error code is returned. The following table summa-
     rizes the error codes that occur:

     Error		       Description
     POPT_ERROR_NOARG	       Argument missing for an option.
     POPT_ERROR_BADOPT	       Option's argument couldn't be parsed.
     POPT_ERROR_UNWANTEDARG    Option does not take an argument.
     POPT_ERROR_OPTSTOODEEP    Option aliasing nested too deeply.
     POPT_ERROR_BADQUOTE       Quotations do not match.
     POPT_ERROR_ERRNO	       errno set, use strerror(errno).
     POPT_ERROR_BADNUMBER      Option couldn't be converted to number.
     POPT_ERROR_OVERFLOW       A given number was too big or small.
     POPT_ERROR_BADOPERATION   Mutually exclusive logical operations requested.
     POPT_ERROR_NULLARG        opt->arg should not be NULL.
     POPT_ERROR_MALLOC	       Memory allocation failed.
     POPT_ERROR_BADCONFIG      Config file failed sanity test.

     Here is a more detailed discussion of each error:

     POPT_ERROR_NOARG
	    An option that requires an argument was  specified	on  the  command
	    line,  but no argument was given. This can be returned only by popt-
	    GetNextOpt().

     POPT_ERROR_BADOPT
	    An option was specified in argv but is not in the option table. This
	    error can be returned only from poptGetNextOpt().

     POPT_ERROR_OPTSTOODEEP
	    A set of option aliases is nested too deeply. Currently,  popt  fol-
	    lows  options only 10 levels (POPT_OPTION_DEPTH) to prevent infinite
	    recursion. Only poptGetNextOpt() can return this error.

     POPT_ERROR_BADQUOTE
	    A parsed string has a quotation mismatch (such as a single quotation
	    mark). poptParseArgvString(), poptReadConfigFile(),  or  poptReadDe-
	    faultConfig() can return this error.

     POPT_ERROR_ERRNO
	    A  system  call returned with an error, and errno still contains the
	    error from the system call. Both poptReadConfigFile() and  poptRead-
	    DefaultConfig() can return this error.

     POPT_ERROR_BADNUMBER
	    A  conversion  from a string to a number (int or long) failed due to
	    the string containing non-numeric characters. This occurs when popt-
	    GetNextOpt()  is  processing  an  argument	of  type   POPT_ARG_INT,
	    POPT_ARG_SHORT, POPT_ARG_LONG, POPT_ARG_LONGLONG, POPT_ARG_FLOAT, or
	    POPT_ARG_DOUBLE.

     POPT_ERROR_OVERFLOW
	    A  string-to-number  conversion  failed  because  the number was too
	    large or too small. Like POPT_ERROR_BADNUMBER, this error can  occur
	    only  when	poptGetNextOpt()  is  processing  an  argument	of  type
	    POPT_ARG_INT,  POPT_ARG_SHORT,   POPT_ARG_LONG,   POPT_ARG_LONGLONG,
	    POPT_ARG_FLOAT, or POPT_ARG_DOUBLE.

     POPT_ERROR_BADOPERATION
	    More  than one logical operation (AND, OR, XOR) was specified for an
	    option, or POPT_ARGFLAG_RANDOM was specified but the  platform  does
	    not  support  the  random()  function.  This can be returned only by
	    poptSaveLongLong(), poptSaveLong(),  poptSaveInt(),  poptSaveShort()
	    and poptGetNextOpt().

     POPT_ERROR_NULLARG
	    An operation was invoked on a null target arg (including zero-length
	    string  arguments).  In  the  poptBitsArgs()  case, this includes an
	    empty leftover argv array. This can only be returned  by  the  popt-
	    Bits*()  and  poptSave*()  functions,  poptConfigFileToString()  and
	    poptGetNextOpt().

     POPT_ERROR_MALLOC
	    Memory allocation failed. This can only  be  returned  by  poptRead-
	    File(),    poptDupArgv(),	poptParseArgvString(),	 poptConfigFile-
	    ToString() and poptGetNextOpt().

     POPT_ERROR_BADCONFIG
	    The popt configuration files are corrupted. This  can  only  be  re-
	    turned by poptReadConfigFile() and poptReadConfigFiles().

     Two  functions  are  available  to make it easy for applications to provide
     good error messages.

	    const char * poptStrerror(const int error);
	    This function takes a popt error code and returns a string	describ-
	    ing the error, just as with the standard strerror() function.

	    const char * poptBadOption(poptContext con, int flags);
	    If	an error occurred during poptGetNextOpt(), this function returns
	    the option that caused the error. If the flags argument  is  set  to
	    POPT_BADOPTION_NOALIAS, the outermost option is returned. Otherwise,
	    flags  should  be  0,  and the option that is 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 poptStrerror(). When an error oc-
     curs during argument parsing, code similar to the following displays a use-
     ful error message:

     fprintf(stderr, "%s: %s\n",
	     poptBadOption(optCon, POPT_BADOPTION_NOALIAS),
	     poptStrerror(rc));

OPTION ALIASING
     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  grep  program
     made use of popt, users could add a --text option that expanded to -i -n -E
     -2 to let them more easily find information in text files.

   1. SPECIFYING ALIASES
     Aliases  are normally specified in two places: /etc/popt and the .popt file
     in the user's home directory (found through the HOME environment variable).
     Both files have the same format, an arbitrary  number  of	lines  formatted
     like this:

     appname alias newoption expansion

     The  appname  is the name of the application, which must be the same as the
     name parameter passed to poptGetContext(). This allows each file to specify
     aliases for 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  simi-
     larly  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 back-
     slash, just as in shell.

     The following entry would add a --text option to the grep command, as  sug-
     gested at the beginning of this section.

     grep alias --text -i -n -E -2

   2. ENABLING ALIASES
     An application must enable alias expansion for a poptContext before calling
     poptGetNextArg()  for the first time. There are three functions that define
     aliases for a context:

	    int poptReadDefaultConfig(poptContext con, int flags);
	    This function reads aliases from /etc/popt and the .popt file in the
	    user's home directory. Currently, flags should be  NULL,  as  it  is
	    provided only for future expansion.

	    int poptReadConfigFile(poptContext con, char * fn);
	    The  file  specified by fn is opened and parsed as a popt configura-
	    tion file. This allows programs to use  program-specific  configura-
	    tion files.

	    int poptAddAlias(poptContext con, struct poptAlias alias,
			     int flags);
	    Occasionally,  processes  want  to specify aliases without having to
	    read them from a configuration file. This function adds a new  alias
	    to a context. The flags argument should be 0, as it is currently re-
	    served  for future expansion. The new alias is specified as a struct
	    poptAlias, which is defined as:

	    struct poptAlias {
		 const char * longName; /* may be NULL */
		 char shortName; /* may be '\0' */
		 int argc;
		 const char ** argv; /* must be free()able */
	    };

	    The first two elements, longName and shortName, specify  the  option
	    that  is aliased. The final two, argc and argv, define the expansion
	    to use when the aliases option is encountered.

PARSING ARGUMENT STRINGS
     Although popt is usually used for parsing arguments already divided into 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 similar to  nor-
     mal shell parsing.

     #include <popt.h>
     int poptParseArgvString(char * s, int * argcPtr,
			     char *** argvPtr);
     int poptDupArgv(int argc, const char ** argv, int * argcPtr,
			     const char *** argvPtr);

     The  string s is parsed into an argv-style array. The integer pointed to by
     the argcPtr parameter contains the number of elements parsed, and the final
     argvPtr parameter contains the address of the  newly  created  array.   The
     routine  poptDupArgv()  can  be used to make a copy of an existing argument
     array.

     The argvPtr created by poptParseArgvString() or poptDupArgv()  is	suitable
     to pass directly to poptGetContext().  Both routines return a single dynam-
     ically  allocated	contiguous  block of storage and should be free()ed when
     the application is finished with the storage.

HANDLING EXTRA ARGUMENTS
     Some applications implement the equivalent of option aliasing but	need  to
     do  so through special logic. The poptStuffArgs() function allows an appli-
     cation to insert new arguments into the current poptContext.

     #include <popt.h>
     int poptStuffArgs(poptContext con, const char ** argv);

     The passed argv must have a NULL pointer as its final element.  When  popt-
     GetNextOpt()  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.

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.

     #include <popt.h>
     #include <stdio.h>
     #include <stdlib.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[]) {
	int	c;	      /* used for argument parsing */
	int	i = 0;	      /* used for tracking options */
	int	speed = 0;    /* used in argument parsing to set speed */
	int	raw = 0;      /* raw mode? */
	int	j;
	char	buf[BUFSIZ+1];
	const char *portname;
	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", NULL },
	   { "hwflow", 'h', 0, 0, 'h',
	  "use hardware (RTS/CTS) flow control", NULL },
	   { "noflow", 'n', 0, 0, 'n',
	  "use no flow control", NULL },
	   { "raw", 'r', 0, &raw, 0,
	  "don't perform any character conversions", NULL },
	   { "swflow", 's', 0, 0, 's',
	  "use software (XON/XOF) flow control", NULL } ,
	   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);
     }

     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.

BUGS
     None presently known.

AUTHOR
     Erik W. Troan <ewt@redhat.com>

     This  man	page  is  derived  in part from 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.

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

SEE ALSO
     getopt(3)

     Linux Application Development, by Michael K. Johnson and Erik W. Troan (Ad-
     dison-Wesley, 1998; ISBN 0-201-30821-5), Chapter 24.

     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.

				  June 30, 1998 			 POPT(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=popt&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help