[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 NUL */
    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 NUL */
    int argc;
/*@owned@*/
    const char ** argv;		/*!< must be free()able */
};

/** \ingroup popt
 * A popt alias or exec argument for poptAddItem().
 */
/*@-exporttype@*/
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;
/*@=exporttype@*/

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

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

/**
 * Auto help table options.
 */
/*@-exportvar@*/
/*@unchecked@*/ /*@observer@*/
extern struct poptOption poptHelpOptions[];
/*@=exportvar@*/

/*@-exportvar@*/
/*@unchecked@*/ /*@observer@*/
extern struct poptOption * poptHelpOptionsI18N;
/*@=exportvar@*/

#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
 */
/*@-exporttype@*/
typedef /*@abstract@*/ struct poptContext_s * poptContext;
/*@=exporttype@*/

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

/*@-exportconst@*/
enum poptCallbackReason {
    POPT_CALLBACK_REASON_PRE	= 0, 
    POPT_CALLBACK_REASON_POST	= 1,
    POPT_CALLBACK_REASON_OPTION = 2
};
/*@=exportconst@*/

#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)
	/*@globals internalState @*/
	/*@modifies internalState @*/;

/** \ingroup popt
 * Initialize popt context.
 * @param name		context name (usually argv[0] program 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
 */
/*@unused@*/
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, internalState @*/
	/*@modifies con, fileSystem, internalState @*/;

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

/** \ingroup popt
 * Return next argument.
 * @param con		context
 * @return		next argument, NULL if no argument is available
 */
/*@observer@*/ /*@null@*/ /*@unused@*/
const char * poptGetArg(/*@null@*/poptContext con)
	/*@modifies con @*/;

/** \ingroup popt
 * Peek at current argument.
 * @param con		context
 * @return		current argument, NULL if no argument is available
 */
/*@observer@*/ /*@null@*/ /*@unused@*/
const char * poptPeekArg(/*@null@*/poptContext con)
	/*@*/;

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

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

/** \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
 */
/*@unused@*/
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 newItem	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 errno, fileSystem, internalState @*/
	/*@modifies con->execs, con->numExecs,
		errno, fileSystem, internalState @*/;

/** \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
 */
/*@unused@*/
int poptReadDefaultConfig(poptContext con, /*@unused@*/ int useEnv)
	/*@globals fileSystem, internalState @*/
	/*@modifies con->execs, con->numExecs,
		fileSystem, internalState @*/;

/** \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 char * s,
		/*@out@*/ int * argcPtr, /*@out@*/ const char *** argvPtr)
	/*@modifies *argcPtr, *argvPtr @*/;

/** \ingroup popt
 * 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:
\verbatim
# 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
\endverbatim
*
* The result is:
\verbatim
--aaa --bbb --ccc --bla="bla" --this_is="fdsafdas" --5555="55555" --test="with lots of spaces"
\endverbatim
*
* Passing this to poptParseArgvString() yields an argv of:
\verbatim
'--aaa'
'--bbb' 
'--ccc' 
'--bla=bla' 
'--this_is=fdsafdas' 
'--5555=55555' 
'--test=with lots of spaces' 
\endverbatim
 *
 * @bug NULL is returned if file line is too long.
 * @bug Silently ignores invalid lines.
 *
 * @param fp		file handle to read
 * @param *argstrp	return string of options (malloc'd)
 * @param flags		unused
 * @return		0 on success
 * @see			poptParseArgvString
 */
/*@-fcnuse@*/
int poptConfigFileToString(FILE *fp, /*@out@*/ char ** argstrp, int flags)
	/*@globals fileSystem @*/
	/*@modifies *fp, *argstrp, fileSystem @*/;
/*@=fcnuse@*/

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

/** \ingroup popt
 * Limit search for executables.
 * @param con		context
 * @param path		single path to search for executables
 * @param allowAbsolute	absolute paths only?
 */
/*@unused@*/
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]
 */
/*@-fcnuse@*/
/*@observer@*/
const char * poptGetInvocationName(poptContext con)
	/*@*/;
