[rsync/rsync.git] / popt / popt.h

/** \file popt/popt.h
 * \ingroup popt
 */

/* (C) 1998-2000 Red Hat, Inc. -- Licensing details are in the COPYING
   file accompanying popt source distributions, available from 
   ftp://ftp.rpm.org/pub/rpm/dist. */

#ifndef H_POPT
#define H_POPT

#include <stdio.h>			/* for FILE * */

#define POPT_OPTION_DEPTH	10

/** \ingroup popt
 * \name Arg type identifiers
 */
/*@{*/
#define POPT_ARG_NONE		0	/*!< no arg */
#define POPT_ARG_STRING		1	/*!< arg will be saved as string */
#define POPT_ARG_INT		2	/*!< arg will be converted to int */
#define POPT_ARG_LONG		3	/*!< arg will be converted to long */
#define POPT_ARG_INCLUDE_TABLE	4	/*!< arg points to table */
#define POPT_ARG_CALLBACK	5	/*!< table-wide callback... must be
					   set first in table; arg points 
					   to callback, descrip points to 
					   callback data to pass */
#define POPT_ARG_INTL_DOMAIN    6       /*!< set the translation domain
					   for this table and any
					   included tables; arg points
					   to the domain string */
#define POPT_ARG_VAL		7	/*!< arg should take value val */
#define	POPT_ARG_FLOAT		8	/*!< arg will be converted to float */
#define	POPT_ARG_DOUBLE		9	/*!< arg will be converted to double */

#define POPT_ARG_MASK		0x0000FFFF
/*@}*/

/** \ingroup popt
 * \name Arg modifiers
 */
/*@{*/
#define POPT_ARGFLAG_ONEDASH	0x80000000  /*!< allow -longoption */
#define POPT_ARGFLAG_DOC_HIDDEN 0x40000000  /*!< don't show in help/usage */
#define POPT_ARGFLAG_STRIP	0x20000000  /*!< strip this arg from argv(only applies to long args) */
#define	POPT_ARGFLAG_OPTIONAL	0x10000000  /*!< arg may be missing */

#define	POPT_ARGFLAG_OR		0x08000000  /*!< arg will be or'ed */
#define	POPT_ARGFLAG_NOR	0x09000000  /*!< arg will be nor'ed */
#define	POPT_ARGFLAG_AND	0x04000000  /*!< arg will be and'ed */
#define	POPT_ARGFLAG_NAND	0x05000000  /*!< arg will be nand'ed */
#define	POPT_ARGFLAG_XOR	0x02000000  /*!< arg will be xor'ed */
#define	POPT_ARGFLAG_NOT	0x01000000  /*!< arg will be negated */
#define POPT_ARGFLAG_LOGICALOPS \
        (POPT_ARGFLAG_OR|POPT_ARGFLAG_AND|POPT_ARGFLAG_XOR)

#define	POPT_BIT_SET	(POPT_ARG_VAL|POPT_ARGFLAG_OR)
					/*!< set arg bit(s) */
#define	POPT_BIT_CLR	(POPT_ARG_VAL|POPT_ARGFLAG_NAND)
					/*!< clear arg bit(s) */

#define	POPT_ARGFLAG_SHOW_DEFAULT 0x00800000 /*!< show default value in --help */

/*@}*/

/** \ingroup popt
 * \name Callback modifiers
 */
/*@{*/
#define POPT_CBFLAG_PRE		0x80000000  /*!< call the callback before parse */
#define POPT_CBFLAG_POST	0x40000000  /*!< call the callback after parse */
#define POPT_CBFLAG_INC_DATA	0x20000000  /*!< use data from the include line,
					       not the subtable */
#define POPT_CBFLAG_SKIPOPTION	0x10000000  /*!< don't callback with option */
#define POPT_CBFLAG_CONTINUE	0x08000000  /*!< continue callbacks with option */
/*@}*/

/** \ingroup popt
 * \name Error return values
 */
/*@{*/
#define POPT_ERROR_NOARG	-10	/*!< missing argument */
#define POPT_ERROR_BADOPT	-11	/*!< unknown option */
#define POPT_ERROR_OPTSTOODEEP	-13	/*!< aliases nested too deeply */
#define POPT_ERROR_BADQUOTE	-15	/*!< error in paramter quoting */
#define POPT_ERROR_ERRNO	-16	/*!< errno set, use strerror(errno) */
#define POPT_ERROR_BADNUMBER	-17	/*!< invalid numeric value */
#define POPT_ERROR_OVERFLOW	-18	/*!< number too large or too small */
#define	POPT_ERROR_BADOPERATION	-19	/*!< mutually exclusive logical operations requested */
#define	POPT_ERROR_NULLARG	-20	/*!< opt->arg should not be NULL */
#define	POPT_ERROR_MALLOC	-21	/*!< memory allocation failed */
/*@}*/

