# POPT.

## Files

file | findme.c
file | findme.h
file | popt.c
file | popt.h
file | poptconfig.c
file | popthelp.c
file | poptint.h
file | poptparse.c

## Data Structures

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

## Typedefs

typedef poptItem_s * | poptItem
| A popt alias or exec argument for poptAddItem().
typedef poptContext_s * | poptContext
typedef poptOption * | poptOption
typedef void(*) | poptCallbackType (poptContext con, enum poptCallbackReason reason, const struct poptOption *opt, const char *arg, const void *data)
| Table callback prototype.

## Functions

poptContext | poptGetContext (const char *name, int argc, const char **argv, const struct poptOption *options, int flags)
| Initialize popt context.
void | poptResetContext (poptContext con)
| Reinitialize popt context.
int | poptGetNextOpt (poptContext con)
| Return value of next option found.
const char * | poptGetOptArg (poptContext con)
| Return next option argument (if any).
const char * | poptGetArg (poptContext con)
| Return current option's argument.
const char * | poptPeekArg (poptContext con)
| Peek at current option's argument.
const char ** | poptGetArgs (poptContext con)
| Return remaining arguments.
const char * | poptBadOption (poptContext con, int flags)
| Return the option which caused the most recent error.
poptContext | poptFreeContext (poptContext con)
| Destroy context.
int | poptStuffArgs (poptContext con, const char **argv)
| Add arguments to context.
int | poptAddAlias (poptContext con, struct poptAlias alias, int flags)
| Add alias to context.
int | poptAddItem (poptContext con, poptItem newItem, int flags)
| Add alias/exec item to context.
int | poptReadConfigFile (poptContext con, const char *fn)
| Read configuration file.
int | poptReadDefaultConfig (poptContext con, int useEnv)
| Read default configuration from /etc/popt and $HOME/.popt.
int | poptDupArgv (int argc, const char **argv, int *argcPtr, const char ***argvPtr)
| Duplicate an argument array.
int | poptParseArgvString (const char *s, int *argcPtr, const char ***argvPtr)
| Parse a string into an argument array.
const char *const | poptStrerror (const int error)
| Return formatted error string for popt failure.
void | poptSetExecPath (poptContext con, const char *path, int allowAbsolute)
| Limit search for executables.
void | poptPrintHelp (poptContext con, FILE *fp, int flags)
| Print detailed description of options.
void | poptPrintUsage (poptContext con, FILE *fp, int flags)
| Print terse description of options.
void | poptSetOtherOptionHelp (poptContext con, const char *text)
| Provide text to replace default "[OPTION...]" in help/usage output.
const char * | poptGetInvocationName (poptContext con)
| Return argv[0] from context.
int | poptStrippedArgv (poptContext con, int argc, char **argv)
| Shuffle argv pointers to remove stripped args, returns new argc.

## Typedef Documentation

typedef void(*) poptCallbackType(poptContext con, enum poptCallbackReason reason,const struct poptOption *opt,const char *arg,const void *data)

Table callback prototype.

Parameters:

  | con | context
  | reason | reason for callback
  | opt | option that triggered callback
  | arg |

Todo:
  Document.

Parameters:

  | data |

Todo:
  Document.

Definition at line 196 of file popt.h.

typedef struct poptContext_s* poptContext

Definition at line 169 of file popt.h.

typedef struct poptItem_s * poptItem

A popt alias or exec argument for poptAddItem().

typedef struct poptOption* poptOption

Definition at line 175 of file popt.h.

## Function Documentation

int poptAddAlias | ( | poptContext | con,
|  | struct poptAlias | alias,
|  | int | flags |
| ) |  |  |

Add alias to context.

Todo:
  Pass alias by reference, not value.

Deprecated:
  Use poptAddItem instead.

Parameters:

  | con | context
  | alias | alias to add
  | flags | (unused)

Returns:
  0 on success

Definition at line 1054 of file popt.c.

References alloca(), 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
  | item | alias/exec item to add
  | flags | 0 for alias, 1 for exec