/*@=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@*/

/**
 * Save a long, performing logical operation with value.
 * @warning Alignment check may be too strict on certain platorms.
 * @param arg		integer pointer, aligned on int boundary.
 * @param argInfo	logical operation (see POPT_ARGFLAG_*)
 * @param aLong		value to use
 * @return		0 on success, POPT_ERROR_NULLARG/POPT_ERROR_BADOPERATION
 */
/*@-incondefs@*/
/*@unused@*/
int poptSaveLong(/*@null@*/ long * arg, int argInfo, long aLong)
	/*@modifies *arg @*/
	/*@requires maxSet(arg) >= 0 /\ maxRead(arg) == 0 @*/;
/*@=incondefs@*/

/**
 * Save an integer, performing logical operation with value.
 * @warning Alignment check may be too strict on certain platorms.
 * @param arg		integer pointer, aligned on int boundary.
 * @param argInfo	logical operation (see POPT_ARGFLAG_*)
 * @param aLong		value to use
 * @return		0 on success, POPT_ERROR_NULLARG/POPT_ERROR_BADOPERATION
 */
/*@-incondefs@*/
/*@unused@*/
int poptSaveInt(/*@null@*/ int * arg, int argInfo, long aLong)
	/*@modifies *arg @*/
	/*@requires maxSet(arg) >= 0 /\ maxRead(arg) == 0 @*/;
/*@=incondefs@*/

/*@=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 {
bc93ee84 WD	115	/@observer@/ /@null@/
	116	const char * longName; /!< may be NULL /
	117	char shortName; /!< may be NUL /
62402cb1	118	int argInfo;
bc93ee84 WD	119	/@shared@/ /@null@/
bc93ee84 WD	120	void * arg; /!< depends on argInfo /
cc248aae	121	int val; /!< 0 means don't return, just update flag /
bc93ee84 WD	122	/@observer@/ /@null@/
	123	const char * descrip; /!< description for autohelp -- may be NULL /
	124	/@observer@/ /@null@/
	125	const char * argDescrip; /!< argument description for autohelp /
62402cb1 MP	126	};
62402cb1 MP	127
cc248aae WD	128	/** \ingroup popt
	129	* A popt alias argument for poptAddAlias().
	130	*/
62402cb1	131	struct poptAlias {
bc93ee84 WD	132	/@owned@/ /@null@/
	133	const char * longName; /!< may be NULL /
	134	char shortName; /!< may be NUL /
62402cb1	135	int argc;
bc93ee84 WD	136	/@owned@/
bc93ee84 WD	137	const char ** argv; /!< must be free()able /
62402cb1 MP	138	};
62402cb1 MP	139
cc248aae WD	140	/** \ingroup popt
	141	* A popt alias or exec argument for poptAddItem().
	142	*/
bc93ee84	143	/@-exporttype@/
cc248aae WD	144	typedef struct poptItem_s {
	145	struct poptOption option; /!< alias/exec name(s) and description. /
	146	int argc; /!< (alias) no. of args. /
bc93ee84 WD	147	/@owned@/
bc93ee84 WD	148	const char ** argv; /!< (alias) args, must be free()able. /
cc248aae	149	} * poptItem;
bc93ee84	150	/@=exporttype@/
cc248aae WD	151
	152	/** \ingroup popt
	153	* \name Auto-generated help/usage
	154	*/
	155	/@{/
	156
	157	/**
	158	* Empty table marker to enable displaying popt alias/exec options.
	159	*/
bc93ee84 WD	160	/@-exportvar@/
bc93ee84 WD	161	/@unchecked@/ /@observer@/
cc248aae	162	extern struct poptOption poptAliasOptions[];
bc93ee84	163	/@=exportvar@/
cc248aae WD	164	#define POPT_AUTOALIAS { NULL, '\0', POPT_ARG_INCLUDE_TABLE, poptAliasOptions, \
	165	0, "Options implemented via popt alias/exec:", NULL },
	166
	167	/**
	168	* Auto help table options.
	169	*/
