popt.h File Reference

#include <stdio.h>

Include dependency graph for popt.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	poptOption
struct	poptAlias
	A popt alias argument for poptAddAlias(). More...
struct	poptItem_s
	A popt alias or exec argument for poptAddItem(). More...
Defines
#define	POPT_OPTION_DEPTH 10
Arg type identifiers

#define	POPT_ARG_NONE 0U
#define	POPT_ARG_STRING 1U
#define	POPT_ARG_INT 2U
#define	POPT_ARG_LONG 3U
#define	POPT_ARG_INCLUDE_TABLE 4U
#define	POPT_ARG_CALLBACK 5U
#define	POPT_ARG_INTL_DOMAIN 6U
#define	POPT_ARG_VAL 7U
#define	POPT_ARG_FLOAT 8U
#define	POPT_ARG_DOUBLE 9U
#define	POPT_ARG_MAINCALL 10U
#define	POPT_ARG_MASK 0x0000FFFFU
Arg modifiers

#define	POPT_ARGFLAG_ONEDASH 0x80000000U
#define	POPT_ARGFLAG_DOC_HIDDEN 0x40000000U
#define	POPT_ARGFLAG_STRIP 0x20000000U
#define	POPT_ARGFLAG_OPTIONAL 0x10000000U
#define	POPT_ARGFLAG_OR 0x08000000U
#define	POPT_ARGFLAG_NOR 0x09000000U
#define	POPT_ARGFLAG_AND 0x04000000U
#define	POPT_ARGFLAG_NAND 0x05000000U
#define	POPT_ARGFLAG_XOR 0x02000000U
#define	POPT_ARGFLAG_NOT 0x01000000U
#define	POPT_ARGFLAG_LOGICALOPS (POPT_ARGFLAG_OR\|POPT_ARGFLAG_AND\|POPT_ARGFLAG_XOR)
#define	POPT_BIT_SET (POPT_ARG_VAL\|POPT_ARGFLAG_OR)
#define	POPT_BIT_CLR (POPT_ARG_VAL\|POPT_ARGFLAG_NAND)
#define	POPT_ARGFLAG_SHOW_DEFAULT 0x00800000U
#define	POPT_ARGFLAG_RANDOM 0x00400000U
Callback modifiers

#define	POPT_CBFLAG_PRE 0x80000000U
#define	POPT_CBFLAG_POST 0x40000000U
#define	POPT_CBFLAG_INC_DATA 0x20000000U
#define	POPT_CBFLAG_SKIPOPTION 0x10000000U
#define	POPT_CBFLAG_CONTINUE 0x08000000U
Error return values

#define	POPT_ERROR_NOARG -10
#define	POPT_ERROR_BADOPT -11
#define	POPT_ERROR_OPTSTOODEEP -13
#define	POPT_ERROR_BADQUOTE -15
#define	POPT_ERROR_ERRNO -16
#define	POPT_ERROR_BADNUMBER -17
#define	POPT_ERROR_OVERFLOW -18
#define	POPT_ERROR_BADOPERATION -19
#define	POPT_ERROR_NULLARG -20
#define	POPT_ERROR_MALLOC -21
poptBadOption() flags

#define	POPT_BADOPTION_NOALIAS (1U << 0)
poptGetContext() flags

#define	POPT_CONTEXT_NO_EXEC (1U << 0)
#define	POPT_CONTEXT_KEEP_FIRST (1U << 1)
#define	POPT_CONTEXT_POSIXMEHARDER (1U << 2)
#define	POPT_CONTEXT_ARG_OPTS (1U << 4)
Typedefs
typedef struct poptItem_s *	poptItem
	A popt alias or exec argument for poptAddItem().
typedef struct poptContext_s *	poptContext
typedef struct poptOption *	poptOption
typedef void(*	poptCallbackType )(poptContext con, enum poptCallbackReason reason, const struct poptOption opt, const char arg, const void *data)
	Table callback prototype.
Enumerations
enum	poptCallbackReason { POPT_CALLBACK_REASON_PRE = 0, POPT_CALLBACK_REASON_POST = 1, POPT_CALLBACK_REASON_OPTION = 2 }
Functions
poptContext	poptGetContext (const char name, int argc, const char argv, const struct poptOption options, unsigned int flags)
	Initialize popt context.
void	poptResetContext (poptContext con)
	Reinitialize popt context.
int	poptGetNextOpt (poptContext con)
	Return value of next option found.
char *	poptGetOptArg (poptContext con)
	Return next option argument (if any).
const char *	poptGetArg (poptContext con)
	Return next argument.
const char *	poptPeekArg (poptContext con)
	Peek at current argument.
const char **	poptGetArgs (poptContext con)
	Return remaining arguments.
