manpages

popt.h(3)

src/popt.h(3) Library Functions Manual src/popt.h(3)

NAME

src/popt.h

SYNOPSIS

#include <stdio.h>

Data Structures


struct poptOption
struct poptAlias
A popt alias argument for poptAddAlias(). struct poptItem_s
A popt alias or exec argument for poptAddItem(). struct poptBits_s

Macros


#define POPT_OPTION_DEPTH 10

Arg type identifiers



#define POPT_ARG_NONE 0U
#define POPT_ARG_STRING 1U
#define POPT_ARG_INT 2U
#define POPT_ARG_LONG 3U
#define POPT_ARG_INCLUDE_TABLE 4U
#define POPT_ARG_CALLBACK 5U
#define POPT_ARG_INTL_DOMAIN 6U
#define POPT_ARG_VAL 7U
#define POPT_ARG_FLOAT 8U
#define POPT_ARG_DOUBLE 9U
#define POPT_ARG_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_NOCONTEXT -22
#define POPT_ERROR_BADCONFIG -23


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)
typedef struct poptItem_s * poptItem
A popt alias or exec argument for poptAddItem().

Auto-generated help/usage


#define POPT_AUTOALIAS
#define POPT_AUTOHELP
#define POPT_TABLEEND { NULL, ' ', 0, NULL, 0, NULL, NULL }
#define POPT_READFILE_TRIMNEWLINES 1
#define _POPT_BITS_N 1024U /* estimated population */
#define _POPT_BITS_M ((3U * _POPT_BITS_N) / 2U)
#define _POPT_BITS_K 16U /* no. of linear hash combinations */
enum poptCallbackReason { POPT_CALLBACK_REASON_PRE = 0, POPT_CALLBACK_REASON_POST = 1, POPT_CALLBACK_REASON_OPTION = 2 }
typedef struct poptContext_s * poptContext
typedef struct poptOption * poptOption
typedef void(* poptCallbackType) (poptContext con, enum poptCallbackReason reason, const struct poptOption *opt, const char *arg, const void *data)
Table callback prototype. typedef struct poptBits_s * poptBits
struct poptOption poptAliasOptions []
Empty table marker to enable displaying popt alias/exec options. struct poptOption poptHelpOptions []
Auto help table options. struct poptOption * poptHelpOptionsI18N
unsigned int _poptBitsN
unsigned int _poptBitsM
unsigned int _poptBitsK
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)
Test path/file for config file sanity (regular file, permissions etc) 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).

Macro Definition Documentation

#define _POPT_BITS_K 16U /* no. of linear hash combinations */

Definition at line 574 of file popt.h.

Referenced by _poptBitsNew().

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

Definition at line 573 of file popt.h.

Referenced by _poptBitsNew().

#define _POPT_BITS_N 1024U /* estimated population */

Definition at line 572 of file popt.h.

Referenced by _poptBitsNew().

#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(), singleOptionDefaultValue(), and singleOptionHelp().

#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(), showShortOptions(), singleTableHelp(), and singleTableUsage().

#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(), itemUsage(), and singleTableUsage().

#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(), poptConfigLine(), 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 poptArgInfo(), 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.

Referenced by poptAddAlias(), and poptConfigLine().

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

Referenced by poptArgInfo().

#define POPT_ARGFLAG_ONEDASH 0x80000000U

allow -longoption

Definition at line 52 of file popt.h.

Referenced by poptGetNextOpt().

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






#define
  POPT_AUTOHELP


Value:




                        { NULL, '\0', POPT_ARG_INCLUDE_TABLE, poptHelpOptions, \


                        0, "Help options:", NULL },






Definition at line 175 of file popt.h.






#define
  POPT_BADOPTION_NOALIAS (1U << 0)


don't go into an alias


Definition at line 112 of file popt.h.


Referenced by poptBadOption().






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


Referenced by poptGetNextOpt().






#define
  POPT_CONTEXT_KEEP_FIRST (1U << 1)