Returns:
  0 on success

Definition at line 1072 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().

const char* poptBadOption | ( | poptContext | con,
|  | int | flags |
| ) |  |  |

Return the option which caused the most recent error.

Parameters:

  | con | context

Returns:
  offending option

Definition at line 1116 of file popt.c.

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

Referenced by doSetupMacro(), main(), parseDescription(), parseFiles(), and parseScript().

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

Definition at line 13 of file poptparse.c.

References POPT_ERROR_MALLOC, and POPT_ERROR_NOARG.

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

poptContext poptFreeContext | ( | poptContext | con | ) |

Destroy context.

Parameters:

  | con | context

Returns:
  NULL always

Definition at line 1010 of file popt.c.

References _free(), poptContext_s::aliases, poptContext_s::appName, poptContext_s::arg_strip, optionStackEntry::argb, poptOption::argDescrip, poptItem_s::argv, poptOption::descrip, poptContext_s::execPath, poptContext_s::execs, poptContext_s::finalArgv, poptContext_s::leftovers, poptOption::longName, poptContext_s::numAliases, poptContext_s::numExecs, poptItem_s::option, poptContext_s::os, poptContext_s::otherHelp, PBM_FREE, and poptResetContext().

Referenced by doSetupMacro(), main(), parseDescription(), parseFiles(), and parseScript().

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

Return current option's argument.

Parameters:

  | con | context

Returns:
  option argument, NULL if no more options are available

Definition at line 980 of file popt.c.

References poptContext_s::leftovers, poptContext_s::nextLeftover, and poptContext_s::numLeftovers.

Referenced by main(), parseDescription(), parseFiles(), and parseScript().

const char** poptGetArgs | ( | poptContext | con | ) |

Return remaining arguments.

Parameters:

  | con | context

Returns:
  argument array, terminated with NULL

Definition at line 996 of file popt.c.

References poptContext_s::leftovers, poptContext_s::nextLeftover, and poptContext_s::numLeftovers.

Referenced by main().

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

Initialize popt context.

Parameters:

  | name |
  | argc | no. of arguments
  | argv | argument array
  | options | address of popt option table
  | flags | or'd POPT_CONTEXT_* bits

Returns:
  initialized popt context

Definition at line 148 of file popt.c.

References getenv(), invokeCallbacksPRE(), POPT_CONTEXT_KEEP_FIRST, and POPT_CONTEXT_POSIXMEHARDER.

Referenced by doSetupMacro(), main(), parseDescription(), parseFiles(), and parseScript().

const char* poptGetInvocationName | ( | poptContext | con | ) |

Return argv[0] from context.

Parameters:

  | con | context

Returns:
  argv[0]

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

Definition at line 659 of file popt.c.

References _ABS, _free(), alloca(), poptOption::arg, optionStackEntry::argb, optionStackEntry::argc, poptOption::argInfo, optionStackEntry::argv, cleanOSE(), poptContext_s::doExec, errno, execCommand(), EXIT_FAILURE, expandNextArg(), poptContext_s::finalArgv, poptContext_s::finalArgvAlloced, poptContext_s::finalArgvCount, findOption(), poptContext_s::flags, handleAlias(), handleExec(), invokeCallbacksOPTION(), invokeCallbacksPOST(), poptContext_s::leftovers, poptOption::longName, optionStackEntry::next, optionStackEntry::nextArg, optionStackEntry::nextCharArg, poptContext_s::numLeftovers, poptContext_s::options, poptContext_s::optionStack, poptContext_s::os, PBM_ISSET, POPT_, POPT_ARG_DOUBLE, POPT_ARG_FLOAT, POPT_ARG_INT, POPT_ARG_LONG, POPT_ARG_MASK, POPT_ARG_NONE, POPT_ARG_STRING, POPT_ARG_VAL, POPT_ARGFLAG_ONEDASH, POPT_ARGFLAG_OPTIONAL, POPT_ARGFLAG_STRIP, POPT_CONTEXT_ARG_OPTS, POPT_CONTEXT_POSIXMEHARDER, POPT_ERROR_BADNUMBER, POPT_ERROR_BADOPERATION, POPT_ERROR_BADOPT, POPT_ERROR_NOARG, POPT_ERROR_OVERFLOW, poptSaveInt(), poptSaveLong(), poptStripArg(), poptContext_s::restLeftover, poptOption::shortName, poptOption::val, and xstrdup().