bc93ee84 WD	170	/@-exportvar@/
bc93ee84 WD	171	/@unchecked@/ /@observer@/
62402cb1	172	extern struct poptOption poptHelpOptions[];
bc93ee84 WD	173	/@=exportvar@/
	174
	175	/@-exportvar@/
	176	/@unchecked@/ /@observer@/
	177	extern struct poptOption * poptHelpOptionsI18N;
	178	/@=exportvar@/
	179
62402cb1	180	#define POPT_AUTOHELP { NULL, '\0', POPT_ARG_INCLUDE_TABLE, poptHelpOptions, \
cc248aae	181	0, "Help options:", NULL },
62402cb1	182
cc248aae WD	183	#define POPT_TABLEEND { NULL, '\0', 0, 0, 0, NULL, NULL }
	184	/@}/
	185
	186	/** \ingroup popt
	187	*/
bc93ee84	188	/@-exporttype@/
cc248aae	189	typedef /@abstract@/ struct poptContext_s * poptContext;
bc93ee84	190	/@=exporttype@/
cc248aae WD	191
	192	/** \ingroup popt
	193	*/
62402cb1	194	#ifndef __cplusplus
bc93ee84	195	/@-exporttype -typeuse@/
62402cb1	196	typedef struct poptOption * poptOption;
bc93ee84	197	/@=exporttype =typeuse@/
62402cb1 MP	198	#endif
62402cb1 MP	199
bc93ee84 WD	200	/@-exportconst@/
	201	enum poptCallbackReason {
	202	POPT_CALLBACK_REASON_PRE = 0,
	203	POPT_CALLBACK_REASON_POST = 1,
	204	POPT_CALLBACK_REASON_OPTION = 2
	205	};
	206	/@=exportconst@/
