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 ar-
       ray 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	gener-
       ate help	and usage messages for the application.

       Like getopt_long(), the popt library supports short and long style  op-
       tions.	Recall	that a short option consists of	a - character followed
       by a single alphanumeric	character.  A long option, common in GNU util-
       ities, 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  op-
       tion 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 plat-
       form.  The latest version is distributed	with rpm and is	always	avail-
       able from: ftp://ftp.rpm.org/pub/rpm/dist.

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

BASIC POPT USAGE
   1. THE OPTION TABLE
       Applications provide popt with information on  their  command-line  op-
       tions  by  means	of an "option table," i.e., an array of	struct poptOp-
       tion 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 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 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 bit-
       wise or'd with POPT_ARGFLAG_NOT,	the value will be negated before  sav-
       ing.  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
       variables  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  indicated	in the right-most column of the	table above. A
       POPT_ARG_ARGV arg will (re-)allocate an array of	char *	string	point-
       ers,  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	 vari-
       able  pointed to	by arg is set to 1 when	the option is used.  (Inciden-
       tally, it will perhaps not escape the attention of  hunt-and-peck  typ-
       ists 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 argument.  Any string is  acceptable  for  POPT_ARG_STRING
       and   POPT_ARG_ARGV   arguments,	  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-exclu-
       sive 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 ex-
       ample, "rm -i -f".  POPT_ARG_VAL	causes the parsing function not	to re-
       turn a value, since the value of	val has	already	been used.

       If the argInfo 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 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  re-
       turn  when the option is	encountered.  If it is 0, the parsing function
       does not	return a value,	instead	parsing	the  next  command-line	 argu-
       ment.

       The last	two options, descrip and argDescrip are	only required if auto-
       matic help messages are desired (automatic usage	messages can be	gener-
       ated  without  them). descrip is	a text description of the argument and
       argDescrip is a short summary of	the type of arguments the  option  ex-
       pects, 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 auto-
       matic 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	option
       table instead of	using POPT_AUTOHELP.

       If the argInfo value is bitwise or'd with POPT_ARGFLAG_DOC_HIDDEN,  the
       argument	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 com-
       mand 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  com-
       mand-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 be-
       ing 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 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:

       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
       section for information on contexts), opt points	to  the	 option	 which
       triggered  this callback, and arg is the	option's argument.  If the op-
       tion 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.

   2. CREATING A CONTEXT
       popt  can  interleave the parsing of multiple command-line sets.	It al-
       lows 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 be-
       ing 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  ta-
       ble  of	command-line options, which was	described in the previous sec-
       tion. 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 pass-
       ing the context as the sole argument to poptResetContext().

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

       Here  are  the  prototypes  of both poptResetContext() and poptFreeCon-
       text():

       #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
       arguments. 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
       command-line argument found. After finding the next argument in the op-
       tion table, the function	fills in the object pointed to by  the	option
       table  entry'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, popt-
       GetNextOpt() 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,
       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  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	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:

       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,
	      indicating the end of the	arguments.

   5. AUTOMATIC	HELP MESSAGES
       The  popt  library  can	automatically generate help messages which de-
       scribe the options a program accepts. There are two types of help  mes-
       sages 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  mes-
       sages  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 func-
       tions are available:

       #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
       descriptor  f,  while  poptPrintUsage() displays	the shorter usage mes-
       sage. 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
       summarizes 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
	      poptGetNextOpt().

       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
	      follows 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 quo-
	      tation mark).  poptParseArgvString(),  poptReadConfigFile(),  or
	      poptReadDefaultConfig() 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
	      poptReadDefaultConfig() 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   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_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_LONG-
	      LONG, 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(), popt-
	      SaveShort() and poptGetNextOpt().

       POPT_ERROR_NULLARG
	      An  operation  was invoked on a null target arg (including zero-
	      length string arguments).	In the poptBitsArgs() case,  this  in-
	      cludes  an  empty	leftover argv array. This can only be returned
	      by the poptBits*() and  poptSave*()  functions,  poptConfigFile-
	      ToString() 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  de-
	      scribing	the  error, just as with the standard strerror() func-
	      tion.

	      const char * poptBadOption(poptContext con, int flags);
	      If an error occurred during poptGetNextOpt(), this function  re-
	      turns 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  applica-
       tions.  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 occurs during argument parsing, code similar to the fol-
       lowing displays a useful	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 ex-
       panded  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 similarly to	a shell	command, which	allows
       \, ", and ' to be used for quoting. If a	backslash is the final charac-
       ter  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.

       The following entry would add a --text option to	the grep  command,  as
       suggested 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 configu-
	      ration file. This	allows programs	to use	program-specific  con-
	      figuration 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	reserved for future expansion. The new alias is	speci-
	      fied 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 op-
	      tion 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 pro-
       vides a function	that parses a string into an array of  strings,	 using
       rules similar to	normal 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 ex-
       isting argument array.

       The argvPtr created by poptParseArgvString() or poptDupArgv() is	 suit-
       able to pass directly to	poptGetContext().  Both	routines return	a sin-
       gle  dynamically	 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
       application 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
       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.

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  re-
       worked,	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 vari-
       ous 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
       (Addison-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+14.3.quarterly>

home | help