/** \ingroup popt
 * \name poptBadOption() flags
 */
/*@{*/
#define POPT_BADOPTION_NOALIAS  (1 << 0)  /*!< don't go into an alias */
/*@}*/

/** \ingroup popt
 * \name poptGetContext() flags
 */
/*@{*/
#define POPT_CONTEXT_NO_EXEC	(1 << 0)  /*!< ignore exec expansions */
#define POPT_CONTEXT_KEEP_FIRST	(1 << 1)  /*!< pay attention to argv[0] */
#define POPT_CONTEXT_POSIXMEHARDER (1 << 2) /*!< options can't follow args */
#define POPT_CONTEXT_ARG_OPTS	(1 << 4) /*!< return args as options with value 0 */
/*@}*/

/** \ingroup popt
 */
struct poptOption {
/*@observer@*/ /*@null@*/ const char * longName; /*!< may be NULL */
    char shortName;			/*!< may be '\0' */
    int argInfo;
/*@shared@*/ /*@null@*/ void * arg;	/*!< depends on argInfo */
    int val;			/*!< 0 means don't return, just update flag */
/*@observer@*/ /*@null@*/ const char * descrip;	/*!< description for autohelp -- may be NULL */
/*@observer@*/ /*@null@*/ const char * argDescrip; /*!< argument description for autohelp */
};

/** \ingroup popt
 * A popt alias argument for poptAddAlias().
 */
struct poptAlias {
/*@owned@*/ /*@null@*/ const char * longName;	/*!< may be NULL */
    char shortName;		/*!< may be '\0' */
    int argc;
/*@owned@*/ const char ** argv;	/*!< must be free()able */
};

/** \ingroup popt
 * A popt alias or exec argument for poptAddItem().
 */
typedef struct poptItem_s {
    struct poptOption option;	/*!< alias/exec name(s) and description. */
    int argc;			/*!< (alias) no. of args. */
/*@owned@*/ const char ** argv;	/*!< (alias) args, must be free()able. */
} * poptItem;

/** \ingroup popt
 * \name Auto-generated help/usage
 */
/*@{*/

/**
 * Empty table marker to enable displaying popt alias/exec options.
 */
/*@observer@*/ /*@checked@*/
extern struct poptOption poptAliasOptions[];
#define POPT_AUTOALIAS { NULL, '\0', POPT_ARG_INCLUDE_TABLE, poptAliasOptions, \
			0, "Options implemented via popt alias/exec:", NULL },

/**
 * Auto help table options.
 */
/*@observer@*/ /*@checked@*/
extern struct poptOption poptHelpOptions[];
#define POPT_AUTOHELP { NULL, '\0', POPT_ARG_INCLUDE_TABLE, poptHelpOptions, \
			0, "Help options:", NULL },

#define POPT_TABLEEND { NULL, '\0', 0, 0, 0, NULL, NULL }
/*@}*/

/** \ingroup popt
 */
typedef /*@abstract@*/ struct poptContext_s * poptContext;

/** \ingroup popt
 */
#ifndef __cplusplus
/*@-typeuse@*/
typedef struct poptOption * poptOption;
/*@=typeuse@*/
#endif

enum poptCallbackReason { POPT_CALLBACK_REASON_PRE, 
			  POPT_CALLBACK_REASON_POST,
			  POPT_CALLBACK_REASON_OPTION };

