Data Structures | Defines | Typedefs | Enumerations | Functions | Variables

popt.h File Reference

#include <stdio.h>
Include dependency graph for popt.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of 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...
struct  poptBits_s

Defines

#define POPT_OPTION_DEPTH   10
#define POPT_READFILE_TRIMNEWLINES   1
#define _POPT_BITS_N   1024U
#define _POPT_BITS_M   ((3U * _POPT_BITS_N) / 2U)
#define _POPT_BITS_K   16U
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_LONGLONG   10U
#define POPT_ARG_MAINCALL   16U+11U
#define POPT_ARG_ARGV   12U
#define POPT_ARG_SHORT   13U
#define POPT_ARG_BITSET   16U+14U
#define POPT_ARG_MASK   0x000000FFU
#define POPT_GROUP_MASK   0x0000FF00U
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
#define POPT_ARGFLAG_TOGGLE   0x00200000U
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
#define POPT_ERROR_BADCONFIG   -22
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_spoptItem
 A popt alias or exec argument for poptAddItem().
typedef struct poptContext_spoptContext
typedef struct poptOptionpoptOption
typedef void(* poptCallbackType )(poptContext con, enum poptCallbackReason reason, const struct poptOption *opt, const char *arg, const void *data)
 Table callback prototype.
typedef struct poptBits_spoptBits

Enumerations

enum  poptCallbackReason { POPT_CALLBACK_REASON_PRE = 0, POPT_CALLBACK_REASON_POST = 1, POPT_CALLBACK_REASON_OPTION = 2 }

Functions

poptContext poptFreeContext (poptContext con)
 Destroy context.
poptContext poptGetContext (const char *name, int argc, const char **argv, const struct poptOption *options, unsigned int flags)
 Initialize popt context.
poptContext poptFini (poptContext con)
 Destroy context (alternative implementation).
poptContext poptInit (int argc, const char **argv, const struct poptOption *options, const char *configPaths)
 Initialize popt context (alternative implementation).
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.
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 poptSaneFile (const char *fn)
 Perform sanity checks on a file path.
int poptReadFile (const char *fn, char **bp, size_t *nbp, int flags)
 Read a file into a buffer.
int poptReadConfigFile (poptContext con, const char *fn)
 Read configuration file.
int poptReadConfigFiles (poptContext con, const char *paths)
 Read configuration file(s).
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 poptSaveString (const char ***argvp, unsigned int argInfo, const char *val)
 Add a string to an argv array.
int poptSaveLongLong (long long *arg, unsigned int argInfo, long long aLongLong)
 Save a long long, performing logical operation with value.
int poptSaveLong (long *arg, unsigned int argInfo, long aLong)
 Save a long, performing logical operation with value.
int poptSaveShort (short *arg, unsigned int argInfo, long aLong)
 Save a short integer, performing logical operation with value.
int poptSaveInt (int *arg, unsigned int argInfo, long aLong)
 Save an integer, performing logical operation with value.
int poptBitsAdd (poptBits bits, const char *s)
int poptBitsChk (poptBits bits, const char *s)
int poptBitsClr (poptBits bits)
int poptBitsDel (poptBits bits, const char *s)
int poptBitsIntersect (poptBits *ap, const poptBits b)
int poptBitsUnion (poptBits *ap, const poptBits b)
int poptBitsArgs (poptContext con, poptBits *ap)
int poptSaveBits (poptBits *bitsp, unsigned int argInfo, const char *s)
 Save a string into a bit set (experimental).

Variables

unsigned int _poptBitsN
unsigned int _poptBitsM
unsigned int _poptBitsK

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 poptOptionpoptHelpOptionsI18N

Define Documentation

#define _POPT_BITS_K   16U

Definition at line 691 of file popt.h.

#define _POPT_BITS_M   ((3U * _POPT_BITS_N) / 2U)

Definition at line 690 of file popt.h.

#define _POPT_BITS_N   1024U

Definition at line 689 of file popt.h.

#define POPT_ARG_ARGV   12U

dupe'd arg appended to realloc'd argv array.

Definition at line 39 of file popt.h.

Referenced by getArgDescrip(), poptSaveArg(), and singleOptionDefaultValue().

#define POPT_ARG_BITSET   16U+14U

arg ==> bit set

Definition at line 41 of file popt.h.

Referenced by poptSaveArg().

#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 ==> double

Definition at line 35 of file popt.h.

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

#define POPT_ARG_FLOAT   8U

arg ==> float

Definition at line 34 of file popt.h.

Referenced by getArgDescrip(), poptSaveArg(), 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(), and singleTableHelp().