const char *	poptBadOption (poptContext con, unsigned int flags)
	Return the option which caused the most recent error.
poptContext	poptFreeContext (poptContext con)
	Destroy context.
int	poptStuffArgs (poptContext con, const char **argv)
	Add arguments to context.
int	poptAddAlias (poptContext con, struct poptAlias alias, int flags)
	Add alias to context.
int	poptAddItem (poptContext con, poptItem newItem, int flags)
	Add alias/exec item to context.
int	poptReadConfigFile (poptContext con, const char *fn)
	Read configuration file.
int	poptReadDefaultConfig (poptContext con, int useEnv)
	Read default configuration from /etc/popt and $HOME/.popt.
int	poptDupArgv (int argc, const char *argv, int argcPtr, const char ***argvPtr)
	Duplicate an argument array.
int	poptParseArgvString (const char s, int argcPtr, const char ***argvPtr)
	Parse a string into an argument array.
int	poptConfigFileToString (FILE fp, char *argstrp, int flags)
	Parses an input configuration file and returns an string that is a command line.
const char *	poptStrerror (const int error)
	Return formatted error string for popt failure.
void	poptSetExecPath (poptContext con, const char *path, int allowAbsolute)
	Limit search for executables.
void	poptPrintHelp (poptContext con, FILE *fp, int flags)
	Print detailed description of options.
void	poptPrintUsage (poptContext con, FILE *fp, int flags)
	Print terse description of options.
void	poptSetOtherOptionHelp (poptContext con, const char *text)
	Provide text to replace default "[OPTION...]" in help/usage output.
const char *	poptGetInvocationName (poptContext con)
	Return argv[0] from context.
int	poptStrippedArgv (poptContext con, int argc, char **argv)
	Shuffle argv pointers to remove stripped args, returns new argc.
int	poptSaveLong (long *arg, unsigned int argInfo, long aLong)
	Save a long, performing logical operation with value.
int	poptSaveInt (int *arg, unsigned int argInfo, long aLong)
	Save an integer, performing logical operation with value.
Auto-generated help/usage

#define	POPT_AUTOALIAS
#define	POPT_AUTOHELP
#define	POPT_TABLEEND { NULL, '\0', 0, NULL, 0, NULL, NULL }
struct poptOption	poptAliasOptions []
	Empty table marker to enable displaying popt alias/exec options.
struct poptOption	poptHelpOptions []
	Auto help table options.
struct poptOption *	poptHelpOptionsI18N

Define Documentation

#define POPT_ARG_CALLBACK 5U

table-wide callback... must be set first in table; arg points to callback, descrip points to callback data to pass

Definition at line 25 of file popt.h.

Referenced by findOption(), invokeCallbacksOPTION(), invokeCallbacksPOST(), and invokeCallbacksPRE().

#define POPT_ARG_DOUBLE 9U

arg will be converted to double

Definition at line 35 of file popt.h.

Referenced by getArgDescrip(), poptGetNextOpt(), singleOptionDefaultValue(), and singleOptionHelp().

#define POPT_ARG_FLOAT 8U

arg will be converted to float

Definition at line 34 of file popt.h.

Referenced by getArgDescrip(), poptGetNextOpt(), singleOptionDefaultValue(), and singleOptionHelp().

#define POPT_ARG_INCLUDE_TABLE 4U

arg points to table

Definition at line 24 of file popt.h.

Referenced by findOption(), invokeCallbacksOPTION(), invokeCallbacksPOST(), invokeCallbacksPRE(), maxArgWidth(), showShortOptions(), singleTableHelp(), and singleTableUsage().

#define POPT_ARG_INT 2U

arg will be converted to int

Definition at line 22 of file popt.h.

Referenced by getArgDescrip(), poptGetNextOpt(), singleOptionDefaultValue(), and singleOptionHelp().

#define POPT_ARG_INTL_DOMAIN 6U

set the translation domain for this table and any included tables; arg points to the domain string

Definition at line 29 of file popt.h.

Referenced by getTableTranslationDomain(), itemUsage(), and singleTableUsage().

#define POPT_ARG_LONG 3U

arg will be converted to long

Definition at line 23 of file popt.h.

Referenced by getArgDescrip(), poptGetNextOpt(), singleOptionDefaultValue(), and singleOptionHelp().

#define POPT_ARG_MAINCALL 10U

return (*arg) (argc, argv)

Definition at line 37 of file popt.h.

Referenced by getArgDescrip(), poptGetNextOpt(), singleOptionDefaultValue(), and singleOptionHelp().

#define POPT_ARG_MASK 0x0000FFFFU

Definition at line 39 of file popt.h.