#ifdef __cplusplus
extern "C" {
#endif
/*@-type@*/

/** \ingroup popt
 * Table callback prototype.
 * @param con		context
 * @param reason	reason for callback
 * @param opt		option that triggered callback
 * @param arg		@todo Document.
 * @param data		@todo Document.
 */
typedef void (*poptCallbackType) (poptContext con, 
		enum poptCallbackReason reason,
		/*@null@*/ const struct poptOption * opt,
		/*@null@*/ const char * arg,
		/*@null@*/ const void * data)
	/*@*/;

/** \ingroup popt
 * Initialize popt context.
 * @param name
 * @param argc		no. of arguments
 * @param argv		argument array
 * @param options	address of popt option table
 * @param flags		or'd POPT_CONTEXT_* bits
 * @return		initialized popt context
 */
/*@only@*/ /*@null@*/ poptContext poptGetContext(
		/*@dependent@*/ /*@keep@*/ const char * name,
		int argc, /*@dependent@*/ /*@keep@*/ const char ** argv,
		/*@dependent@*/ /*@keep@*/ const struct poptOption * options,
		int flags)
	/*@*/;

/** \ingroup popt
 * Reinitialize popt context.
 * @param con		context
 */
void poptResetContext(/*@null@*/poptContext con)
	/*@modifies con @*/;

/** \ingroup popt
 * Return value of next option found.
 * @param con		context
 * @return		next option val, -1 on last item, POPT_ERROR_* on error
 */
int poptGetNextOpt(/*@null@*/poptContext con)
	/*@globals fileSystem@*/
	/*@modifies con, fileSystem @*/;

/*@-redecl@*/
/** \ingroup popt
 * Return next option argument (if any).
 * @param con		context
 * @return		option argument, NULL if no more options are available
 */
/*@observer@*/ /*@null@*/ const char * poptGetOptArg(/*@null@*/poptContext con)
	/*@modifies con @*/;

/** \ingroup popt
 * Return current option's argument.
 * @param con		context
 * @return		option argument, NULL if no more options are available
 */
/*@observer@*/ /*@null@*/ const char * poptGetArg(/*@null@*/poptContext con)
	/*@modifies con @*/;

/** \ingroup popt
 * Peek at current option's argument.
 * @param con		context
 * @return		option argument
 */
/*@observer@*/ /*@null@*/ const char * poptPeekArg(/*@null@*/poptContext con)
	/*@*/;

/** \ingroup popt
 * Return remaining arguments.
 * @param con		context
 * @return		argument array, terminated with NULL
 */
/*@observer@*/ /*@null@*/ const char ** poptGetArgs(/*@null@*/poptContext con)
	/*@modifies con @*/;

/** \ingroup popt
 * Return the option which caused the most recent error.
 * @param con		context
 * @return		offending option
 */
/*@observer@*/ const char * poptBadOption(/*@null@*/poptContext con, int flags)
	/*@*/;
/*@=redecl@*/

/** \ingroup popt
 * Destroy context.
 * @param con		context
 * @return		NULL always
 */
/*@null@*/ poptContext poptFreeContext( /*@only@*/ /*@null@*/ poptContext con)
	/*@modifies con @*/;

/** \ingroup popt
 * Add arguments to context.
 * @param con		context
 * @param argv		argument array, NULL terminated
 * @return		0 on success, POPT_ERROR_OPTSTOODEEP on failure
 */
int poptStuffArgs(poptContext con, /*@keep@*/ const char ** argv)
	/*@modifies con @*/;

/** \ingroup popt
 * Add alias to context.
 * @todo Pass alias by reference, not value.
 * @deprecated Use poptAddItem instead.
 * @param con		context
 * @param alias		alias to add
 * @param flags		(unused)
 * @return		0 on success
 */
/*@unused@*/
int poptAddAlias(poptContext con, struct poptAlias alias, int flags)
	/*@modifies con @*/;

/** \ingroup popt
 * Add alias/exec item to context.
 * @param con		context
 * @param item		alias/exec item to add
 * @param flags		0 for alias, 1 for exec
 * @return		0 on success
 */
int poptAddItem(poptContext con, poptItem newItem, int flags)
	/*@modifies con @*/;

/** \ingroup popt
 * Read configuration file.
 * @param con		context
 * @param fn		file name to read
 * @return		0 on success, POPT_ERROR_ERRNO on failure
 */
int poptReadConfigFile(poptContext con, const char * fn)
	/*@globals fileSystem@*/
	/*@modifies fileSystem,
		con->execs, con->numExecs @*/;

/** \ingroup popt
 * Read default configuration from /etc/popt and $HOME/.popt.
 * @param con		context
 * @param useEnv	(unused)
 * @return		0 on success, POPT_ERROR_ERRNO on failure
 */
int poptReadDefaultConfig(poptContext con, /*@unused@*/ int useEnv)
	/*@globals fileSystem@*/
	/*@modifies fileSystem,
		con->execs, con->numExecs @*/;

/** \ingroup popt
 * Duplicate an argument array.
 * @note: The argument array is malloc'd as a single area, so only argv must
 * be free'd.
 *
 * @param argc		no. of arguments
 * @param argv		argument array
 * @retval argcPtr	address of returned no. of arguments
 * @retval argvPtr	address of returned argument array
 * @return		0 on success, POPT_ERROR_NOARG on failure
 */
int poptDupArgv(int argc, /*@null@*/ const char **argv,
		/*@null@*/ /*@out@*/ int * argcPtr,
		/*@null@*/ /*@out@*/ const char *** argvPtr)
	/*@modifies *argcPtr, *argvPtr @*/;

/** \ingroup popt
 * 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.
 *
 * @param s		string to parse
 * @retval argcPtr	address of returned no. of arguments
 * @retval argvPtr	address of returned argument array
 */
int poptParseArgvString(const unsigned char * s,
		/*@out@*/ int * argcPtr, /*@out@*/ const char *** argvPtr)
	/*@modifies *argcPtr, *argvPtr @*/;

/** \ingroup popt
 * Return formatted error string for popt failure.
 * @param error		popt error
 * @return		error string
 */
/*@-redecl@*/
/*@observer@*/ const char * poptStrerror(const int error)
	/*@*/;
/*@=redecl@*/

/** \ingroup popt
 * Limit search for executables.
 * @param con		context
 * @param path		single path to search for executables
 * @param allowAbsolute	absolute paths only?
 */
void poptSetExecPath(poptContext con, const char * path, int allowAbsolute)
	/*@modifies con @*/;

/** \ingroup popt
 * Print detailed description of options.
 * @param con		context
 * @param fp		ouput file handle
 * @param flags		(unused)
 */
void poptPrintHelp(poptContext con, FILE * fp, /*@unused@*/ int flags)
	/*@globals fileSystem @*/
	/*@modifies *fp, fileSystem @*/;

/** \ingroup popt
 * Print terse description of options.
 * @param con		context
 * @param fp		ouput file handle
 * @param flags		(unused)
 */
void poptPrintUsage(poptContext con, FILE * fp, /*@unused@*/ int flags)
	/*@globals fileSystem @*/
	/*@modifies *fp, fileSystem @*/;

/** \ingroup popt
 * Provide text to replace default "[OPTION...]" in help/usage output.
 * @param con		context
 * @param text		replacement text
 */
/*@-fcnuse@*/
void poptSetOtherOptionHelp(poptContext con, const char * text)
	/*@modifies con @*/;
/*@=fcnuse@*/

/** \ingroup popt
 * Return argv[0] from context.
 * @param con		context
 * @return		argv[0]
 */
/*@-redecl -fcnuse@*/
/*@observer@*/ const char * poptGetInvocationName(poptContext con)
	/*@*/;
/*@=redecl =fcnuse@*/

/** \ingroup popt
 * Shuffle argv pointers to remove stripped args, returns new argc.
 * @param con		context
 * @param argc		no. of args
 * @param argv		arg vector
 * @return		new argc
 */
/*@-fcnuse@*/
int poptStrippedArgv(poptContext con, int argc, char ** argv)
	/*@modifies *argv @*/;
/*@=fcnuse@*/

/*@=type@*/
#ifdef  __cplusplus
}
#endif