pay attention to argv[0]


Definition at line 120 of file popt.h.


Referenced by poptGetContext(), and
  showHelpIntro().






#define
  POPT_CONTEXT_NO_EXEC (1U << 0)


ignore exec expansions


Definition at line 119 of file popt.h.


Referenced by handleExec().






#define
  POPT_CONTEXT_POSIXMEHARDER (1U << 2)


options can't follow args


Definition at line 121 of file popt.h.


Referenced by poptGetContext(), and
    poptGetNextOpt().






#define
  POPT_ERROR_BADCONFIG -23


config file failed sanity test


Definition at line 104 of file popt.h.


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






#define
  POPT_ERROR_BADNUMBER -17


invalid numeric value


Definition at line 98 of file popt.h.


Referenced by poptParseInteger(), poptSaveArg(), and
    poptStrerror().






#define
  POPT_ERROR_BADOPERATION -19


mutually exclusive logical operations requested


Definition at line 100 of file popt.h.


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






#define
  POPT_ERROR_BADOPT -11


unknown option


Definition at line 94 of file popt.h.


Referenced by poptGetNextOpt(), and
  poptStrerror().






#define
  POPT_ERROR_BADQUOTE -15


error in paramter quoting


Definition at line 96 of file popt.h.


Referenced by poptParseArgvString(), and
    poptStrerror().






#define
  POPT_ERROR_ERRNO -16


errno set, use strerror(errno)


Definition at line 97 of file popt.h.


Referenced by execCommand(), poptGlob(),
    poptReadDefaultConfig(), poptReadFile(), and
    poptStrerror().






#define
  POPT_ERROR_MALLOC -21


memory allocation failed


Definition at line 102 of file popt.h.


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






#define
  POPT_ERROR_NOARG -10


missing argument


Definition at line 93 of file popt.h.


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






#define
  POPT_ERROR_NOCONTEXT -22


no context


Definition at line 103 of file popt.h.


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






#define
  POPT_ERROR_NULLARG -20


opt->arg should not be NULL


Definition at line 101 of file popt.h.


Referenced by _poptBitsNew(), poptBitsAdd(),
    poptBitsArgs(), poptBitsChk(), poptBitsClr(),
    poptBitsDel(), poptBitsIntersect(), poptBitsUnion(),
    poptConfigFileToString(), poptSaveBits(),
    poptSaveInt(), poptSaveLong(), poptSaveLongLong(),
    poptSaveShort(), poptSaveString(), and
  poptStrerror().






#define
  POPT_ERROR_OPTSTOODEEP -13


aliases nested too deeply


Definition at line 95 of file popt.h.


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






#define
  POPT_ERROR_OVERFLOW -18


number too large or too small


Definition at line 99 of file popt.h.


Referenced by poptConfigFileToString(),
    poptSaveArg(), and 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 355 of file popt.h.


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






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


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


Todo


Document.


Parameters


data


Todo


Document.


Definition at line 211 of file popt.h.






typedef struct poptContext_s* poptContext


Definition at line 183 of file popt.h.






typedef struct poptItem_s * poptItem


A popt alias or exec argument for poptAddItem().






typedef
  struct poptOption* poptOption


Definition at line 188 of file popt.h.








Enumeration
  Type Documentation




enum
  poptCallbackReason


Enumerator
  





  
POPT_CALLBACK_REASON_PRE
    

  

  
POPT_CALLBACK_REASON_POST
    

  

  
POPT_CALLBACK_REASON_OPTION
    

  




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


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






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


Add alias/exec item to context.


Parameters


con context


newItem alias/exec item to add


flags 0 for alias, 1 for exec


Returns


0 on success


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


References optionStackEntry::argc,
    optionStackEntry::argv, poptItem_s::argv,
    poptContext_s::doExec, poptContext_s::execFail,
    optionStackEntry::next, optionStackEntry::nextCharArg,
    poptContext_s::optionStack, poptContext_s::os, and
    POPT_BADOPTION_NOALIAS.