Referenced by findOption(), getArgDescrip(), invokeCallbacksOPTION(), invokeCallbacksPOST(), invokeCallbacksPRE(), itemUsage(), maxArgWidth(), poptGetNextOpt(), showShortOptions(), singleOptionDefaultValue(), singleOptionHelp(), singleTableHelp(), and singleTableUsage().

#define POPT_ARG_NONE 0U

no arg

Definition at line 20 of file popt.h.

Referenced by getArgDescrip(), poptGetNextOpt(), singleOptionDefaultValue(), and singleOptionHelp().

#define POPT_ARG_STRING 1U

arg will be saved as string

Definition at line 21 of file popt.h.

Referenced by configLine(), getArgDescrip(), poptGetNextOpt(), singleOptionDefaultValue(), and singleOptionHelp().

#define POPT_ARG_VAL 7U

arg should take value val

Definition at line 33 of file popt.h.

Referenced by getArgDescrip(), poptGetNextOpt(), singleOptionDefaultValue(), and singleOptionHelp().

#define POPT_ARGFLAG_AND 0x04000000U

arg will be and'ed

Definition at line 53 of file popt.h.

Referenced by poptSaveInt(), poptSaveLong(), and singleOptionHelp().

#define POPT_ARGFLAG_DOC_HIDDEN 0x40000000U

don't show in help/usage

Definition at line 47 of file popt.h.

Referenced by configLine(), itemHelp(), itemUsage(), maxArgWidth(), poptAddAlias(), singleTableHelp(), and singleTableUsage().

#define POPT_ARGFLAG_LOGICALOPS (POPT_ARGFLAG_OR|POPT_ARGFLAG_AND|POPT_ARGFLAG_XOR)

Definition at line 57 of file popt.h.

Referenced by poptSaveInt(), poptSaveLong(), and singleOptionHelp().

#define POPT_ARGFLAG_NAND 0x05000000U

arg will be nand'ed

Definition at line 54 of file popt.h.

#define POPT_ARGFLAG_NOR 0x09000000U

arg will be nor'ed

Definition at line 52 of file popt.h.

#define POPT_ARGFLAG_NOT 0x01000000U

arg will be negated

Definition at line 56 of file popt.h.

Referenced by poptSaveInt(), poptSaveLong(), and singleOptionHelp().

#define POPT_ARGFLAG_ONEDASH 0x80000000U

allow -longoption

Definition at line 46 of file popt.h.

Referenced by findOption(), maxArgWidth(), poptGetNextOpt(), singleOptionHelp(), and singleOptionUsage().

#define POPT_ARGFLAG_OPTIONAL 0x10000000U

arg may be missing

Definition at line 49 of file popt.h.

Referenced by maxArgWidth(), poptGetNextOpt(), and singleOptionHelp().

#define POPT_ARGFLAG_OR 0x08000000U

arg will be or'ed

Definition at line 51 of file popt.h.

Referenced by poptSaveInt(), poptSaveLong(), and singleOptionHelp().

#define POPT_ARGFLAG_RANDOM 0x00400000U

Definition at line 66 of file popt.h.

Referenced by poptSaveInt(), and poptSaveLong().

#define POPT_ARGFLAG_SHOW_DEFAULT 0x00800000U

show default value in --help

Definition at line 65 of file popt.h.

Referenced by singleOptionHelp().

#define POPT_ARGFLAG_STRIP 0x20000000U

strip this arg from argv(only applies to long args)

Definition at line 48 of file popt.h.

Referenced by poptGetNextOpt().

#define POPT_ARGFLAG_XOR 0x02000000U

arg will be xor'ed

Definition at line 55 of file popt.h.

Referenced by poptSaveInt(), poptSaveLong(), and singleOptionHelp().

#define POPT_AUTOALIAS

Value:

{ NULL, '\0', POPT_ARG_INCLUDE_TABLE, poptAliasOptions, \
                        0, "Options implemented via popt alias/exec:", NULL },

Definition at line 167 of file popt.h.

#define POPT_AUTOHELP

Value:

{ NULL, '\0', POPT_ARG_INCLUDE_TABLE, poptHelpOptions, \
                        0, "Help options:", NULL },

Definition at line 183 of file popt.h.

#define POPT_BADOPTION_NOALIAS (1U << 0)

don't go into an alias

Definition at line 102 of file popt.h.

Referenced by poptBadOption().

#define POPT_BIT_CLR (POPT_ARG_VAL|POPT_ARGFLAG_NAND)

clear arg bit(s)

Definition at line 62 of file popt.h.

#define POPT_BIT_SET (POPT_ARG_VAL|POPT_ARGFLAG_OR)

set arg bit(s)

Definition at line 60 of file popt.h.

#define POPT_CBFLAG_CONTINUE 0x08000000U