Referenced by doSetupMacro(), main(), parseDescription(), parseFiles(), and parseScript().

const char* poptGetOptArg | ( | poptContext | con | ) |

Return next option argument (if any).

Parameters:

  | con | context

Returns:
  option argument, NULL if no more options are available

Definition at line 968 of file popt.c.

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

Referenced by doSetupMacro(), and main().

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

Definition at line 54 of file poptparse.c.

References alloca(), POPT_ARGV_ARRAY_GROW_DELTA, POPT_ERROR_BADQUOTE, POPT_ERROR_MALLOC, and poptDupArgv().

Referenced by addOrAppendListEntry(), checkPassPhrase(), configLine(), doScript(), doSetupMacro(), ftpGlob(), handlePreambleTag(), ignoreDep(), makeGPGSignature(), makePGPSignature(), parseDescription(), parseFiles(), parseScript(), rpmGlob(), verifyGPGSignature(), and verifyPGPSignature().

const char* poptPeekArg | ( | poptContext | con | ) |

Peek at current option's argument.

Parameters:

  | con | context

Returns:
  option argument

Definition at line 988 of file popt.c.

References poptContext_s::leftovers, poptContext_s::nextLeftover, and poptContext_s::numLeftovers.

Referenced by main(), parseDescription(), parseFiles(), and parseScript().

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

References maxArgWidth(), poptContext_s::options, poptContext_s::otherHelp, POPT_, 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 632 of file popthelp.c.

References poptContext_s::aliases, poptContext_s::execs, itemUsage(), 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

Definition at line 93 of file poptconfig.c.

References alloca(), configLine(), errno, file, POPT_ERROR_ERRNO, and SEEK_END.

Referenced by main(), and poptReadDefaultConfig().

int poptReadDefaultConfig | ( | poptContext | con,
|  | int | useEnv |
| ) |  |  |

Read default configuration from /etc/popt and $HOME/.popt.

Parameters:

  | con | context
  | useEnv | (unused)

Returns:
  0 on success, POPT_ERROR_ERRNO on failure

Definition at line 162 of file poptconfig.c.

References alloca(), poptContext_s::appName, getenv(), and poptReadConfigFile().

Referenced by main().

void poptResetContext | ( | poptContext | con | ) |

Reinitialize popt context.

Parameters:

  | con | context

Definition at line 205 of file popt.c.

References _free(), poptContext_s::arg_strip, optionStackEntry::argb, cleanOSE(), optionStackEntry::currAlias, poptContext_s::doExec, 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 main(), and poptFreeContext().

void poptSetExecPath | ( | poptContext | con,
|  | const char * | path,
|  | int | allowAbsolute |
| ) |  |  |

Limit search for executables.

Parameters:

  | con | context
  | path | single path to search for executables
  | allowAbsolute | absolute paths only?

Definition at line 47 of file popt.c.

References _free(), poptContext_s::execAbsolute, poptContext_s::execPath, and xstrdup().

Referenced by main().

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

References _free(), poptContext_s::otherHelp, and xstrdup().

const char* const poptStrerror | ( | const int | error | ) |

Return formatted error string for popt failure.

Parameters:

  | error | popt error

Returns:
  error string

Definition at line 1128 of file popt.c.

References errno, POPT_, 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().

Referenced by doSetupMacro(), main(), parseDescription(), parseFiles(), and parseScript().

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

Definition at line 1156 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_OPTSTOODEEP, POPT_OPTION_DEPTH, poptDupArgv(), and optionStackEntry::stuffed.

Referenced by main().