int
  poptBitsAdd (poptBits bits, const char * s)


< opt->arg should not be NULL


Definition at line 732 of file popt.c.


References _poptBitsK, _poptBitsM, PBM_SET,
    POPT_ERROR_NULLARG, and poptJlu32lpair().


Referenced by poptBitsArgs(), and
  poptSaveBits().






int
  poptBitsArgs (poptContext con, poptBits * ap)


< opt->arg should not be NULL


Definition at line 844 of file popt.c.


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






int
  poptBitsChk (poptBits bits, const char * s)


< opt->arg should not be NULL


Definition at line 751 of file popt.c.


References _poptBitsK, _poptBitsM, PBM_ISSET,
    POPT_ERROR_NULLARG, and poptJlu32lpair().


Referenced by poptSaveBits().






int
  poptBitsClr (poptBits bits)


< opt->arg should not be NULL


Definition at line 774 of file popt.c.


References __PBM_IX, __PBM_NBITS, _poptBitsM,
    and POPT_ERROR_NULLARG.






int
  poptBitsDel (poptBits bits, const char * s)


< opt->arg should not be NULL


Definition at line 785 of file popt.c.


References _poptBitsK, _poptBitsM, PBM_CLR,
    POPT_ERROR_NULLARG, and poptJlu32lpair().


Referenced by poptSaveBits().






int
  poptBitsIntersect (poptBits * ap, const poptBits b)


< opt->arg should not be NULL


Definition at line 804 of file popt.c.


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






int
  poptBitsUnion (poptBits * ap, const poptBits b)


< opt->arg should not be NULL


Definition at line 824 of file popt.c.


References __PBM_BITS, __PBM_IX, _poptBitsM,
    _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:






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, POPT_ERROR_MALLOC,
    POPT_ERROR_NULLARG, and POPT_ERROR_OVERFLOW.






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 POPT_ERROR_MALLOC, POPT_ERROR_NOARG, and
    stpcpy().


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






poptContext poptFini (poptContext con)


Destroy context (alternative implementation).


Parameters


con context


Returns


NULL always


Definition at line 482 of file poptconfig.c.


References poptFreeContext().


Referenced by poptInit().






poptContext poptFreeContext (poptContext con)


Destroy context.


Parameters


con context


Returns


NULL always


Definition at line 1531 of file popt.c.


References _free(), poptContext_s::aliases,
    poptContext_s::appName, poptContext_s::arg_strip,
    poptContext_s::execPath, poptContext_s::execs,
    poptContext_s::finalArgv, poptContext_s::leftovers,
    poptContext_s::numAliases, poptContext_s::numExecs,
    poptContext_s::otherHelp, PBM_FREE, poptFreeItems(),
    and poptResetContext().


Referenced by displayArgs(), and poptFini().






const
  char * poptGetArg (poptContext con)


Return next argument.


Parameters


con context


Returns


next argument, NULL if no argument is available


Definition at line 1486 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 1502 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 155 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::execFail, 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,
    POPT_CONTEXT_POSIXMEHARDER, and xstrdup.


Referenced by poptInit().






const
  char * poptGetInvocationName (poptContext con)


Return argv[0] from context.


Parameters


con context


Returns


argv[0]


Definition at line 1698 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 1225 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_ARGFLAG_ONEDASH,
    POPT_CONTEXT_ARG_OPTS, POPT_CONTEXT_POSIXMEHARDER,
    POPT_ERROR_BADOPERATION, POPT_ERROR_BADOPT,
    POPT_ERROR_NOARG, 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 1476 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 488 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, POPT_ARGV_ARRAY_GROW_DELTA,
    POPT_ERROR_BADQUOTE, POPT_ERROR_MALLOC, 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 1494 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 632 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 851 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


< no context


< config file failed sanity test


Definition at line 338 of file poptconfig.c.