continue callbacks with option

Definition at line 79 of file popt.h.

Referenced by invokeCallbacksOPTION().

#define POPT_CBFLAG_INC_DATA 0x20000000U

use data from the include line, not the subtable

Definition at line 76 of file popt.h.

Referenced by findOption().

#define POPT_CBFLAG_POST 0x40000000U

call the callback after parse

Definition at line 75 of file popt.h.

Referenced by invokeCallbacksPOST().

#define POPT_CBFLAG_PRE 0x80000000U

call the callback before parse

Definition at line 74 of file popt.h.

Referenced by invokeCallbacksPRE().

#define POPT_CBFLAG_SKIPOPTION 0x10000000U

don't callback with option

Definition at line 78 of file popt.h.

Referenced by invokeCallbacksOPTION().

#define POPT_CONTEXT_ARG_OPTS (1U << 4)

return args as options with value 0

Definition at line 112 of file popt.h.

Referenced by poptGetNextOpt().

#define POPT_CONTEXT_KEEP_FIRST (1U << 1)

pay attention to argv[0]

Definition at line 110 of file popt.h.

Referenced by poptGetContext(), and showHelpIntro().

#define POPT_CONTEXT_NO_EXEC (1U << 0)

ignore exec expansions

Definition at line 109 of file popt.h.

Referenced by handleExec().

#define POPT_CONTEXT_POSIXMEHARDER (1U << 2)

options can't follow args

Definition at line 111 of file popt.h.

Referenced by poptGetContext(), and poptGetNextOpt().

#define POPT_ERROR_BADNUMBER -17

invalid numeric value

Definition at line 91 of file popt.h.

Referenced by poptGetNextOpt(), and poptStrerror().

#define POPT_ERROR_BADOPERATION -19

mutually exclusive logical operations requested

Definition at line 93 of file popt.h.

Referenced by poptGetNextOpt(), poptSaveInt(), poptSaveLong(), and poptStrerror().

#define POPT_ERROR_BADOPT -11

unknown option

Definition at line 87 of file popt.h.

Referenced by poptGetNextOpt(), and poptStrerror().

#define POPT_ERROR_BADQUOTE -15

error in paramter quoting

Definition at line 89 of file popt.h.

Referenced by poptParseArgvString(), and poptStrerror().

#define POPT_ERROR_ERRNO -16

errno set, use strerror(errno)

Definition at line 90 of file popt.h.

Referenced by execCommand(), poptReadConfigFile(), poptReadDefaultConfig(), and poptStrerror().

#define POPT_ERROR_MALLOC -21

memory allocation failed

Definition at line 95 of file popt.h.

Referenced by execCommand(), poptConfigFileToString(), poptDupArgv(), poptParseArgvString(), and poptStrerror().

#define POPT_ERROR_NOARG -10

missing argument

Definition at line 86 of file popt.h.

Referenced by execCommand(), poptDupArgv(), poptGetNextOpt(), and poptStrerror().

#define POPT_ERROR_NULLARG -20

opt->arg should not be NULL

Definition at line 94 of file popt.h.

Referenced by poptConfigFileToString(), poptSaveInt(), poptSaveLong(), and poptStrerror().

#define POPT_ERROR_OPTSTOODEEP -13

aliases nested too deeply

Definition at line 88 of file popt.h.

Referenced by handleAlias(), poptStrerror(), and poptStuffArgs().

#define POPT_ERROR_OVERFLOW -18

number too large or too small

Definition at line 92 of file popt.h.

Referenced by poptConfigFileToString(), poptGetNextOpt(), and poptStrerror().

#define POPT_OPTION_DEPTH 10

Definition at line 14 of file popt.h.

Referenced by handleAlias(), and poptStuffArgs().

#define POPT_TABLEEND { NULL, '\0', 0, NULL, 0, NULL, NULL }

Definition at line 186 of file popt.h.

Typedef Documentation

typedef void(* poptCallbackType)(poptContext con, enum poptCallbackReason reason,const struct poptOption *opt,const char *arg,const void *data)

Table callback prototype.

Parameters:

	con	context
	reason	reason for callback
	opt	option that triggered callback
	arg

Todo:: Document.

Parameters:

data

Todo:: Document.

Definition at line 226 of file popt.h.

typedef struct poptContext_s* poptContext

Definition at line 192 of file popt.h.

typedef struct poptItem_s * poptItem

A popt alias or exec argument for poptAddItem().

typedef struct poptOption* poptOption

Definition at line 199 of file popt.h.

Enumeration Type Documentation

enum poptCallbackReason

Enumerator:

POPT_CALLBACK_REASON_PRE
POPT_CALLBACK_REASON_POST
POPT_CALLBACK_REASON_OPTION