#define POPT_ARG_INT   2U

arg ==> int

Definition at line 22 of file popt.h.

Referenced by getArgDescrip(), poptSaveArg(), 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(), and itemUsage().

#define POPT_ARG_LONG   3U

arg ==> long

Definition at line 23 of file popt.h.

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

#define POPT_ARG_LONGLONG   10U

arg ==> long long

Definition at line 36 of file popt.h.

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

#define POPT_ARG_MAINCALL   16U+11U

EXPERIMENTAL: return (*arg) (argc, argv)

Definition at line 38 of file popt.h.

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

#define POPT_ARG_MASK   0x000000FFU

Definition at line 43 of file popt.h.

#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_SHORT   13U

arg ==> short

Definition at line 40 of file popt.h.

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

#define POPT_ARG_STRING   1U

arg will be saved as string

Definition at line 21 of file popt.h.

Referenced by getArgDescrip(), poptSaveArg(), 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 59 of file popt.h.

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

#define POPT_ARGFLAG_DOC_HIDDEN   0x40000000U

don't show in help/usage

Definition at line 53 of file popt.h.

#define POPT_ARGFLAG_LOGICALOPS   (POPT_ARGFLAG_OR|POPT_ARGFLAG_AND|POPT_ARGFLAG_XOR)

Definition at line 63 of file popt.h.

#define POPT_ARGFLAG_NAND   0x05000000U

arg will be nand'ed

Definition at line 60 of file popt.h.

#define POPT_ARGFLAG_NOR   0x09000000U

arg will be nor'ed

Definition at line 58 of file popt.h.

#define POPT_ARGFLAG_NOT   0x01000000U

arg will be negated

Definition at line 62 of file popt.h.

#define POPT_ARGFLAG_ONEDASH   0x80000000U

allow -longoption

Definition at line 52 of file popt.h.

#define POPT_ARGFLAG_OPTIONAL   0x10000000U

arg may be missing

Definition at line 55 of file popt.h.

#define POPT_ARGFLAG_OR   0x08000000U

arg will be or'ed

Definition at line 57 of file popt.h.

Referenced by poptArgInfo(), poptSaveInt(), poptSaveLong(), poptSaveLongLong(), poptSaveShort(), and singleOptionHelp().

#define POPT_ARGFLAG_RANDOM   0x00400000U

random value in [1,arg]

Definition at line 72 of file popt.h.

#define POPT_ARGFLAG_SHOW_DEFAULT   0x00800000U

show default value in --help

Definition at line 71 of file popt.h.

#define POPT_ARGFLAG_STRIP   0x20000000U

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

Definition at line 54 of file popt.h.

#define POPT_ARGFLAG_TOGGLE   0x00200000U

permit --[no]opt prefix toggle

Definition at line 73 of file popt.h.

#define POPT_ARGFLAG_XOR   0x02000000U

arg will be xor'ed

Definition at line 61 of file popt.h.

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

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

Definition at line 175 of file popt.h.

#define POPT_AUTOHELP
Value:
{ NULL, '\0', POPT_ARG_INCLUDE_TABLE, poptHelpOptions, \
                        0, "Help options:", NULL },

Definition at line 191 of file popt.h.

#define POPT_BADOPTION_NOALIAS   (1U << 0)

don't go into an alias

Definition at line 110 of file popt.h.

#define POPT_BIT_CLR   (POPT_ARG_VAL|POPT_ARGFLAG_NAND)

clear arg bit(s)

Definition at line 68 of file popt.h.

#define POPT_BIT_SET   (POPT_ARG_VAL|POPT_ARGFLAG_OR)

set arg bit(s)

Definition at line 66 of file popt.h.

#define POPT_CBFLAG_CONTINUE   0x08000000U

continue callbacks with option

Definition at line 86 of file popt.h.

#define POPT_CBFLAG_INC_DATA   0x20000000U

use data from the include line, not the subtable

Definition at line 83 of file popt.h.

#define POPT_CBFLAG_POST   0x40000000U

call the callback after parse

Definition at line 82 of file popt.h.

#define POPT_CBFLAG_PRE   0x80000000U

call the callback before parse

Definition at line 81 of file popt.h.

#define POPT_CBFLAG_SKIPOPTION   0x10000000U

don't callback with option

Definition at line 85 of file popt.h.

#define POPT_CONTEXT_ARG_OPTS   (1U << 4)

return args as options with value 0

Definition at line 120 of file popt.h.

Referenced by poptGetNextOpt().

#define POPT_CONTEXT_KEEP_FIRST   (1U << 1)

pay attention to argv[0]

Definition at line 118 of file popt.h.