References _isspaceptr, POPT_ERROR_BADCONFIG,
    POPT_ERROR_NOCONTEXT, 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


Definition at line 390 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 433 of file poptconfig.c.


References poptContext_s::appName, POPT_ERROR_ERRNO,
    poptGlob(), poptReadConfigFile(), poptSaneFile(), 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 126 of file poptconfig.c.


References POPT_ERROR_ERRNO, POPT_ERROR_MALLOC, and
    POPT_READFILE_TRIMNEWLINES.


Referenced by poptConfigLine(), and
    poptReadConfigFile().






void
  poptResetContext (poptContext con)


Reinitialize popt context.


Parameters


con context


Definition at line 206 of file popt.c.


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


Referenced by poptFreeContext().






int
  poptSaneFile (const char * fn)


Test path/file for config file sanity (regular file, permissions
    etc)


Parameters


fn file name


Returns


1 on OK, 0 on NOTOK.


Definition at line 111 of file poptconfig.c.


Referenced by poptReadConfigFiles(), and
    poptReadDefaultConfig().






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


References _free(), _poptBitsNew(),
    POPT_ERROR_NULLARG, 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 993 of file popt.c.


References ALIGNOF, LF_ISSET,
    POPT_ARGFLAG_AND, POPT_ARGFLAG_OR, POPT_ARGFLAG_XOR,
    POPT_ERROR_BADOPERATION, POPT_ERROR_NULLARG, and
  seed.


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


References ALIGNOF, LF_ISSET,
    POPT_ARGFLAG_AND, POPT_ARGFLAG_OR, POPT_ARGFLAG_XOR,
    POPT_ERROR_BADOPERATION, POPT_ERROR_NULLARG, and
  seed.


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


References ALIGNOF, LF_ISSET,
    POPT_ARGFLAG_AND, POPT_ARGFLAG_OR, POPT_ARGFLAG_XOR,
    POPT_ERROR_BADOPERATION, POPT_ERROR_NULLARG, and
  seed.


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


References ALIGNOF, LF_ISSET,
    POPT_ARGFLAG_AND, POPT_ARGFLAG_OR, POPT_ARGFLAG_XOR,
    POPT_ERROR_BADOPERATION, POPT_ERROR_NULLARG, and
  seed.


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


References optionStackEntry::argc,
    POPT_ERROR_NULLARG, 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 64 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 888 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)


< no context


Definition at line 1640 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_NOCONTEXT, 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 1703 of file popt.c.


References poptContext_s::arg_strip,
    optionStackEntry::argc, optionStackEntry::argv, 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


< no context


< aliases nested too deeply


Definition at line 1672 of file popt.c.


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








Variable
  Documentation




unsigned
  int _poptBitsK [extern]


Definition at line 712 of file popt.c.


Referenced by _poptBitsNew(), poptBitsAdd(),
    poptBitsChk(), and poptBitsDel().






unsigned
  int _poptBitsM [extern]


Definition at line 711 of file popt.c.


Referenced by _poptBitsNew(), poptBitsAdd(),
    poptBitsChk(), poptBitsClr(), poptBitsDel(),
    poptBitsIntersect(), and poptBitsUnion().






unsigned
  int _poptBitsN [extern]


Definition at line 710 of file popt.c.


Referenced by _poptBitsNew().






struct poptOption poptAliasOptions[] [extern]


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


Definition at line 55 of file popthelp.c.


Referenced by singleTableHelp().






struct poptOption poptHelpOptions[] [extern]


Auto help table options.


Definition at line 62 of file popthelp.c.


Referenced by getArgDescrip(), maxArgWidth(),
    showShortOptions(), singleTableHelp(), and
    singleTableUsage().






struct poptOption* poptHelpOptionsI18N [extern]


Definition at line 82 of file popthelp.c.


Referenced by maxArgWidth(), showShortOptions(),
    singleTableHelp(), and singleTableUsage().








Author


Generated automatically by Doxygen for popt from the source
  code.







  

    Version 1.18
    popt