#endif
Commit	Line	Data
cc248aae WD	1	/** \file popt/popt.h
	2	* \ingroup popt
	3	*/
	4
	5	/* (C) 1998-2000 Red Hat, Inc. -- Licensing details are in the COPYING
62402cb1	6	file accompanying popt source distributions, available from
cc248aae	7	ftp://ftp.rpm.org/pub/rpm/dist. */
62402cb1 MP	8
	9	#ifndef H_POPT
	10	#define H_POPT
	11
	12	#include <stdio.h> /* for FILE * */
	13
	14	#define POPT_OPTION_DEPTH 10
	15
cc248aae WD	16	/** \ingroup popt
	17	* \name Arg type identifiers
	18	*/
	19	/@{/
	20	#define POPT_ARG_NONE 0 /!< no arg /
	21	#define POPT_ARG_STRING 1 /!< arg will be saved as string /
	22	#define POPT_ARG_INT 2 /!< arg will be converted to int /
	23	#define POPT_ARG_LONG 3 /!< arg will be converted to long /
	24	#define POPT_ARG_INCLUDE_TABLE 4 /!< arg points to table /
	25	#define POPT_ARG_CALLBACK 5 /*!< table-wide callback... must be
62402cb1 MP	26	set first in table; arg points
	27	to callback, descrip points to
	28	callback data to pass */
cc248aae	29	#define POPT_ARG_INTL_DOMAIN 6 /*!< set the translation domain
b348deae MP	30	for this table and any
	31	included tables; arg points
	32	to the domain string */
cc248aae WD	33	#define POPT_ARG_VAL 7 /!< arg should take value val /
	34	#define POPT_ARG_FLOAT 8 /!< arg will be converted to float /
	35	#define POPT_ARG_DOUBLE 9 /!< arg will be converted to double /
	36
62402cb1	37	#define POPT_ARG_MASK 0x0000FFFF
cc248aae WD	38	/@}/
	39
	40	/** \ingroup popt
	41	* \name Arg modifiers
	42	*/
	43	/@{/
	44	#define POPT_ARGFLAG_ONEDASH 0x80000000 /!< allow -longoption /
	45	#define POPT_ARGFLAG_DOC_HIDDEN 0x40000000 /!< don't show in help/usage /
	46	#define POPT_ARGFLAG_STRIP 0x20000000 /!< strip this arg from argv(only applies to long args) /
	47	#define POPT_ARGFLAG_OPTIONAL 0x10000000 /!< arg may be missing /
	48
	49	#define POPT_ARGFLAG_OR 0x08000000 /!< arg will be or'ed /
	50	#define POPT_ARGFLAG_NOR 0x09000000 /!< arg will be nor'ed /
	51	#define POPT_ARGFLAG_AND 0x04000000 /!< arg will be and'ed /
	52	#define POPT_ARGFLAG_NAND 0x05000000 /!< arg will be nand'ed /
	53	#define POPT_ARGFLAG_XOR 0x02000000 /!< arg will be xor'ed /
	54	#define POPT_ARGFLAG_NOT 0x01000000 /!< arg will be negated /
	55	#define POPT_ARGFLAG_LOGICALOPS \
	56	(POPT_ARGFLAG_OR\|POPT_ARGFLAG_AND\|POPT_ARGFLAG_XOR)
	57
	58	#define POPT_BIT_SET (POPT_ARG_VAL\|POPT_ARGFLAG_OR)
	59	/!< set arg bit(s) /
	60	#define POPT_BIT_CLR (POPT_ARG_VAL\|POPT_ARGFLAG_NAND)
	61	/!< clear arg bit(s) /
	62
	63	#define POPT_ARGFLAG_SHOW_DEFAULT 0x00800000 /!< show default value in --help /
	64
	65	/@}/
	66
	67	/** \ingroup popt
	68	* \name Callback modifiers
	69	*/
	70	/@{/
	71	#define POPT_CBFLAG_PRE 0x80000000 /!< call the callback before parse /
	72	#define POPT_CBFLAG_POST 0x40000000 /!< call the callback after parse /
	73	#define POPT_CBFLAG_INC_DATA 0x20000000 /*!< use data from the include line,
62402cb1	74	not the subtable */
cc248aae WD	75	#define POPT_CBFLAG_SKIPOPTION 0x10000000 /!< don't callback with option /
	76	#define POPT_CBFLAG_CONTINUE 0x08000000 /!< continue callbacks with option /
	77	/@}/