Definition at line 206 of file popt.h.

Function Documentation

int poptAddAlias	(	poptContext	con,
		struct poptAlias	alias,
		int	flags
	)

Add alias to context.

Todo:: Pass alias by reference, not value.

Deprecated:: Use poptAddItem instead.

Parameters:

	con	context
	alias	alias to add
	flags	(unused)

Returns:: 0 on success

< don't show in help/usage

Definition at line 1112 of file popt.c.

References poptAlias::argc, poptAlias::argv, poptAlias::longName, POPT_ARGFLAG_DOC_HIDDEN, poptAddItem(), and poptAlias::shortName.

int poptAddItem	(	poptContext	con,
		poptItem	newItem,
		int	flags
	)

Add alias/exec item to context.

Parameters:

	con	context
	newItem	alias/exec item to add
	flags	0 for alias, 1 for exec

Returns:: 0 on success

Definition at line 1130 of file popt.c.

References poptContext_s::aliases, poptOption::arg, poptItem_s::argc, poptOption::argDescrip, poptOption::argInfo, poptItem_s::argv, poptOption::descrip, poptContext_s::execs, poptOption::longName, poptContext_s::numAliases, poptContext_s::numExecs, poptItem_s::option, realloc(), poptOption::shortName, poptOption::val, and xstrdup.

Referenced by configLine(), and poptAddAlias().

const char* poptBadOption	(	poptContext	con,
		unsigned int	flags
	)

Return the option which caused the most recent error.

Parameters:

	con	context
	flags

Returns:: offending option

< don't go into an alias

Definition at line 1173 of file popt.c.

References optionStackEntry::argv, optionStackEntry::next, poptContext_s::optionStack, poptContext_s::os, and POPT_BADOPTION_NOALIAS.

int poptConfigFileToString	(	FILE *	fp,
		char **	argstrp,
		int	flags
	)

Parses an input configuration file and returns an string that is a command line.

For use with popt. You must free the return value when done.

Given the file:

# this line is ignored
    #   this one too
aaa
  bbb
    ccc   
bla=bla

this_is   =   fdsafdas
     bad_line=        
  reall bad line  
  reall bad line  = again
5555=   55555   
  test = with lots of spaces

The result is:

--aaa --bbb --ccc --bla="bla" --this_is="fdsafdas" --5555="55555" --test="with lots of spaces"

Passing this to poptParseArgvString() yields an argv of:

'--aaa'
'--bbb' 
'--ccc' 
'--bla=bla' 
'--this_is=fdsafdas' 
'--5555=55555' 
'--test=with lots of spaces'

Bug:

NULL is returned if file line is too long.

Silently ignores invalid lines.