Referenced by poptGetContext(), and showHelpIntro().

#define POPT_CONTEXT_NO_EXEC   (1U << 0)

ignore exec expansions

Definition at line 117 of file popt.h.

Referenced by handleExec().

#define POPT_CONTEXT_POSIXMEHARDER   (1U << 2)

options can't follow args

Definition at line 119 of file popt.h.

Referenced by poptGetNextOpt().

#define POPT_ERROR_BADCONFIG   -22

config file failed sanity test

Definition at line 103 of file popt.h.

Referenced by poptStrerror().

#define POPT_ERROR_BADNUMBER   -17

invalid numeric value

Definition at line 98 of file popt.h.

Referenced by poptStrerror().

#define POPT_ERROR_BADOPERATION   -19

mutually exclusive logical operations requested

Definition at line 100 of file popt.h.

Referenced by poptStrerror().

#define POPT_ERROR_BADOPT   -11

unknown option

Definition at line 94 of file popt.h.

Referenced by poptStrerror().

#define POPT_ERROR_BADQUOTE   -15

error in paramter quoting

Definition at line 96 of file popt.h.

Referenced by poptStrerror().

#define POPT_ERROR_ERRNO   -16

errno set, use strerror(errno)

Definition at line 97 of file popt.h.

Referenced by poptStrerror().

#define POPT_ERROR_MALLOC   -21

memory allocation failed

Definition at line 102 of file popt.h.

Referenced by poptStrerror().

#define POPT_ERROR_NOARG   -10

missing argument

Definition at line 93 of file popt.h.

Referenced by poptStrerror().

#define POPT_ERROR_NULLARG   -20

opt->arg should not be NULL

Definition at line 101 of file popt.h.

Referenced by poptBitsIntersect(), poptBitsUnion(), and poptStrerror().

#define POPT_ERROR_OPTSTOODEEP   -13

aliases nested too deeply

Definition at line 95 of file popt.h.

Referenced by poptStrerror().

#define POPT_ERROR_OVERFLOW   -18

number too large or too small

Definition at line 99 of file popt.h.

Referenced by poptStrerror().

#define POPT_GROUP_MASK   0x0000FF00U

Definition at line 44 of file popt.h.

#define POPT_OPTION_DEPTH   10

Definition at line 14 of file popt.h.

Referenced by handleAlias(), and poptStuffArgs().

#define POPT_READFILE_TRIMNEWLINES   1

Definition at line 411 of file popt.h.

Referenced by poptConfigLine(), poptReadConfigFile(), and poptReadFile().

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

Definition at line 194 of file popt.h.


Typedef Documentation

typedef struct poptBits_s * poptBits
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\xrefitem todo 1.
data\xrefitem todo 2.

Definition at line 234 of file popt.h.

typedef struct poptContext_s* poptContext

Definition at line 200 of file popt.h.

typedef struct poptItem_s * poptItem

A popt alias or exec argument for poptAddItem().

typedef struct poptOption* poptOption

Definition at line 207 of file popt.h.


Enumeration Type Documentation

Enumerator:
POPT_CALLBACK_REASON_PRE 
POPT_CALLBACK_REASON_POST 
POPT_CALLBACK_REASON_OPTION 

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

References poptAlias::argc, poptAlias::argv, poptAlias::longName, 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 1654 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, poptOption::shortName, poptOption::val, and xstrdup().

Referenced by poptAddAlias(), and poptConfigLine().

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

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

int poptBitsAdd ( poptBits  bits,
const char *  s 
)

< opt->arg should not be NULL

Definition at line 785 of file popt.c.

References PBM_SET, and poptJlu32lpair().

Referenced by poptBitsArgs(), and poptSaveBits().

int poptBitsArgs ( poptContext  con,
poptBits ap 
)

< opt->arg should not be NULL

Definition at line 897 of file popt.c.

References _poptBitsNew(), poptContext_s::leftovers, poptContext_s::nextLeftover, poptContext_s::numLeftovers, and poptBitsAdd().

int poptBitsChk ( poptBits  bits,
const char *  s 
)

< opt->arg should not be NULL

Definition at line 804 of file popt.c.

References PBM_ISSET, and poptJlu32lpair().

Referenced by poptSaveBits().

int poptBitsClr ( poptBits  bits  ) 

< opt->arg should not be NULL

Definition at line 827 of file popt.c.

References __PBM_IX, and __PBM_NBITS.

int poptBitsDel ( poptBits  bits,
const char *  s 
)

< opt->arg should not be NULL

Definition at line 838 of file popt.c.

References PBM_CLR, and poptJlu32lpair().