62402cb1	78
cc248aae WD	79	/** \ingroup popt
	80	* \name Error return values
	81	*/
	82	/@{/
	83	#define POPT_ERROR_NOARG -10 /!< missing argument /
	84	#define POPT_ERROR_BADOPT -11 /!< unknown option /
	85	#define POPT_ERROR_OPTSTOODEEP -13 /!< aliases nested too deeply /
	86	#define POPT_ERROR_BADQUOTE -15 /!< error in paramter quoting /
	87	#define POPT_ERROR_ERRNO -16 /!< errno set, use strerror(errno) /
	88	#define POPT_ERROR_BADNUMBER -17 /!< invalid numeric value /
	89	#define POPT_ERROR_OVERFLOW -18 /!< number too large or too small /
	90	#define POPT_ERROR_BADOPERATION -19 /!< mutually exclusive logical operations requested /
	91	#define POPT_ERROR_NULLARG -20 /!< opt->arg should not be NULL /
	92	#define POPT_ERROR_MALLOC -21 /!< memory allocation failed /
	93	/@}/
62402cb1	94
cc248aae WD	95	/** \ingroup popt
	96	* \name poptBadOption() flags
	97	*/
	98	/@{/
	99	#define POPT_BADOPTION_NOALIAS (1 << 0) /!< don't go into an alias /
	100	/@}/