cc248aae WD	207
	208	#ifdef __cplusplus
	209	extern "C" {
	210	#endif
	211	/@-type@/
	212
	213	/** \ingroup popt
	214	* Table callback prototype.
	215	* @param con context
	216	* @param reason reason for callback
	217	* @param opt option that triggered callback
	218	* @param arg @todo Document.
	219	* @param data @todo Document.
	220	*/
	221	typedef void (*poptCallbackType) (poptContext con,
	222	enum poptCallbackReason reason,
	223	/@null@/ const struct poptOption * opt,
	224	/@null@/ const char * arg,
	225	/@null@/ const void * data)
bc93ee84 WD	226	/@globals internalState @/
bc93ee84 WD	227	/@modifies internalState @/;
cc248aae WD	228
	229	/** \ingroup popt
	230	* Initialize popt context.
bc93ee84	231	* @param name context name (usually argv[0] program name)
cc248aae WD	232	* @param argc no. of arguments
	233	* @param argv argument array
	234	* @param options address of popt option table
	235	* @param flags or'd POPT_CONTEXT_* bits
	236	* @return initialized popt context
	237	*/
bc93ee84 WD	238	/@only@/ /@null@/
bc93ee84 WD	239	poptContext poptGetContext(
cc248aae WD	240	/@dependent@/ /@keep@/ const char * name,
	241	int argc, /@dependent@/ /@keep@/ const char ** argv,
	242	/@dependent@/ /@keep@/ const struct poptOption * options,
	243	int flags)
	244	/@/;
	245
	246	/** \ingroup popt
	247	* Reinitialize popt context.
	248	* @param con context
	249	*/
bc93ee84	250	/@unused@/
cc248aae WD	251	void poptResetContext(/@null@/poptContext con)
	252	/@modifies con @/;
	253
	254	/** \ingroup popt
	255	* Return value of next option found.
	256	* @param con context
	257	* @return next option val, -1 on last item, POPT_ERROR_* on error
	258	*/
	259	int poptGetNextOpt(/@null@/poptContext con)
bc93ee84 WD	260	/@globals fileSystem, internalState @/
bc93ee84 WD	261	/@modifies con, fileSystem, internalState @/;
cc248aae	262
cc248aae WD	263	/** \ingroup popt
	264	* Return next option argument (if any).
	265	* @param con context
bc93ee84	266	* @return option argument, NULL if no argument is available
cc248aae	267	*/
bc93ee84 WD	268	/@observer@/ /@null@/ /@unused@/
bc93ee84 WD	269	const char * poptGetOptArg(/@null@/poptContext con)
cc248aae WD	270	/@modifies con @/;
	271
	272	/** \ingroup popt
bc93ee84	273	* Return next argument.
cc248aae	274	* @param con context
bc93ee84	275	* @return next argument, NULL if no argument is available
cc248aae	276	*/
bc93ee84 WD	277	/@observer@/ /@null@/ /@unused@/
bc93ee84 WD	278	const char * poptGetArg(/@null@/poptContext con)
cc248aae WD	279	/@modifies con @/;
	280
	281	/** \ingroup popt
bc93ee84	282	* Peek at current argument.
cc248aae	283	* @param con context
bc93ee84	284	* @return current argument, NULL if no argument is available
cc248aae	285	*/
bc93ee84 WD	286	/@observer@/ /@null@/ /@unused@/
bc93ee84 WD	287	const char * poptPeekArg(/@null@/poptContext con)
cc248aae WD	288	/@/;
	289
	290	/** \ingroup popt
	291	* Return remaining arguments.
	292	* @param con context
bc93ee84	293	* @return argument array, NULL terminated
cc248aae	294	*/
bc93ee84 WD	295	/@observer@/ /@null@/
bc93ee84 WD	296	const char ** poptGetArgs(/@null@/poptContext con)
cc248aae WD	297	/@modifies con @/;
	298
	299	/** \ingroup popt
	300	* Return the option which caused the most recent error.
	301	* @param con context
bc93ee84	302	* @param flags
cc248aae WD	303	* @return offending option
cc248aae WD	304	*/
bc93ee84 WD	305	/@observer@/
bc93ee84 WD	306	const char * poptBadOption(/@null@/poptContext con, int flags)
cc248aae	307	/@/;
cc248aae WD	308
	309	/** \ingroup popt
	310	* Destroy context.
	311	* @param con context
	312	* @return NULL always
	313	*/
bc93ee84 WD	314	/@null@/
bc93ee84 WD	315	poptContext poptFreeContext( /@only@/ /@null@/ poptContext con)
cc248aae WD	316	/@modifies con @/;
	317
	318	/** \ingroup popt
	319	* Add arguments to context.
	320	* @param con context
	321	* @param argv argument array, NULL terminated
	322	* @return 0 on success, POPT_ERROR_OPTSTOODEEP on failure
	323	*/
bc93ee84	324	/@unused@/
cc248aae WD	325	int poptStuffArgs(poptContext con, /@keep@/ const char ** argv)
	326	/@modifies con @/;
	327
	328	/** \ingroup popt
	329	* Add alias to context.
	330	* @todo Pass alias by reference, not value.
	331	* @deprecated Use poptAddItem instead.
	332	* @param con context
	333	* @param alias alias to add
	334	* @param flags (unused)
	335	* @return 0 on success
	336	*/
	337	/@unused@/
	338	int poptAddAlias(poptContext con, struct poptAlias alias, int flags)
	339	/@modifies con @/;
	340
	341	/** \ingroup popt
	342	* Add alias/exec item to context.
	343	* @param con context
bc93ee84	344	* @param newItem alias/exec item to add
cc248aae WD	345	* @param flags 0 for alias, 1 for exec
	346	* @return 0 on success
	347	*/
	348	int poptAddItem(poptContext con, poptItem newItem, int flags)
	349	/@modifies con @/;
	350
	351	/** \ingroup popt
	352	* Read configuration file.
	353	* @param con context
	354	* @param fn file name to read
	355	* @return 0 on success, POPT_ERROR_ERRNO on failure
	356	*/
	357	int poptReadConfigFile(poptContext con, const char * fn)
bc93ee84 WD	358	/@globals errno, fileSystem, internalState @/
	359	/*@modifies con->execs, con->numExecs,
	360	errno, fileSystem, internalState @*/;
cc248aae WD	361
	362	/** \ingroup popt
	363	* Read default configuration from /etc/popt and $HOME/.popt.
	364	* @param con context
	365	* @param useEnv (unused)
	366	* @return 0 on success, POPT_ERROR_ERRNO on failure
	367	*/
bc93ee84	368	/@unused@/
cc248aae	369	int poptReadDefaultConfig(poptContext con, /@unused@/ int useEnv)
bc93ee84 WD	370	/@globals fileSystem, internalState @/
	371	/*@modifies con->execs, con->numExecs,
	372	fileSystem, internalState @*/;
cc248aae WD	373
	374	/** \ingroup popt
	375	* Duplicate an argument array.
	376	* @note: The argument array is malloc'd as a single area, so only argv must
	377	* be free'd.
	378	*
	379	* @param argc no. of arguments
	380	* @param argv argument array
	381	* @retval argcPtr address of returned no. of arguments
	382	* @retval argvPtr address of returned argument array
	383	* @return 0 on success, POPT_ERROR_NOARG on failure
	384	*/
	385	int poptDupArgv(int argc, /@null@/ const char **argv,
	386	/@null@/ /@out@/ int * argcPtr,
	387	/@null@/ /@out@/ const char *** argvPtr)
	388	/@modifies argcPtr, argvPtr @/;
	389
	390	/** \ingroup popt
	391	* Parse a string into an argument array.
	392	* The parse allows ', ", and \ quoting, but ' is treated the same as " and
	393	* both may include \ quotes.
	394	* @note: The argument array is malloc'd as a single area, so only argv must
	395	* be free'd.
	396	*
	397	* @param s string to parse
	398	* @retval argcPtr address of returned no. of arguments
	399	* @retval argvPtr address of returned argument array
	400	*/
bc93ee84	401	int poptParseArgvString(const char * s,
cc248aae WD	402	/@out@/ int * argcPtr, /@out@/ const char *** argvPtr)
	403	/@modifies argcPtr, argvPtr @/;
	404
bc93ee84 WD	405	/** \ingroup popt
	406	* Parses an input configuration file and returns an string that is a
	407	* command line. For use with popt. You must free the return value when done.
	408	*
	409	* Given the file:
	410	\verbatim
	411	# this line is ignored
	412	# this one too
	413	aaa
	414	bbb
	415	ccc
	416	bla=bla
	417
	418	this_is = fdsafdas
	419	bad_line=
	420	reall bad line
	421	reall bad line = again
	422	5555= 55555
	423	test = with lots of spaces
	424	\endverbatim
	425	*
	426	* The result is:
	427	\verbatim
	428	--aaa --bbb --ccc --bla="bla" --this_is="fdsafdas" --5555="55555" --test="with lots of spaces"
	429	\endverbatim
	430	*
	431	* Passing this to poptParseArgvString() yields an argv of:
	432	\verbatim
	433	'--aaa'
	434	'--bbb'
	435	'--ccc'
	436	'--bla=bla'
	437	'--this_is=fdsafdas'
	438	'--5555=55555'
	439	'--test=with lots of spaces'
	440	\endverbatim
	441	*
	442	* @bug NULL is returned if file line is too long.
	443	* @bug Silently ignores invalid lines.
	444	*
	445	* @param fp file handle to read
	446	* @param *argstrp return string of options (malloc'd)
	447	* @param flags unused
	448	* @return 0 on success
	449	* @see poptParseArgvString
	450	*/
	451	/@-fcnuse@/
	452	int poptConfigFileToString(FILE fp, /@out@/ char * argstrp, int flags)
	453	/@globals fileSystem @/
	454	/@modifies fp, argstrp, fileSystem @/;
	455	/@=fcnuse@/
	456
cc248aae WD	457	/** \ingroup popt
	458	* Return formatted error string for popt failure.
	459	* @param error popt error
	460	* @return error string
	461	*/
bc93ee84 WD	462	/@observer@/
bc93ee84 WD	463	const char * poptStrerror(const int error)
cc248aae	464	/@/;
cc248aae WD	465
	466	/** \ingroup popt
	467	* Limit search for executables.
	468	* @param con context
	469	* @param path single path to search for executables
	470	* @param allowAbsolute absolute paths only?
	471	*/
bc93ee84	472	/@unused@/
cc248aae WD	473	void poptSetExecPath(poptContext con, const char * path, int allowAbsolute)
	474	/@modifies con @/;
	475
	476	/** \ingroup popt
	477	* Print detailed description of options.
	478	* @param con context
	479	* @param fp ouput file handle
	480	* @param flags (unused)
	481	*/
	482	void poptPrintHelp(poptContext con, FILE * fp, /@unused@/ int flags)
	483	/@globals fileSystem @/
	484	/@modifies fp, fileSystem @*/;
	485
	486	/** \ingroup popt
	487	* Print terse description of options.
	488	* @param con context
	489	* @param fp ouput file handle
	490	* @param flags (unused)
	491	*/
	492	void poptPrintUsage(poptContext con, FILE * fp, /@unused@/ int flags)
	493	/@globals fileSystem @/
	494	/@modifies fp, fileSystem @*/;
	495
	496	/** \ingroup popt
	497	* Provide text to replace default "[OPTION...]" in help/usage output.
	498	* @param con context
	499	* @param text replacement text
	500	*/
	501	/@-fcnuse@/
	502	void poptSetOtherOptionHelp(poptContext con, const char * text)
	503	/@modifies con @/;
	504	/@=fcnuse@/
	505
	506	/** \ingroup popt
	507	* Return argv[0] from context.
	508	* @param con context
	509	* @return argv[0]
	510	*/
bc93ee84 WD	511	/@-fcnuse@/
	512	/@observer@/
	513	const char * poptGetInvocationName(poptContext con)
cc248aae	514	/@/;
bc93ee84	515	/@=fcnuse@/
cc248aae WD	516
	517	/** \ingroup popt
	518	* Shuffle argv pointers to remove stripped args, returns new argc.
	519	* @param con context
	520	* @param argc no. of args
	521	* @param argv arg vector
	522	* @return new argc
	523	*/
	524	/@-fcnuse@/
	525	int poptStrippedArgv(poptContext con, int argc, char ** argv)
	526	/@modifies argv @*/;
	527	/@=fcnuse@/
b348deae	528
bc93ee84 WD	529	/**
	530	* Save a long, performing logical operation with value.
	531	* @warning Alignment check may be too strict on certain platorms.
	532	* @param arg integer pointer, aligned on int boundary.
	533	* @param argInfo logical operation (see POPT_ARGFLAG_*)
	534	* @param aLong value to use
	535	* @return 0 on success, POPT_ERROR_NULLARG/POPT_ERROR_BADOPERATION
	536	*/
	537	/@-incondefs@/
	538	/@unused@/
	539	int poptSaveLong(/@null@/ long * arg, int argInfo, long aLong)
	540	/@modifies arg @*/
	541	/@requires maxSet(arg) >= 0 /\ maxRead(arg) == 0 @/;
	542	/@=incondefs@/
	543
	544	/**
	545	* Save an integer, performing logical operation with value.
	546	* @warning Alignment check may be too strict on certain platorms.
	547	* @param arg integer pointer, aligned on int boundary.
	548	* @param argInfo logical operation (see POPT_ARGFLAG_*)
	549	* @param aLong value to use
	550	* @return 0 on success, POPT_ERROR_NULLARG/POPT_ERROR_BADOPERATION
	551	*/
	552	/@-incondefs@/
	553	/@unused@/
	554	int poptSaveInt(/@null@/ int * arg, int argInfo, long aLong)
	555	/@modifies arg @*/
	556	/@requires maxSet(arg) >= 0 /\ maxRead(arg) == 0 @/;
	557	/@=incondefs@/
	558
cc248aae	559	/@=type@/
b348deae MP	560	#ifdef __cplusplus
	561	}
	562	#endif
62402cb1 MP	563
62402cb1 MP	564	#endif