Referenced by poptSaveBits().

int poptBitsIntersect ( poptBits ap,
const poptBits  b 
)

< opt->arg should not be NULL

Definition at line 857 of file popt.c.

References __PBM_BITS, __PBM_IX, _poptBitsNew(), and POPT_ERROR_NULLARG.

int poptBitsUnion ( poptBits ap,
const poptBits  b 
)

< opt->arg should not be NULL

Definition at line 877 of file popt.c.

References __PBM_BITS, __PBM_IX, _poptBitsNew(), and POPT_ERROR_NULLARG.

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

< memory allocation failed

Definition at line 131 of file poptparse.c.

References _isspaceptr.

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.

References stpcpy().

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

poptContext poptFini ( poptContext  con  ) 

Destroy context (alternative implementation).

Parameters:
con context
Returns:
NULL always

Definition at line 559 of file poptconfig.c.

References poptFreeContext().

Referenced by poptInit().

poptContext poptFreeContext ( poptContext  con  ) 
const char* poptGetArg ( poptContext  con  ) 

Return next argument.

Parameters:
con context
Returns:
next argument, NULL if no argument is available

Definition at line 1563 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 1579 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 168 of file popt.c.

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

Referenced by poptInit().

const char* poptGetInvocationName ( poptContext  con  ) 

Return argv[0] from context.

Parameters:
con context
Returns:
argv[0]

Definition at line 1760 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

< allow -longoption

< allow -longoption

< 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 may be missing

< arg should take value val

< allow -longoption

< no arg

< arg should take value val

< no arg

Definition at line 1299 of file popt.c.

References _free(), poptOption::arg, optionStackEntry::argb, optionStackEntry::argc, poptOption::argInfo, optionStackEntry::argv, cleanOSE(), poptContext_s::doExec, execCommand(), expandNextArg(), F_ISSET, poptContext_s::finalArgv, poptContext_s::finalArgvAlloced, poptContext_s::finalArgvCount, findOption(), poptContext_s::flags, handleAlias(), handleExec(), invokeCallbacksOPTION(), invokeCallbacksPOST(), poptContext_s::leftovers, LF_ISSET, poptOption::longName, poptContext_s::maincall, optionStackEntry::next, optionStackEntry::nextArg, optionStackEntry::nextCharArg, poptContext_s::numLeftovers, poptContext_s::options, poptContext_s::optionStack, poptContext_s::os, PBM_ISSET, POPT_ARG_NONE, POPT_ARG_VAL, POPT_CONTEXT_ARG_OPTS, POPT_CONTEXT_POSIXMEHARDER, poptArgInfo(), poptArgType, poptSaveArg(), poptSaveInt(), poptStripArg(), poptContext_s::restLeftover, poptOption::shortName, stpcpy(), 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 1553 of file popt.c.

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

poptContext poptInit ( int  argc,
const char **  argv,
const struct poptOption options,
const char *  configPaths 
)

Initialize popt context (alternative implementation).

This routine does poptGetContext() and then poptReadConfigFiles().

Parameters:
argc no. of arguments
argv argument array
options address of popt option table
configPaths colon separated file path(s) to read.
Returns:
initialized popt context (NULL on error).

Definition at line 565 of file poptconfig.c.

References poptFini(), poptGetContext(), and poptReadConfigFiles().

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.

References _isspaceptr, and poptDupArgv().

Referenced by poptConfigLine().

const char* poptPeekArg ( poptContext  con  ) 

Peek at current argument.

Parameters:
con context
Returns:
current argument, NULL if no argument is available

Definition at line 1571 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 663 of file popthelp.c.

References columns_s::cur, columns_s::max, maxArgWidth(), maxColumnWidth(), poptContext_s::options, poptContext_s::otherHelp, POPT_, POPT_fprintf(), 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 884 of file popthelp.c.

References poptContext_s::aliases, 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

< config file failed sanity test

Definition at line 392 of file poptconfig.c.

References _isspaceptr, POPT_READFILE_TRIMNEWLINES, poptConfigLine(), and poptReadFile().

Referenced by poptReadConfigFiles(), and poptReadDefaultConfig().

int poptReadConfigFiles ( poptContext  con,
const char *  paths 
)

Read configuration file(s).

Colon separated files to read, looping over poptReadConfigFile(). Note that an '@' character preceeding a path in the list will also perform additional sanity checks on the file before reading.

Parameters:
con context
paths colon separated file name(s) to read
Returns:
0 on success, POPT_ERROR_BADCONFIG on failure

< config file failed sanity test

Definition at line 445 of file poptconfig.c.