Parameters:

	fp	file handle to read
	*argstrp	return string of options (malloc'd)
	flags	unused

Returns:: 0 on success

See also:: poptParseArgvString

< opt->arg should not be NULL

< memory allocation failed

< number too large or too small

< memory allocation failed

Definition at line 129 of file poptparse.c.

References _isspaceptr, calloc(), POPT_ERROR_MALLOC, POPT_ERROR_NULLARG, POPT_ERROR_OVERFLOW, and realloc().

int poptDupArgv	(	int	argc,
		const char **	argv,
		int *	argcPtr,
		const char ***	argvPtr
	)

Duplicate an argument array.

Note:: : The argument array is malloc'd as a single area, so only argv must be free'd.

Parameters:

	argc	no. of arguments
	argv	argument array

Return values:

	argcPtr	address of returned no. of arguments
	argvPtr	address of returned argument array

Returns:: 0 on success, POPT_ERROR_NOARG on failure

< missing argument

< memory allocation failed

Definition at line 13 of file poptparse.c.

References malloc(), POPT_ERROR_MALLOC, and POPT_ERROR_NOARG.

Referenced by handleAlias(), poptParseArgvString(), and poptStuffArgs().

poptContext poptFreeContext ( poptContext con )

Destroy context.

Parameters:

con

context

Returns:: NULL always

Definition at line 1068 of file popt.c.

References _free(), poptContext_s::aliases, poptContext_s::appName, poptContext_s::arg_strip, optionStackEntry::argb, poptOption::argDescrip, poptItem_s::argv, poptOption::descrip, poptContext_s::execPath, poptContext_s::execs, poptContext_s::finalArgv, poptContext_s::leftovers, poptOption::longName, poptContext_s::numAliases, poptContext_s::numExecs, poptItem_s::option, poptContext_s::os, poptContext_s::otherHelp, PBM_FREE, and poptResetContext().

Referenced by displayArgs().

const char* poptGetArg ( poptContext con )

Return next argument.

Parameters:

con

context

Returns:: next argument, NULL if no argument is available

Definition at line 1038 of file popt.c.

References poptContext_s::leftovers, poptContext_s::nextLeftover, and poptContext_s::numLeftovers.

const char** poptGetArgs ( poptContext con )

Return remaining arguments.

Parameters:

con

context

Returns:: argument array, NULL terminated

Definition at line 1054 of file popt.c.

References poptContext_s::leftovers, poptContext_s::nextLeftover, and poptContext_s::numLeftovers.

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

Initialize popt context.

Parameters:

	name	context name (usually argv[0] program name)
	argc	no. of arguments
	argv	argument array
	options	address of popt option table
	flags	or'd POPT_CONTEXT_* bits

Returns:: initialized popt context

< pay attention to argv[0]

< options can't follow args

Definition at line 162 of file popt.c.

References poptContext_s::aliases, poptContext_s::appName, poptContext_s::arg_strip, optionStackEntry::argb, optionStackEntry::argc, optionStackEntry::argv, calloc(), poptContext_s::execAbsolute, poptContext_s::execs, poptContext_s::finalArgv, poptContext_s::finalArgvAlloced, poptContext_s::flags, invokeCallbacksPRE(), poptContext_s::leftovers, malloc(), optionStackEntry::next, poptContext_s::numAliases, poptContext_s::numExecs, poptContext_s::options, poptContext_s::optionStack, poptContext_s::os, POPT_CONTEXT_KEEP_FIRST, and POPT_CONTEXT_POSIXMEHARDER.

const char* poptGetInvocationName ( poptContext con )

Return argv[0] from context.

Parameters:

con

context

Returns:: argv[0]

Definition at line 1234 of file popt.c.

References optionStackEntry::argv, and poptContext_s::os.

int poptGetNextOpt ( poptContext con )

Return value of next option found.

Parameters:

con

context

Returns:: next option val, -1 on last item, POPT_ERROR_* on error

< unknown option

< options can't follow args

< return args as options with value 0

< unknown option

< strip this arg from argv(only applies to long args)

< unknown option

< no arg

< mutually exclusive logical operations requested

< arg should take value val

< mutually exclusive logical operations requested

< no arg

< arg may be missing

< missing argument

< strip this arg from argv(only applies to long args)

< arg may be missing

< arg will be saved as string

< arg will be converted to int

< arg will be converted to long

< invalid numeric value

< arg will be converted to long

< number too large or too small

< mutually exclusive logical operations requested

< number too large or too small

< mutually exclusive logical operations requested

< arg will be converted to float

< arg will be converted to double

< number too large or too small

< invalid numeric value

< arg will be converted to double

< number too large or too small

< return (*arg) (argc, argv)

< arg should take value val

< allow -longoption

< no arg

< arg should take value val

< no arg

Definition at line 713 of file popt.c.

References _ABS, _free(), poptOption::arg, optionStackEntry::argb, optionStackEntry::argc, poptOption::argInfo, optionStackEntry::argv, cleanOSE(), poptContext_s::doExec, execCommand(), expandNextArg(), poptContext_s::finalArgv, poptContext_s::finalArgvAlloced, poptContext_s::finalArgvCount, findOption(), poptContext_s::flags, handleAlias(), handleExec(), invokeCallbacksOPTION(), invokeCallbacksPOST(), poptContext_s::leftovers, poptOption::longName, poptContext_s::maincall, malloc(), optionStackEntry::next, optionStackEntry::nextArg, optionStackEntry::nextCharArg, poptContext_s::numLeftovers, poptContext_s::options, poptContext_s::optionStack, poptContext_s::os, PBM_ISSET, POPT_, POPT_ARG_DOUBLE, POPT_ARG_FLOAT, POPT_ARG_INT, POPT_ARG_LONG, POPT_ARG_MAINCALL, POPT_ARG_MASK, POPT_ARG_NONE, POPT_ARG_STRING, POPT_ARG_VAL, POPT_ARGFLAG_ONEDASH, POPT_ARGFLAG_OPTIONAL, POPT_ARGFLAG_STRIP, POPT_CONTEXT_ARG_OPTS, POPT_CONTEXT_POSIXMEHARDER, POPT_ERROR_BADNUMBER, POPT_ERROR_BADOPERATION, POPT_ERROR_BADOPT, POPT_ERROR_NOARG, POPT_ERROR_OVERFLOW, poptSaveInt(), poptSaveLong(), poptStripArg(), realloc(), poptContext_s::restLeftover, poptOption::shortName, poptOption::val, and xstrdup.

char* poptGetOptArg ( poptContext con )

Return next option argument (if any).

Parameters:

con

context

Returns:: option argument, NULL if no argument is available

Definition at line 1028 of file popt.c.

References optionStackEntry::nextArg, and poptContext_s::os.

int poptParseArgvString	(	const char *	s,
		int *	argcPtr,
		const char ***	argvPtr
	)

Parse a string into an argument array.

The parse allows ', ", and \ quoting, but ' is treated the same as " and both may include \ quotes.

Note:: : The argument array is malloc'd as a single area, so only argv must be free'd.

Parameters:

s

string to parse

Return values:

	argcPtr	address of returned no. of arguments
	argvPtr	address of returned argument array

< memory allocation failed

< error in paramter quoting

Definition at line 52 of file poptparse.c.

References _isspaceptr, calloc(), malloc(), POPT_ARGV_ARRAY_GROW_DELTA, POPT_ERROR_BADQUOTE, POPT_ERROR_MALLOC, poptDupArgv(), and realloc().

Referenced by configLine().

const char* poptPeekArg ( poptContext con )

Peek at current argument.

Parameters:

con

context

Returns:: current argument, NULL if no argument is available

Definition at line 1046 of file popt.c.

References poptContext_s::leftovers, poptContext_s::nextLeftover, and poptContext_s::numLeftovers.

void poptPrintHelp	(	poptContext	con,
		FILE *	fp,
		int	flags
	)

Print detailed description of options.

Parameters:

	con	context
	fp	ouput file handle
	flags	(unused)

Definition at line 610 of file popthelp.c.

References calloc(), columns_s::cur, columns_s::max, maxArgWidth(), maxColumnWidth(), poptContext_s::options, poptContext_s::otherHelp, POPT_, showHelpIntro(), and singleTableHelp().

Referenced by displayArgs().

void poptPrintUsage	(	poptContext	con,
		FILE *	fp,
		int	flags
	)

Print terse description of options.

Parameters:

	con	context
	fp	ouput file handle
	flags	(unused)

Definition at line 837 of file popthelp.c.

References poptContext_s::aliases, calloc(), columns_s::cur, poptContext_s::execs, itemUsage(), columns_s::max, maxColumnWidth(), poptContext_s::numAliases, poptContext_s::numExecs, poptContext_s::options, poptContext_s::otherHelp, showHelpIntro(), showShortOptions(), and singleTableUsage().

Referenced by displayArgs().

int poptReadConfigFile	(	poptContext	con,
		const char *	fn
	)

Read configuration file.

Parameters:

	con	context
	fn	file name to read

Returns:: 0 on success, POPT_ERROR_ERRNO on failure

< errno set, use strerror(errno)

Definition at line 97 of file poptconfig.c.

References _isspaceptr, configLine(), malloc(), and POPT_ERROR_ERRNO.

Referenced by poptReadDefaultConfig().

int poptReadDefaultConfig	(	poptContext	con,
		int	useEnv
	)

Read default configuration from /etc/popt and $HOME/.popt.

Parameters:

	con	context
	useEnv	(unused)

Returns:: 0 on success, POPT_ERROR_ERRNO on failure

< errno set, use strerror(errno)

Definition at line 171 of file poptconfig.c.

References poptContext_s::appName, malloc(), POPT_ERROR_ERRNO, and poptReadConfigFile().

void poptResetContext ( poptContext con )

Reinitialize popt context.

Parameters:

con

context

Definition at line 219 of file popt.c.

References _free(), poptContext_s::arg_strip, optionStackEntry::argb, cleanOSE(), optionStackEntry::currAlias, poptContext_s::doExec, poptContext_s::finalArgv, poptContext_s::finalArgvCount, optionStackEntry::next, optionStackEntry::nextArg, optionStackEntry::nextCharArg, poptContext_s::nextLeftover, poptContext_s::numLeftovers, poptContext_s::optionStack, poptContext_s::os, PBM_FREE, and poptContext_s::restLeftover.

Referenced by poptFreeContext().

int poptSaveInt	(	int *	arg,
		unsigned int	argInfo,
		long	aLong
	)

Save an integer, performing logical operation with value.

Warning:: Alignment check may be too strict on certain platorms.

Parameters:

	arg	integer pointer, aligned on int boundary.
	argInfo	logical operation (see POPT_ARGFLAG_*)
	aLong	value to use

Returns:: 0 on success, POPT_ERROR_NULLARG/POPT_ERROR_BADOPERATION

< opt->arg should not be NULL

< arg will be negated

< arg will be or'ed

< arg will be and'ed

< arg will be xor'ed

< arg will be or'ed

< arg will be and'ed

< arg will be xor'ed

< mutually exclusive logical operations requested

Definition at line 675 of file popt.c.

References POPT_ARGFLAG_AND, POPT_ARGFLAG_LOGICALOPS, POPT_ARGFLAG_NOT, POPT_ARGFLAG_OR, POPT_ARGFLAG_RANDOM, POPT_ARGFLAG_XOR, POPT_ERROR_BADOPERATION, and POPT_ERROR_NULLARG.

Referenced by poptGetNextOpt().

int poptSaveLong	(	long *	arg,
		unsigned int	argInfo,
		long	aLong
	)

Save a long, performing logical operation with value.

Warning:: Alignment check may be too strict on certain platorms.

Parameters:

	arg	integer pointer, aligned on int boundary.
	argInfo	logical operation (see POPT_ARGFLAG_*)
	aLong	value to use

Returns:: 0 on success, POPT_ERROR_NULLARG/POPT_ERROR_BADOPERATION

< opt->arg should not be NULL

< arg will be negated

< arg will be or'ed

< arg will be and'ed

< arg will be xor'ed

< arg will be or'ed

< arg will be and'ed

< arg will be xor'ed

< mutually exclusive logical operations requested

Definition at line 637 of file popt.c.

References POPT_ARGFLAG_AND, POPT_ARGFLAG_LOGICALOPS, POPT_ARGFLAG_NOT, POPT_ARGFLAG_OR, POPT_ARGFLAG_RANDOM, POPT_ARGFLAG_XOR, POPT_ERROR_BADOPERATION, and POPT_ERROR_NULLARG.

Referenced by poptGetNextOpt().

void poptSetExecPath	(	poptContext	con,
		const char *	path,
		int	allowAbsolute
	)

Limit search for executables.

Parameters:

	con	context
	path	single path to search for executables
	allowAbsolute	absolute paths only?

Definition at line 54 of file popt.c.

References _free(), poptContext_s::execAbsolute, poptContext_s::execPath, and xstrdup.

void poptSetOtherOptionHelp	(	poptContext	con,
		const char *	text
	)

Provide text to replace default "[OPTION...]" in help/usage output.

Parameters:

	con	context
	text	replacement text

Definition at line 874 of file popthelp.c.

References _free(), poptContext_s::otherHelp, and xstrdup.

const char* poptStrerror ( const int error )

Return formatted error string for popt failure.

Parameters:

error

popt error

Returns:: error string

< missing argument

< unknown option

< mutually exclusive logical operations requested

< opt->arg should not be NULL

< aliases nested too deeply

< error in paramter quoting

< invalid numeric value

< number too large or too small

< memory allocation failed

< errno set, use strerror(errno)

Definition at line 1183 of file popt.c.

References POPT_, POPT_ERROR_BADNUMBER, POPT_ERROR_BADOPERATION, POPT_ERROR_BADOPT, POPT_ERROR_BADQUOTE, POPT_ERROR_ERRNO, POPT_ERROR_MALLOC, POPT_ERROR_NOARG, POPT_ERROR_NULLARG, POPT_ERROR_OPTSTOODEEP, POPT_ERROR_OVERFLOW, and strerror().

int poptStrippedArgv	(	poptContext	con,
		int	argc,
		char **	argv
	)

Shuffle argv pointers to remove stripped args, returns new argc.

Parameters:

	con	context
	argc	no. of args
	argv	arg vector

Returns:: new argc

Definition at line 1239 of file popt.c.

References poptContext_s::arg_strip, and PBM_ISSET.

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

Add arguments to context.

Parameters:

	con	context
	argv	argument array, NULL terminated

Returns:: 0 on success, POPT_ERROR_OPTSTOODEEP on failure

< aliases nested too deeply

Definition at line 1211 of file popt.c.

References optionStackEntry::argb, optionStackEntry::argc, optionStackEntry::argv, optionStackEntry::currAlias, optionStackEntry::next, optionStackEntry::nextArg, optionStackEntry::nextCharArg, poptContext_s::optionStack, poptContext_s::os, POPT_ERROR_OPTSTOODEEP, POPT_OPTION_DEPTH, poptDupArgv(), and optionStackEntry::stuffed.

Variable Documentation

struct poptOption poptAliasOptions[]

Empty table marker to enable displaying popt alias/exec options.

Definition at line 63 of file popthelp.c.

struct poptOption poptHelpOptions[]

Auto help table options.

Definition at line 72 of file popthelp.c.

Referenced by findOption(), invokeCallbacksOPTION(), invokeCallbacksPOST(), and invokeCallbacksPRE().

struct poptOption* poptHelpOptionsI18N

Definition at line 95 of file popthelp.c.

Referenced by findOption(), invokeCallbacksOPTION(), invokeCallbacksPOST(), and invokeCallbacksPRE().

popt.h File Reference

Data Structures

Defines

Typedefs

Enumerations

Functions

Auto-generated help/usage

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation