POPT.

Files
file	findme.c
file	findme.h
file	popt.c
file	popt.h
file	poptconfig.c
file	popthelp.c
file	poptint.h
file	poptparse.c
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...
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.
Functions
poptContext	poptGetContext (const char *name, int argc, const char **argv, const struct poptOption *options, int flags)
	Initialize popt context.
void	poptResetContext (poptContext con)
	Reinitialize popt context.
int	poptGetNextOpt (poptContext con)
	Return value of next option found.
const char *	poptGetOptArg (poptContext con)
	Return next option argument (if any).
const char *	poptGetArg (poptContext con)
	Return current option's argument.
const char *	poptPeekArg (poptContext con)
	Peek at current option's argument.
const char **	poptGetArgs (poptContext con)
	Return remaining arguments.
const char *	poptBadOption (poptContext con, 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.
const char *const	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.

---

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 196 of file popt.h.

typedef struct poptContext_s* poptContext

Definition at line 169 of file popt.h.

typedef struct poptItem_s * poptItem

A popt alias or exec argument for poptAddItem().

typedef struct poptOption* poptOption

Definition at line 175 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 1067 of file popt.c.

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

Add alias/exec item to context.

Parameters:

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

Returns:

0 on success

Definition at line 1085 of file popt.c.

const char* poptBadOption	(	poptContext	con,
		int	flags
	)

Return the option which caused the most recent error.

Parameters:

con

context

Returns:

offending option

< don't go into an alias

Definition at line 1129 of file popt.c.

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

< missing argument

< memory allocation failed

Definition at line 13 of file poptparse.c.

poptContext poptFreeContext

(

poptContext

con

)

Destroy context.

Parameters:

con

context

Returns:

NULL always

Definition at line 1023 of file popt.c.

const char* poptGetArg

(

poptContext

con

)

Return current option's argument.

Parameters:

con

context

Returns:

option argument, NULL if no more options are available

Definition at line 993 of file popt.c.

const char** poptGetArgs

(

poptContext

con

)

Return remaining arguments.

Parameters:

con

context

Returns:

argument array, terminated with NULL

Definition at line 1009 of file popt.c.

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

Initialize popt context.

Parameters:

	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 157 of file popt.c.

const char* poptGetInvocationName

(

poptContext

con

)

Return argv[0] from context.

Parameters:

con

context

Returns:

argv[0]

Definition at line 1192 of file popt.c.

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

< unknown option

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

< unknown option

< 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 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

< number too large or too small

< arg should take value val

< allow -longoption

< no arg

< arg should take value val

< no arg

Definition at line 672 of file popt.c.

const char* poptGetOptArg

(

poptContext

con

)

Return next option argument (if any).

Parameters:

con

context

Returns:

option argument, NULL if no more options are available

Definition at line 981 of file popt.c.

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

< error in paramter quoting

Definition at line 54 of file poptparse.c.

const char* poptPeekArg

(

poptContext

con

)

Peek at current option's argument.

Parameters:

con

context

Returns:

option argument

Definition at line 1001 of file popt.c.

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 479 of file popthelp.c.

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 644 of file popthelp.c.

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)

< errno set, use strerror(errno)

< errno set, use strerror(errno)

< errno set, use strerror(errno)

Definition at line 93 of file poptconfig.c.

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

Definition at line 162 of file poptconfig.c.

void poptResetContext

(

poptContext

con

)

Reinitialize popt context.

Parameters:

con

context

Definition at line 214 of file popt.c.

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 47 of file popt.c.

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 663 of file popthelp.c.

const char* const 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 1141 of file popt.c.

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 1197 of file popt.c.

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 1169 of file popt.c.