References poptGlob(), poptReadConfigFile(), poptSaneFile(), and xstrdup().

Referenced by poptInit().

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 499 of file poptconfig.c.

References poptContext_s::appName, poptGlob(), poptReadConfigFile(), and stpcpy().

int poptReadFile ( const char *  fn,
char **  bp,
size_t *  nbp,
int  flags 
)

Read a file into a buffer.

Parameters:
fn file name
Return values:
*bp buffer (malloc'd) (or NULL)
*nbp no. of bytes in buffer (including final NUL) (or NULL)
Parameters:
flags 1 to trim escaped newlines return 0 on success

< errno set, use strerror(errno)

< memory allocation failed

Definition at line 159 of file poptconfig.c.

References POPT_READFILE_TRIMNEWLINES.

Referenced by poptConfigLine(), and poptReadConfigFile().

void poptResetContext ( poptContext  con  ) 
int poptSaneFile ( const char *  fn  ) 

Perform sanity checks on a file path.

Parameters:
fn file name
Returns:
0 on OK, 1 on NOTOK.

Definition at line 141 of file poptconfig.c.

Referenced by poptReadConfigFiles().

int poptSaveBits ( poptBits bitsp,
unsigned int  argInfo,
const char *  s 
)

Save a string into a bit set (experimental).

Return values:
*bits bit set (lazily malloc'd if NULL)
Parameters:
argInfo logical operation (see POPT_ARGFLAG_*)
s string to add to bit set
Returns:
0 on success, POPT_ERROR_NULLARG/POPT_ERROR_BADOPERATION

< opt->arg should not be NULL

Definition at line 918 of file popt.c.

References _free(), _poptBitsNew(), poptBitsAdd(), poptBitsChk(), poptBitsDel(), and xstrdup().

Referenced by poptSaveArg().

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

< random value in [1,arg]

< mutually exclusive logical operations requested

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

References LF_ISSET, POPT_ARGFLAG_AND, POPT_ARGFLAG_OR, and POPT_ARGFLAG_XOR.

Referenced by poptGetNextOpt(), and poptSaveArg().

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

< random value in [1,arg]

< mutually exclusive logical operations requested

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

References LF_ISSET, POPT_ARGFLAG_AND, POPT_ARGFLAG_OR, and POPT_ARGFLAG_XOR.

Referenced by poptSaveArg().

int poptSaveLongLong ( long long *  arg,
unsigned int  argInfo,
long long  aLongLong 
)

Save a long 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_*)
aLongLong value to use
Returns:
0 on success, POPT_ERROR_NULLARG/POPT_ERROR_BADOPERATION

< opt->arg should not be NULL

< random value in [1,arg]

< mutually exclusive logical operations requested

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

References LF_ISSET, POPT_ARGFLAG_AND, POPT_ARGFLAG_OR, and POPT_ARGFLAG_XOR.

Referenced by poptSaveArg().

int poptSaveShort ( short *  arg,
unsigned int  argInfo,
long  aLong 
)

Save a short integer, performing logical operation with value.

Warning:
Alignment check may be too strict on certain platorms.
Parameters:
arg short pointer, aligned on short 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

< random value in [1,arg]

< mutually exclusive logical operations requested

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

References LF_ISSET, POPT_ARGFLAG_AND, POPT_ARGFLAG_OR, and POPT_ARGFLAG_XOR.

Referenced by poptSaveArg().

int poptSaveString ( const char ***  argvp,
unsigned int  argInfo,
const char *  val 
)

Add a string to an argv array.

Return values:
*argvp argv array
Parameters:
argInfo (unused)
val string arg to add (using strdup)
Returns:
0 on success, POPT_ERROR_NULLARG/POPT_ERROR_BADOPERATION

< opt->arg should not be NULL

Definition at line 953 of file popt.c.

References optionStackEntry::argc, xrealloc(), and xstrdup().

Referenced by poptSaveArg().

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

< config file failed sanity test

< errno set, use strerror(errno)

Definition at line 1707 of file popt.c.

References POPT_, POPT_ERROR_BADCONFIG, 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 1765 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 1737 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_OPTION_DEPTH, poptDupArgv(), and optionStackEntry::stuffed.


Variable Documentation

unsigned int _poptBitsK

Definition at line 760 of file popt.c.

unsigned int _poptBitsM

Definition at line 758 of file popt.c.

unsigned int _poptBitsN

Definition at line 756 of file popt.c.

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

Definition at line 64 of file popthelp.c.

Auto help table options.

Definition at line 73 of file popthelp.c.

Definition at line 97 of file popthelp.c.


Generated for popt by  doxygen 1.7.1