62402cb1	101
cc248aae WD	102	/** \ingroup popt
	103	* \name poptGetContext() flags
	104	*/
	105	/@{/
	106	#define POPT_CONTEXT_NO_EXEC (1 << 0) /!< ignore exec expansions /
	107	#define POPT_CONTEXT_KEEP_FIRST (1 << 1) /!< pay attention to argv[0] /
	108	#define POPT_CONTEXT_POSIXMEHARDER (1 << 2) /!< options can't follow args /
	109	#define POPT_CONTEXT_ARG_OPTS (1 << 4) /!< return args as options with value 0 /
	110	/@}/
62402cb1	111
cc248aae WD	112	/** \ingroup popt
cc248aae WD	113	*/
62402cb1	114	struct poptOption {
cc248aae WD	115	/@observer@/ /@null@/ const char * longName; /!< may be NULL /
cc248aae WD	116	char shortName; /!< may be '\0' /
62402cb1	117	int argInfo;
cc248aae WD	118	/@shared@/ /@null@/ void * arg; /!< depends on argInfo /
	119	int val; /!< 0 means don't return, just update flag /
	120	/@observer@/ /@null@/ const char * descrip; /!< description for autohelp -- may be NULL /
	121	/@observer@/ /@null@/ const char * argDescrip; /!< argument description for autohelp /
62402cb1 MP	122	};
62402cb1 MP	123
cc248aae WD	124	/** \ingroup popt
	125	* A popt alias argument for poptAddAlias().
	126	*/
62402cb1	127	struct poptAlias {
cc248aae WD	128	/@owned@/ /@null@/ const char * longName; /!< may be NULL /
cc248aae WD	129	char shortName; /!< may be '\0' /
62402cb1	130	int argc;
cc248aae	131	/@owned@/ const char ** argv; /!< must be free()able /
62402cb1 MP	132	};
62402cb1 MP	133
cc248aae WD	134	/** \ingroup popt
	135	* A popt alias or exec argument for poptAddItem().
	136	*/
	137	typedef struct poptItem_s {
	138	struct poptOption option; /!< alias/exec name(s) and description. /
	139	int argc; /!< (alias) no. of args. /
	140	/@owned@/ const char ** argv; /!< (alias) args, must be free()able. /
	141	} * poptItem;
	142
	143	/** \ingroup popt
	144	* \name Auto-generated help/usage
	145	*/
	146	/@{/
	147
	148	/**
	149	* Empty table marker to enable displaying popt alias/exec options.
	150	*/
	151	/@observer@/ /@checked@/
	152	extern struct poptOption poptAliasOptions[];
	153	#define POPT_AUTOALIAS { NULL, '\0', POPT_ARG_INCLUDE_TABLE, poptAliasOptions, \
	154	0, "Options implemented via popt alias/exec:", NULL },
	155
	156	/**
	157	* Auto help table options.
	158	*/
	159	/@observer@/ /@checked@/
62402cb1 MP	160	extern struct poptOption poptHelpOptions[];
62402cb1 MP	161	#define POPT_AUTOHELP { NULL, '\0', POPT_ARG_INCLUDE_TABLE, poptHelpOptions, \
cc248aae	162	0, "Help options:", NULL },
62402cb1	163
cc248aae WD	164	#define POPT_TABLEEND { NULL, '\0', 0, 0, 0, NULL, NULL }
	165	/@}/
	166
	167	/** \ingroup popt
	168	*/
	169	typedef /@abstract@/ struct poptContext_s * poptContext;
	170
	171	/** \ingroup popt
	172	*/
62402cb1	173	#ifndef __cplusplus
cc248aae	174	/@-typeuse@/
62402cb1	175	typedef struct poptOption * poptOption;
cc248aae	176	/@=typeuse@/
62402cb1 MP	177	#endif
	178
	179	enum poptCallbackReason { POPT_CALLBACK_REASON_PRE,
	180	POPT_CALLBACK_REASON_POST,
	181	POPT_CALLBACK_REASON_OPTION };
cc248aae WD	182
	183	#ifdef __cplusplus
	184	extern "C" {
	185	#endif
	186	/@-type@/
	187
	188	/** \ingroup popt
	189	* Table callback prototype.
	190	* @param con context
	191	* @param reason reason for callback
	192	* @param opt option that triggered callback
	193	* @param arg @todo Document.
	194	* @param data @todo Document.
	195	*/
	196	typedef void (*poptCallbackType) (poptContext con,
	197	enum poptCallbackReason reason,
	198	/@null@/ const struct poptOption * opt,
	199	/@null@/ const char * arg,
	200	/@null@/ const void * data)
	201	/@/;
	202
	203	/** \ingroup popt
	204	* Initialize popt context.
	205	* @param name
	206	* @param argc no. of arguments
	207	* @param argv argument array
	208	* @param options address of popt option table
	209	* @param flags or'd POPT_CONTEXT_* bits
	210	* @return initialized popt context
	211	*/
	212	/@only@/ /@null@/ poptContext poptGetContext(
	213	/@dependent@/ /@keep@/ const char * name,
	214	int argc, /@dependent@/ /@keep@/ const char ** argv,
	215	/@dependent@/ /@keep@/ const struct poptOption * options,
	216	int flags)
	217	/@/;
	218
	219	/** \ingroup popt
	220	* Reinitialize popt context.
	221	* @param con context
	222	*/
	223	void poptResetContext(/@null@/poptContext con)
	224	/@modifies con @/;
	225
	226	/** \ingroup popt
	227	* Return value of next option found.
	228	* @param con context
	229	* @return next option val, -1 on last item, POPT_ERROR_* on error
	230	*/
	231	int poptGetNextOpt(/@null@/poptContext con)
	232	/@globals fileSystem@/
	233	/@modifies con, fileSystem @/;
	234
	235	/@-redecl@/
	236	/** \ingroup popt
	237	* Return next option argument (if any).
	238	* @param con context
	239	* @return option argument, NULL if no more options are available
	240	*/
	241	/@observer@/ /@null@/ const char * poptGetOptArg(/@null@/poptContext con)
	242	/@modifies con @/;
	243
	244	/** \ingroup popt
	245	* Return current option's argument.
246	* @param con context
247	* @return option argument, NULL if no more options are available
248	*/
249	/@observer@/ /@null@/ const char * poptGetArg(/@null@/poptContext con)
250	/@modifies con @/;
251
252	/** \ingroup popt
253	* Peek at current option's argument.
254	* @param con context
255	* @return option argument
256	*/
257	/@observer@/ /@null@/ const char * poptPeekArg(/@null@/poptContext con)
258	/@/;
259
260	/** \ingroup popt
261	* Return remaining arguments.
262	* @param con context
263	* @return argument array, terminated with NULL
264	*/
265	/@observer@/ /@null@/ const char ** poptGetArgs(/@null@/poptContext con)
266	/@modifies con @/;
267
268	/** \ingroup popt
269	* Return the option which caused the most recent error.
270	* @param con context
271	* @return offending option
272	*/
273	/@observer@/ const char * poptBadOption(/@null@/poptContext con, int flags)
274	/@/;
275	/@=redecl@/
276
277	/** \ingroup popt
278	* Destroy context.
279	* @param con context
280	* @return NULL always
281	*/
282	/@null@/ poptContext poptFreeContext( /@only@/ /@null@/ poptContext con)
283	/@modifies con @/;
284
285	/** \ingroup popt
286	* Add arguments to context.
287	* @param con context
288	* @param argv argument array, NULL terminated
289	* @return 0 on success, POPT_ERROR_OPTSTOODEEP on failure
290	*/
291	int poptStuffArgs(poptContext con, /@keep@/ const char ** argv)
292	/@modifies con @/;
293
294	/** \ingroup popt
295	* Add alias to context.
296	* @todo Pass alias by reference, not value.
297	* @deprecated Use poptAddItem instead.
298	* @param con context
299	* @param alias alias to add
300	* @param flags (unused)
301	* @return 0 on success
302	*/
303	/@unused@/
304	int poptAddAlias(poptContext con, struct poptAlias alias, int flags)
305	/@modifies con @/;
306
307	/** \ingroup popt
308	* Add alias/exec item to context.
309	* @param con context
310	* @param item alias/exec item to add
311	* @param flags 0 for alias, 1 for exec
312	* @return 0 on success
313	*/
314	int poptAddItem(poptContext con, poptItem newItem, int flags)
315	/@modifies con @/;
316
317	/** \ingroup popt
318	* Read configuration file.
319	* @param con context
320	* @param fn file name to read
321	* @return 0 on success, POPT_ERROR_ERRNO on failure
322	*/
323	int poptReadConfigFile(poptContext con, const char * fn)
324	/@globals fileSystem@/
325	/*@modifies fileSystem,
326	con->execs, con->numExecs @*/;
327
328	/** \ingroup popt
329	* Read default configuration from /etc/popt and $HOME/.popt.
330	* @param con context
331	* @param useEnv (unused)
332	* @return 0 on success, POPT_ERROR_ERRNO on failure
333	*/
334	int poptReadDefaultConfig(poptContext con, /@unused@/ int useEnv)
335	/@globals fileSystem@/
336	/*@modifies fileSystem,
337	con->execs, con->numExecs @*/;
338
339	/** \ingroup popt
340	* Duplicate an argument array.
341	* @note: The argument array is malloc'd as a single area, so only argv must
342	* be free'd.
343	*
344	* @param argc no. of arguments
345	* @param argv argument array
346	* @retval argcPtr address of returned no. of arguments
347	* @retval argvPtr address of returned argument array
348	* @return 0 on success, POPT_ERROR_NOARG on failure
349	*/
350	int poptDupArgv(int argc, /@null@/ const char **argv,
351	/@null@/ /@out@/ int * argcPtr,
352	/@null@/ /@out@/ const char *** argvPtr)
353	/@modifies argcPtr, argvPtr @/;
354
355	/** \ingroup popt
356	* Parse a string into an argument array.
357	* The parse allows ', ", and \ quoting, but ' is treated the same as " and
358	* both may include \ quotes.
359	* @note: The argument array is malloc'd as a single area, so only argv must
360	* be free'd.
361	*
362	* @param s string to parse
363	* @retval argcPtr address of returned no. of arguments
364	* @retval argvPtr address of returned argument array
365	*/
37101856	366	int poptParseArgvString(const unsigned char * s,
cc248aae WD	367	/@out@/ int * argcPtr, /@out@/ const char *** argvPtr)
	368	/@modifies argcPtr, argvPtr @/;
	369
	370	/** \ingroup popt
	371	* Return formatted error string for popt failure.
	372	* @param error popt error
	373	* @return error string
	374	*/
	375	/@-redecl@/
4fd4b3d6	376	/@observer@/ const char * poptStrerror(const int error)
cc248aae WD	377	/@/;
	378	/@=redecl@/
	379
	380	/** \ingroup popt
	381	* Limit search for executables.
	382	* @param con context
	383	* @param path single path to search for executables
	384	* @param allowAbsolute absolute paths only?
	385	*/
	386	void poptSetExecPath(poptContext con, const char * path, int allowAbsolute)
	387	/@modifies con @/;
	388
	389	/** \ingroup popt
	390	* Print detailed description of options.
	391	* @param con context
	392	* @param fp ouput file handle
	393	* @param flags (unused)
	394	*/
	395	void poptPrintHelp(poptContext con, FILE * fp, /@unused@/ int flags)
	396	/@globals fileSystem @/
	397	/@modifies fp, fileSystem @*/;
	398
	399	/** \ingroup popt
	400	* Print terse description of options.
	401	* @param con context
	402	* @param fp ouput file handle
	403	* @param flags (unused)
	404	*/
	405	void poptPrintUsage(poptContext con, FILE * fp, /@unused@/ int flags)
	406	/@globals fileSystem @/
	407	/@modifies fp, fileSystem @*/;
	408
	409	/** \ingroup popt
	410	* Provide text to replace default "[OPTION...]" in help/usage output.
	411	* @param con context
	412	* @param text replacement text
	413	*/
	414	/@-fcnuse@/
	415	void poptSetOtherOptionHelp(poptContext con, const char * text)
	416	/@modifies con @/;
	417	/@=fcnuse@/
	418
	419	/** \ingroup popt
	420	* Return argv[0] from context.
	421	* @param con context
	422	* @return argv[0]
	423	*/
	424	/@-redecl -fcnuse@/
	425	/@observer@/ const char * poptGetInvocationName(poptContext con)
	426	/@/;
	427	/@=redecl =fcnuse@/
	428
	429	/** \ingroup popt
	430	* Shuffle argv pointers to remove stripped args, returns new argc.
	431	* @param con context
	432	* @param argc no. of args
	433	* @param argv arg vector
	434	* @return new argc
	435	*/
	436	/@-fcnuse@/
	437	int poptStrippedArgv(poptContext con, int argc, char ** argv)
	438	/@modifies argv @*/;
	439	/@=fcnuse@/
b348deae	440
cc248aae	441	/@=type@/
b348deae MP	442	#ifdef __cplusplus
	443	}
	444	#endif
62402cb1 MP	445
62402cb1 MP	446	#endif