opts.c File Reference

Standard command-line options built-in options parsing and validation definitions. More...

#include <stdio.h>
#include <errno.h>
#include <getopt.h>
#include <stdlib.h>
#include <stdarg.h>
#include <libgen.h>
#include <limits.h>
#include <string.h>
#include "rnr/rnrconfig.h"
#include "rnr/pkg.h"
#include "rnr/new.h"
#include "rnr/assoc.h"
#include "rnr/log.h"
#include "rnr/opts.h"

Go to the source code of this file.

Classes
struct	OptsCtl_T

Macros
#define	OPTS_LONGOPT_LOG   "log"
	log long option name
#define	OPTS_LONGOPT_LOGFILE   "logfile"
	log file long option name
#define	OPTS_LONGOPT_LOGNOCOLOR   "log-no-color"
	log with no color option
#define	OPTS_LONGOPT_LOGNOTIME   "log-no-timestamp"
	log no timestamps option
#define	OPTS_RESET_ARGCV(optind, argc, argv)   { argc -= optind; argv += optind; }
	Reset argc,argv to start of non-option command arguments. More...
#define	MAX_FMT_BUF   ((size_t)1024)
	Format buffer size.
#define	HELP_OPT_OVER   30
	opt help desc 1st line indent More...
#define	HELP_OPT_OVER_2   (HELP_OPT_OVER+2)
	opt help desc 2nd line+ indent
#define	HELP_MAX_COL   79
	max help column

Functions
int	HelpIndent (int over)
	Indents (spaces) over, returning number of added indentation. More...
int	HelpPutNL (int over)
	Puts help newline, returning new output column position. More...
static int	HelpPutBuf (int col, int colstart, char buf[], size_t *pbuflen)
	Puts help buffer, returning new output column position. More...
static int	HelpPutStr (int col, int colstart, const char *s)
	Puts help string, returning new output column position. More...
static int	HelpPutC (int col, int colstart, int c)
	Puts help character, returning new output column position. More...
static int	HelpGetC (int col, int colstart, char buf[], size_t bufsiz, size_t *pbuflen, int c)
	Gets help character into local buffer, returning new/same output column position. More...
static int	OptsPrintf (int col, int colstart, const char *sFmtDesc, const char *sPgmName, OptsInfo_T *pOptsInfo)
	Prints formatted description. More...
static void	OptsPrintOpt (const char *argv0, OptsInfo_T *pOptsInfo)
	Prints option syntax and description in standard 'usage' format. More...
static void	OptsHelp (const char *argv0, OptsInfo_T *pOptsInfo, OptsPgmInfo_T *pPgmInfo, bool_t bHasLogging)
	Prints command-line help. More...
static void	OptsVersion (const char *argv0, const PkgInfo_T *pPkgInfo)
	Prints command-line program version string(s). More...
static void	OptsLogSetLevel (const char *argv0, const char *sOptName, char *optarg)
	Set program logging level. More...
static void	OptsLogSetFile (const char *argv0, const char *sOptName, char *optarg)
	Set program logging output file. More...
static void	OptsLogDisableColor (const char *argv0, const char *sOptName, char *optarg)
	Disable program logging in color. More...
static void	OptsLogDisableTimestamp (const char *argv0, const char *sOptName, char *optarg)
	Disable program logging with timestamps. More...
static OptsCtl_T *	OptsNew (OptsInfo_T *pOptsInfo, bool_t bHasLogging)
	Allocate and build short and long options getopt_long() parameters from the provided option info. More...
static void	OptsDelete (OptsCtl_T *pOptsCtl)
	Delete an allocated options control structure. More...
char **	OptsGet (const char *argv0, const PkgInfo_T *pPkgInfo, OptsPgmInfo_T *pPgmInfo, OptsInfo_T *pOptsInfo, bool_t bHasLogging, int *pargc, char *argv[])
	Gets, validates, and sets all command line options. More...
int	OptsCvtArgStr (const char *argv0, const char *sOptName, char *optarg, void *pOptVal)
	Convert options string argument to string. More...
int	OptsCvtArgBool (const char *argv0, const char *sOptName, char *optarg, void *pOptVal)
	Convert options boolean argument to bool_t. More...
int	OptsCvtArgInt (const char *argv0, const char *sOptName, char *optarg, void *pOptVal)
	Convert options integer argument to integer. More...
int	OptsCvtArgFloat (const char *argv0, const char *sOptName, char *optarg, void *pOptVal)
	Convert options float argument to double. More...
int	OptsCvtArgLogLevel (const char *argv0, const char *sOptName, char *optarg, void *pOptVal)
	Convert options string argument to log threshold level. More...
char *	OptsFmtStr (char *buf, size_t buflen, void *pOptVal)
	String option value string formatter. More...
char *	OptsFmtInt (char *buf, size_t buflen, void *pOptVal)
	Integer option value string formatter. More...
char *	OptsFmtFloat (char *buf, size_t buflen, void *pOptVal)
	Float option value string formatter. More...
char *	OptsFmtBool (char *buf, size_t buflen, void *pOptVal)
	Boolean option value string formatter. More...
char *	OptsFmtChar (char *buf, size_t buflen, void *pOptVal)
	Character option value string formatter. More...
char *	OptsFmtLogLevel (char *buf, size_t buflen, void *pOptVal)
	Log Level option value string formatter. More...
void	OptsInvalid (const char *argv0, const char *sFmt,...)
	Invalid option or option argument print and exit. More...

Variables
static Nvp_T	OptsLogLevelTbl []
static int	OptsLogLevel = LOG_LEVEL_DFT
	working log level value More...
static char *	OptsLogFile = LOG_FILENAME_DFT
	working log file value
static bool_t	OptsLogNoColor = false
	working log no color value
static bool_t	OptsLogNoTimestamp = false
	working log no timestamp value
static OptsInfo_T	OptsBuiltIn []
	Built-In Options.

Detailed Description

Standard command-line options built-in options parsing and validation definitions.

LastChangedDate

2014-12-06 13:48:30 -0700 (Sat, 06 Dec 2014)

Rev

3823

Author

Robin Knight (robin.nosp@m..kni.nosp@m.ght@r.nosp@m.oadn.nosp@m.arrow.nosp@m.s.co.nosp@m.m)

Copyright

© 2005-2018. RoadNarrows LLC..
http://www.roadnarrows.com
All Rights Reserved

Definition in file opts.c.

Macro Definition Documentation

#define HELP_OPT_OVER   30

opt help desc 1st line indent

PrettyPrint formats

Definition at line 224 of file opts.c.

Referenced by OptsPrintOpt().

#define OPTS_RESET_ARGCV	(		optind,
			argc,
			argv
	)		{ argc -= optind; argv += optind; }

Reset argc,argv to start of non-option command arguments.

Parameters

optind	Last option index.
argc	Argument count.
argv	Argument vector.

Definition at line 216 of file opts.c.

Referenced by OptsGet().

Function Documentation

static int HelpGetC ( int  col, int  colstart, char  buf[], size_t  bufsiz, size_t *  pbuflen, int  c  )

static

Gets help character into local buffer, returning new/same output column position.

Parameters

col	Current column position.
colstart	Column to start.
buf	[out] Buffer to put.
bufsiz	Buffer maximum size.
pbuflen	[out] Buffer insert point.
c	Help character to get (put into buffer).

Returns

New column position.

Definition at line 324 of file opts.c.

References HelpPutBuf().

Referenced by OptsPrintf().

{
  if( *pbuflen >= bufsiz )
  {
    *pbuflen = bufsiz - 1;
    col = HelpPutBuf(col, colstart, buf, pbuflen);
  }
  else
  {
    buf[*pbuflen] = (char)c;
    *pbuflen += 1;
  }
  return col;
}

int HelpIndent ( int  over )

inline

Indents (spaces) over, returning number of added indentation.

Parameters

over	Number of spaces.

Definition at line 232 of file opts.c.

Referenced by HelpPutNL(), and OptsPrintOpt().

{ return printf("%*s", over, ""); }

static int HelpPutBuf ( int  col, int  colstart, char  buf[], size_t *  pbuflen  )

static

Puts help buffer, returning new output column position.

Parameters

col	Current column position.
colstart	Column to start.
buf	Buffer to output.
pbuflen	[out] Buffer length.

Returns

New column position.

Definition at line 250 of file opts.c.

References HELP_MAX_COL, and HelpPutNL().

Referenced by HelpGetC(), and OptsPrintf().

{
  if( *pbuflen == 0 )
  {
    return col;
  }
  if( (col > colstart) && (col >= (HELP_MAX_COL - *pbuflen)) )
  {
    col = HelpPutNL(colstart);
  }
  buf[*pbuflen] = 0; 
  col += printf("%s", buf); 
  *pbuflen = 0;
  return col;
}

static int HelpPutC ( int  col, int  colstart, int  c  )

static

Puts help character, returning new output column position.

Parameters

col	Current column position.
colstart	Column to start.
c	Help character.

Returns

New column position.

Definition at line 301 of file opts.c.

References HELP_MAX_COL, and HelpPutNL().

Referenced by OptsPrintf().

{
  if( col > HELP_MAX_COL )
  {
    col = HelpPutNL(colstart);
  }
  col += printf("%c", c);
  return col;
}

int HelpPutNL ( int  over )

inline

Puts help newline, returning new output column position.

Parameters

over	Number of spaces.

Definition at line 238 of file opts.c.

References HelpIndent().

Referenced by HelpPutBuf(), HelpPutC(), HelpPutStr(), and OptsPrintf().

{ printf("\n"); return HelpIndent(over); }

static int HelpPutStr ( int  col, int  colstart, const char *  s  )

static

Puts help string, returning new output column position.

Parameters

col	Current column position.
colstart	Column to start.
s	Help string.

Returns

New column position.

Definition at line 275 of file opts.c.

References HELP_MAX_COL, HelpPutNL(), and NULL.

Referenced by OptsPrintf().

{
  int n;

  if( (s == NULL) || (*s == 0) )
  {
    return col;
  }
  n = (int)strlen(s);
  if( (col > colstart) && (col >= (HELP_MAX_COL - n)) )
  {
    col = HelpPutNL(colstart);
  }
  col += printf("%s", s); 
  return col;
}

int OptsCvtArgBool	(	const char *	argv0,
		const char *	sOptName,
		char *	optarg,
		void *	pOptVal
	)

Convert options boolean argument to bool_t.

1 or "true" converts to true.
0 or "false" converts to false.

Note

Function returns integer for derived applications. librnr Opts ignores the return value.

Parameters

	argv0	Command name.
	sOptName	Option name.
	optarg	Parsed option argument to convert (optional).
[out]	pOptVal	Pointer to converted option value.

Default:

true

Exceptions

OPTSBADARG()

Returns

If returns, then returns OK.

Definition at line 1018 of file opts.c.

References OK, and OPTSBADARG.

{
  if( optarg )
  {
    if( !strcmp(optarg, "true") || !strcmp(optarg, "1") )
    {
      *((bool_t *)pOptVal) = true;
    }
    else if( !strcmp(optarg, "false") || !strcmp(optarg, "0") )
    {
      *((bool_t *)pOptVal) = false;
    }
    else
    {
      OPTSBADARG(argv0, sOptName, optarg);
    }
  }
  // optional argument default
  else
  {
    *((bool_t *)pOptVal) = true;
  }

  return OK;
}

int OptsCvtArgFloat	(	const char *	argv0,
		const char *	sOptName,
		char *	optarg,
		void *	pOptVal
	)

Convert options float argument to double.

Accepted format: optionally signed floating-point number.

Note

Function returns integer for derived applications. librnr Opts ignores the return value.

Parameters

	argv0	Command name.
	sOptName	Option name.
	optarg	Parsed option argument to convert (optional).
[out]	pOptVal	Pointer to converted option value.

Default:

1.0

Exceptions

OPTSBADARG()

Returns

If returns, then returns OK.

Definition at line 1109 of file opts.c.

References OK, and OPTSBADARG.

{
  double  optargFloat;

  if( optarg )
  {
    if( sscanf(optarg, "%lf", &optargFloat) != 1 )
    {
      OPTSBADARG(argv0, sOptName, optarg);
    }
    *((double *)pOptVal) = optargFloat;
  }
  // optional argument default
  else
  {
    *((double *)pOptVal) = 1.0;
  }

  return OK;
}

int OptsCvtArgInt	(	const char *	argv0,
		const char *	sOptName,
		char *	optarg,
		void *	pOptVal
	)

Convert options integer argument to integer.

Accepted formats: decimal hexidecimal(0x<hexdigits>) octal(0<octaldigits>).

Note

Function returns integer for derived applications. librnr Opts ignores the return value.

Parameters

	argv0	Command name.
	sOptName	Option name.
	optarg	Parsed option argument to convert (optional).
[out]	pOptVal	Pointer to converted option value.

Default:

1

Exceptions

OPTSBADARG()

Returns

If returns, then returns OK.

Definition at line 1065 of file opts.c.

References OK, and OPTSBADARG.

Referenced by OptsCvtArgLogLevel().

{
  int   optargInt;
  char  *optargEnd;

  if( optarg )
  {
    optargInt = (int)strtol(optarg, &optargEnd, 0);
    if( *optargEnd != 0 )
    {
      OPTSBADARG(argv0, sOptName, optarg);
    }
    *((int *)pOptVal) = optargInt;
  }
  // optional argument default
  else
  {
    *((int *)pOptVal) = 1;
  }

  return OK;
}

int OptsCvtArgLogLevel	(	const char *	argv0,
		const char *	sOptName,
		char *	optarg,
		void *	pOptVal
	)

Convert options string argument to log threshold level.

Format: "off", "error", "diag1", "diag2", "diag3", "diag4", "diag5", or >= 0

Note

Function returns integer for derived applications. librnr Opts ignores the return value.

Parameters

	argv0	Command name.
	sOptName	Option name.
	optarg	Parsed option argument to convert (optional).
[out]	pOptVal	Pointer to converted option value.

Default:

LOG_LEVEL_DFT

Exceptions

OPTSBADARG()

Returns

If returns, then returns OK.

Definition at line 1151 of file opts.c.

References arraysize, LOG_LEVEL_DFT, LOG_LEVEL_OFF, NvpName2Val(), OK, and OptsCvtArgInt().

Referenced by OptsLogSetLevel().

{
  int logLevel;

  if( optarg )
  {
    logLevel = NvpName2Val(OptsLogLevelTbl, arraysize(OptsLogLevelTbl), optarg);

    // assume integer format
    if( logLevel < LOG_LEVEL_OFF )
    {
      OptsCvtArgInt(argv0, sOptName, optarg, &logLevel);
    }
  }
  // optional argument default
  else
  {
    logLevel = LOG_LEVEL_DFT;
  }

  if( logLevel < LOG_LEVEL_OFF )
  {
    logLevel = LOG_LEVEL_OFF;
  }

  *((int *)pOptVal) = logLevel;

  return OK;
}

int OptsCvtArgStr	(	const char *	argv0,
		const char *	sOptName,
		char *	optarg,
		void *	pOptVal
	)

Convert options string argument to string.

Note

Function returns integer for derived applications. librnr Opts ignores the return value.

Parameters

	argv0	Command name.
	sOptName	Option name.
	optarg	Parsed option argument to convert (optional).
[out]	pOptVal	Pointer to converted option value.

Default:

"" (zero-length string)

Returns

If returns, then returns OK.

Definition at line 987 of file opts.c.

References new_strdup(), and OK.

Referenced by OptsGet(), and OptsLogSetFile().

{
  *((char **)pOptVal) = new_strdup(optarg);
  return OK;
}

static void OptsDelete ( OptsCtl_T *  pOptsCtl )

static

Delete an allocated options control structure.

Parameters

pOptsCtl

Options control structure.

Definition at line 832 of file opts.c.

References OptsCtl_T::m_pLongOpts, OptsCtl_T::m_sShortOpts, and NULL.

Referenced by OptsGet().

{
  if( pOptsCtl != NULL )
  {
    delete(pOptsCtl->m_pLongOpts);
    delete(pOptsCtl->m_sShortOpts);
    delete(pOptsCtl);
  }
}

char* OptsFmtBool	(	char *	buf,
		size_t	buflen,
		void *	pOptVal
	)

Boolean option value string formatter.

Parameters

[out]	buf	Output buffer.
	buflen	Buffer length.
	pOptVal	Option value.

Returns

Pointer to start of buf.

Definition at line 1247 of file opts.c.

{
  char  *s;

  if( *((int *)pOptVal) == true )
  {
    s = "true";
  }
  else
  {
    s = "false";
  }
  strncpy(buf, s, buflen);
  buf[buflen-1] = 0;
  return buf;
}

char* OptsFmtChar	(	char *	buf,
		size_t	buflen,
		void *	pOptVal
	)

Character option value string formatter.

Parameters

[out]	buf	Output buffer.
	buflen	Buffer length.
	pOptVal	Option value.

Returns

Pointer to start of buf.

Definition at line 1273 of file opts.c.

{
  buf[0] = *((char *)pOptVal);
  buf[1] = 0;
  return buf;
}

char* OptsFmtFloat	(	char *	buf,
		size_t	buflen,
		void *	pOptVal
	)

Float option value string formatter.

Parameters

[out]	buf	Output buffer.
	buflen	Buffer length.
	pOptVal	Option value.

Returns

Pointer to start of buf.

Definition at line 1231 of file opts.c.

{
  snprintf(buf, buflen, "%f", *((double *)pOptVal));
  buf[buflen-1] = 0;
  return buf;
}

char* OptsFmtInt	(	char *	buf,
		size_t	buflen,
		void *	pOptVal
	)

Integer option value string formatter.

Parameters

[out]	buf	Output buffer.
	buflen	Buffer length.
	pOptVal	Option value.

Returns

Pointer to start of buf.

Definition at line 1215 of file opts.c.

Referenced by OptsFmtLogLevel().

{
  snprintf(buf, buflen, "%d", *((int *)pOptVal));
  buf[buflen-1] = 0;
  return buf;
}

char* OptsFmtLogLevel	(	char *	buf,
		size_t	buflen,
		void *	pOptVal
	)

Log Level option value string formatter.

Parameters

[out]	buf	Output buffer.
	buflen	Buffer length.
	pOptVal	Option value.

Returns

Pointer to start of buf.

Definition at line 1289 of file opts.c.

References LOG_LEVEL_OFF, OptsFmtInt(), and OptsFmtStr().

{
  int   level = *((int *)pOptVal);
  char *off   = "off";

  if( level == LOG_LEVEL_OFF )
  {
    return OptsFmtStr(buf, buflen, &off);
  }
  else
  {
    return OptsFmtInt(buf, buflen, pOptVal);
  }
}

char* OptsFmtStr	(	char *	buf,
		size_t	buflen,
		void *	pOptVal
	)

String option value string formatter.

Parameters

[out]	buf	Output buffer.
	buflen	Buffer length.
	pOptVal	Option value.

Returns

Pointer to start of buf.

Definition at line 1191 of file opts.c.

References NULL.

Referenced by OptsFmtLogLevel().

{
  
  if( (pOptVal == NULL) || (*((char **)pOptVal) == NULL) )
  {
    buf[0] = 0;
  }
  else
  {
    strncpy(buf, *((char **)pOptVal), buflen);
    buf[buflen-1] = 0;
  }
  return buf;
}

char** OptsGet	(	const char *	argv0,
		const PkgInfo_T *	pPkgInfo,
		OptsPgmInfo_T *	pPgmInfo,
		OptsInfo_T *	pOptsInfo,
		bool_t	bHasLogging,
		int *	pargc,
		char *	argv[]
	)

Gets, validates, and sets all command line options.

Parameters

	argv0	(Massaged) program name.
	pPkgInfo	Package info.
	pPgmInfo	Program info.
	pOptsInfo	Program options info.
	bHasLogging	Do [not] include logging options.
[out]	pargc	New non-option argument count.
	argv	Command-line options and arguments. arguments.

Returns

Reposition command-line arguments to start of first non-option comand argument.

Definition at line 861 of file opts.c.

References EC_BAD_OPT, OptsInfo_T::fn_cvt, OptsInfo_T::has_arg, OptsInfo_T::long_opt, OptsCtl_T::m_pLongOpts, OptsCtl_T::m_sShortOpts, NULL, OK, OptsInfo_T::opt_addr, OPTS_LONGOPT_LOG, OPTS_LONGOPT_LOGFILE, OPTS_RESET_ARGCV, OPTS_RVAL_ERROR, OPTS_RVAL_HELP, OPTS_RVAL_LOG, OPTS_RVAL_LOGFILE, OPTS_RVAL_LOGNOCOLOR, OPTS_RVAL_LOGNOTIME, OPTS_RVAL_VERSION, OptsCvtArgStr(), OptsDelete(), OptsHelp(), OptsInvalid(), OptsLogDisableColor(), OptsLogDisableTimestamp(), OptsLogSetFile(), OptsLogSetLevel(), OptsNew(), OptsVersion(), and OptsInfo_T::pvt_retval.

Referenced by init().

{
  OptsCtl_T     *pOptsCtl;
  OptsInfo_T    *p;
  int           argc = *pargc;
  int           c;
  int           option_index;
  bool_t        bHasOpt;

  //
  // Set external getopt_long() variables. N.B. makes OptsGet() non-reentrant.
  //
  optarg  = NULL; // current argument to option
  optind  = 0;    // next index in argv to look for options
  opterr  = 1;    // allow getopt_long() to print error messages
  optopt  = 0;    // current parsed option character

  // build option arguments from info
  pOptsCtl = OptsNew(pOptsInfo, bHasLogging);

  // parse and convert options
  while(true)
  {
    option_index = 0;

    // parse next long/short option
    c = getopt_long(argc, argv, pOptsCtl->m_sShortOpts, pOptsCtl->m_pLongOpts,
                    &option_index);

    // end of option list
    if( c == -1 )
    {
      break;
    }

    // process option
    switch(c)
    {
      case OPTS_RVAL_ERROR:         // -? options error
        OptsInvalid(argv0, "");
        break;
      case OPTS_RVAL_HELP:          // --help
        OptsHelp(argv0, pOptsInfo, pPgmInfo, bHasLogging);
        exit(OK);
        break;
      case OPTS_RVAL_VERSION:       // --version
        OptsVersion(argv0, pPkgInfo);
        exit(OK);
        break;
      case OPTS_RVAL_LOG:           // -l, --log <level>
        OptsLogSetLevel(argv0, OPTS_LONGOPT_LOG, optarg);
        break;
      case OPTS_RVAL_LOGFILE:       // --logfile <file>
        OptsLogSetFile(argv0, OPTS_LONGOPT_LOGFILE, optarg);
        break;
      case OPTS_RVAL_LOGNOCOLOR:    // --log-no-color
        OptsLogDisableColor(argv0, OPTS_LONGOPT_LOG, optarg);
        break;
      case OPTS_RVAL_LOGNOTIME:     // --log-no-timestamp
        OptsLogDisableTimestamp(argv0, OPTS_LONGOPT_LOG, optarg);
        break;
      default:                      // user application option
        bHasOpt = false;
        for(p=pOptsInfo; (p!=NULL) && (p->long_opt!=NULL); ++p)
        {
          if( p->pvt_retval == c )
          {
            bHasOpt = true;

            // user supplied option conversion function
            if( p->fn_cvt != NULL )
            {
              p->fn_cvt(argv0, p->long_opt, optarg, p->opt_addr);
            }
            // default for option w/o argument is boolean true value
            else if( p->has_arg == no_argument )
            {
              *((int *)p->opt_addr) = true;
            }
            // default for option w/ argument is string value
            else
            {
              OptsCvtArgStr(argv0, p->long_opt, optarg, p->opt_addr);
            }
          }
        }
        if( !bHasOpt )
        {
          fprintf(stderr, "Warning: getopt_long() return character code 0x%x\n",
                            c);
          exit(EC_BAD_OPT);
        }
        break;
    }
  }

  OptsDelete(pOptsCtl);

  OPTS_RESET_ARGCV(optind, argc, argv);

  *pargc = argc;

  return argv;
}

static void OptsHelp ( const char *  argv0, OptsInfo_T *  pOptsInfo, OptsPgmInfo_T *  pPgmInfo, bool_t  bHasLogging  )

static

Prints command-line help.

This functions is called to act on –help option.

Parameters

argv0	Program name.
pOptsInfo	Options info.
pPgmInfo	Program info.
bHasLogging	This program does [not] support the logging optoins.

Definition at line 544 of file opts.c.

References OptsPgmInfo_T::diagnostics, OptsPgmInfo_T::long_desc, OptsInfo_T::long_opt, NULL, OPTS_RVAL_HELP, OPTS_RVAL_LOG, OPTS_RVAL_LOGFILE, OptsPrintf(), OptsPrintOpt(), OptsInfo_T::pvt_retval, OptsPgmInfo_T::synopsis, and OptsPgmInfo_T::usage_args.

Referenced by OptsGet().

{
  OptsInfo_T  *p;
  int          col;

  // usage
  col = printf("Usage: %s [OPTIONS] ", argv0);
  if( (pPgmInfo != NULL) && (pPgmInfo->usage_args != NULL) )
  {
    col = OptsPrintf(col, 2, pPgmInfo->usage_args, argv0, NULL);
  }

  // synopsis
  printf("\n");
  if( (pPgmInfo != NULL) && (pPgmInfo->synopsis != NULL) )
  {
    col = OptsPrintf(0, 0, pPgmInfo->synopsis, argv0, NULL);
    printf("\n");
  }

  // options
  printf(
"\n"
"Mandatory arguments to long options are also mandatory for short options.\n");

  if( pOptsInfo != NULL )
  {
    for(p=pOptsInfo; p->long_opt!=NULL; ++p)
    {
      OptsPrintOpt(argv0, p);
    }
  }

  for(p=OptsBuiltIn; p->long_opt!=NULL; ++p)
  {
    if( !bHasLogging && 
        ((p->pvt_retval == OPTS_RVAL_LOG)
         || (p->pvt_retval == OPTS_RVAL_LOGFILE)) )
    {
      continue;
    }
    if( p->pvt_retval == OPTS_RVAL_HELP )
    {
      printf("\n");
    }
    OptsPrintOpt(argv0, p);
  }

  // long description
  if( (pPgmInfo != NULL) && (pPgmInfo->long_desc != NULL) )
  {
    printf("\n");
    col = OptsPrintf(0, 0, pPgmInfo->long_desc, argv0, NULL);
    printf("\n");
  }

  // diagnostics
  if( (pPgmInfo != NULL) && (pPgmInfo->diagnostics != NULL) )
  {
    printf("\n");
    printf("DIAGNOSTICS:\n");
    col = OptsPrintf(0, 0, pPgmInfo->diagnostics, argv0, NULL);
    printf("\n");
  }
}

void OptsInvalid	(	const char *	argv0,
		const char *	sFmt,
			...
	)

Invalid option or option argument print and exit.

Parameters

argv0	Program name.
sFmt	Error format string.
...	Variable arguments to format string.

Note

The function terminates process with exit status EC_BAD_OPT(2).

Definition at line 1313 of file opts.c.

References EC_BAD_OPT, MAX_FMT_BUF, and NULL.

Referenced by OptsGet().

{
  va_list ap;
  char    fmtbuf[MAX_FMT_BUF];

  if( (sFmt != NULL) && (*sFmt != 0) )
  {
    snprintf(fmtbuf, MAX_FMT_BUF, "%s: %s\n", argv0, sFmt);
    fmtbuf[MAX_FMT_BUF-1] = 0;
    va_start(ap, sFmt);
    vfprintf(stderr, fmtbuf, ap); 
    va_end(ap);
  }
  fprintf(stderr, "Try '%s --help' for more information.\n", argv0);
  exit(EC_BAD_OPT);
}

static void OptsLogDisableColor ( const char *  argv0, const char *  sOptName, char *  optarg  )

static

Disable program logging in color.

This function is called to act on the –log-no-color option.

Parameters

argv0	Program name.
sOptName	Long option name.
optarg	Long option argument (from getopt_long(3)).

Definition at line 684 of file opts.c.

References LOG_SET_COLOR_ENABLE().

Referenced by OptsGet().

{
#ifdef LOG
  LOG_SET_COLOR_ENABLE(false);
#endif // LOG
}

static void OptsLogDisableTimestamp ( const char *  argv0, const char *  sOptName, char *  optarg  )

static

Disable program logging with timestamps.

This function is called to act on the –log-no-timestamp option.

Parameters

argv0	Program name.
sOptName	Long option name.
optarg	Long option argument (from getopt_long(3)).

Definition at line 702 of file opts.c.

References LOG_SET_TIMESTAMP_ENABLE().

Referenced by OptsGet().

{
#ifdef LOG
  LOG_SET_TIMESTAMP_ENABLE(false);
#endif // LOG
}

static void OptsLogSetFile ( const char *  argv0, const char *  sOptName, char *  optarg  )

static

Set program logging output file.

This function is called to act on the –logfile <file> option.

Parameters

argv0	Program name.
sOptName	Long option name.
optarg	Long option argument (from getopt_long(3)).

Definition at line 664 of file opts.c.

References LOG_SET_LOGFILE(), and OptsCvtArgStr().

Referenced by OptsGet().

{
#ifdef LOG
  char *sFileName;

  OptsCvtArgStr(argv0, sOptName, optarg, &sFileName);
  LOG_SET_LOGFILE(sFileName);
#endif // LOG
}

static void OptsLogSetLevel ( const char *  argv0, const char *  sOptName, char *  optarg  )

static

Set program logging level.

This function is called to act on the –log <level> option.

Parameters

argv0	Program name.
sOptName	Long option name.
optarg	Long option argument (from getopt_long(3)).

Definition at line 644 of file opts.c.

References LOG_SET_THRESHOLD(), and OptsCvtArgLogLevel().

Referenced by OptsGet().

{
#ifdef LOG
  int level;

  OptsCvtArgLogLevel(argv0, sOptName, optarg, &level);
  LOG_SET_THRESHOLD(level);
#endif // LOG
}

static OptsCtl_T* OptsNew ( OptsInfo_T *  pOptsInfo, bool_t  bHasLogging  )

static

Allocate and build short and long options getopt_long() parameters from the provided option info.

Parameters

pOptsInfo	Options info table.
bHasLogging	This program does [not] support the logging optoins.

Returns

New options control structure.

Definition at line 718 of file opts.c.

References arraysize, OptsInfo_T::has_arg, OptsInfo_T::long_opt, OptsCtl_T::m_pLongOpts, OptsCtl_T::m_sShortOpts, NEW, NULL, OPTS_LONGOPT_LOG, OPTS_LONGOPT_LOGFILE, OPTS_NO_SHORT, OPTS_RVAL_USER, OptsInfo_T::pvt_retval, and OptsInfo_T::short_opt.

Referenced by OptsGet().

{
  size_t         n;
  struct option *pLongOpts, *p;
  OptsInfo_T    *q;
  char          *sShortOpts, *s;
  OptsCtl_T     *pOptsCtl;

  // count the number of options
  for(n=0; pOptsInfo[n].long_opt!=NULL; ++n);   // user

  n += arraysize(OptsBuiltIn) - 1;

  // allocate memory
  pLongOpts   = new(sizeof(struct option)*(n+1)); // include null
  sShortOpts  = new(sizeof(char)*(n*3+1));        // include null

  //
  // Make Built-In long and short option arguments to getopt_long()
  //
  for(p=pLongOpts, s=sShortOpts, q=OptsBuiltIn; q->long_opt!=NULL; ++q)
  {
    // ignore logging options
    if( !bHasLogging 
        && (!strcmp(q->long_opt, OPTS_LONGOPT_LOG) 
            || !strcmp(q->long_opt, OPTS_LONGOPT_LOGFILE)) )
    {
      continue;
    }

    // long option also has corresponding short option
    if( q->short_opt != OPTS_NO_SHORT )
    {
      *s++ = (char)(q->short_opt);
      if( q->has_arg != no_argument )
      {
        *s++ = ':';
      }
      if( q->has_arg == optional_argument )
      {
        *s++ = ':';
      }
      
      // check return value must be an ascii characater
      if( q->pvt_retval != q->short_opt )
      {
        fprintf(stderr,
            "Warning: Built-in option pvt_retval 0x%x != short_opt '%c'\n",
            q->pvt_retval, q->short_opt);
      }
    }

    // long option
    p->name     = q->long_opt;
    p->has_arg  = q->has_arg;
    p->flag     = NULL;
    p->val      = q->pvt_retval;
    p++;
  }
  
  //
  // Make User-Defined long and short option arguments to getopt_long()
  //
  for(n=0, q=pOptsInfo; q->long_opt!=NULL; ++n, ++q)
  {
    // long option only
    if( q->short_opt == OPTS_NO_SHORT )
    {
      q->pvt_retval  = OPTS_RVAL_USER + (int)n;
    }
    // long option also has corresponding short option
    else
    {
      *s++ = (char)(q->short_opt);
      if( q->has_arg != no_argument )
      {
        *s++ = ':';
      }
      if( q->has_arg == optional_argument )
      {
        *s++ = ':';
      }
      q->pvt_retval  = q->short_opt;
    }

    // long option
    p->name     = q->long_opt;
    p->has_arg  = q->has_arg;
    p->flag     = NULL;
    p->val      = q->pvt_retval;
    p++;
  }

  // end of long options
  p->name     = NULL;
  p->has_arg  = no_argument;
  p->flag     = NULL;
  p->val      = 0;

  // end of short options string
  *s = 0;

  pOptsCtl = NEW(OptsCtl_T);
  pOptsCtl->m_pLongOpts   = pLongOpts;
  pOptsCtl->m_sShortOpts  = sShortOpts;

  return pOptsCtl;
}

static int OptsPrintf ( int  col, int  colstart, const char *  sFmtDesc, const char *  sPgmName, OptsInfo_T *  pOptsInfo  )

static

Prints formatted description.

Formatting Directives:

The description argumnet sFmtDesc may contain the following formatting directives:
P - print program name (argv0)
L - print name of Long argument
S - print name of Short argument
A - print name of option Argument
D - print value of Default
%% - print %

Parameters

col	Current column position.
colstart	Column to start.
sFmtDesc	Formatted description string.
sPgmName	Program name (argv0).
pOptsInfo	Options info.

Returns

New column position.

Definition at line 362 of file opts.c.

References OptsInfo_T::arg_name, HelpGetC(), HelpPutBuf(), HelpPutC(), HelpPutNL(), HelpPutStr(), LOGERROR, OptsInfo_T::long_opt, NULL, OPTS_NO_SHORT, OptsInfo_T::pvt_opt_dft, and OptsInfo_T::short_opt.

Referenced by OptsHelp(), and OptsPrintOpt().

{
  char        buf[1028];
  size_t      buflen = 0;
  const char  *s;

  for(s=sFmtDesc; s && *s; ++s)
  {
    switch( *s )
    {
      case '\n':
        col = HelpPutBuf(col, colstart, buf, &buflen);
        col = HelpPutNL(colstart);
        break;
      case ' ':
      case '\t':
        col = HelpPutBuf(col, colstart, buf, &buflen);
        col = HelpPutC(col, colstart, ' ');
        break;
      case '%':
        ++s;
        switch(*s)
        {
          case 'P':
            if( sPgmName != NULL )
            {
              col = HelpPutBuf(col, colstart, buf, &buflen);
              col = HelpPutStr(col, colstart, sPgmName);
            }
            break;
          case 'L':
            if((pOptsInfo != NULL) && (pOptsInfo->long_opt != NULL))
            {
              col = HelpPutBuf(col, colstart, buf, &buflen);
              col = HelpPutStr(col, colstart, pOptsInfo->long_opt);
            }
            break;
          case 'S':
            if((pOptsInfo != NULL) && (pOptsInfo->short_opt != OPTS_NO_SHORT))
            {
              col = HelpGetC(col, colstart, buf, sizeof(buf), &buflen,
                              pOptsInfo->short_opt);
            }
            break;
          case 'A':
            if((pOptsInfo != NULL) && (pOptsInfo->arg_name != NULL))
            {
              col = HelpPutBuf(col, colstart, buf, &buflen);
              col = HelpPutStr(col, colstart, pOptsInfo->arg_name);
            }
            break;
          case 'D':
            if((pOptsInfo != NULL) && (pOptsInfo->pvt_opt_dft != NULL))
            {
              col = HelpPutBuf(col, colstart, buf, &buflen);
              col = HelpPutStr(col, colstart, pOptsInfo->pvt_opt_dft);
            }
            break;
          case '%':
            col = HelpGetC(col, colstart, buf, sizeof(buf), &buflen, *s);
            break;
          default:
            --s; 
            LOGERROR("Invalid print directive: '%.2s'", s);
            break;
        }
        break;
      default:
        col = HelpGetC(col, colstart, buf, sizeof(buf), &buflen, *s);
        break;
    }
  }

  // the last word
  if( buflen > 0 )
  {
    col = HelpPutBuf(col, colstart, buf, &buflen);
  }

  return col;
}

static void OptsPrintOpt ( const char *  argv0, OptsInfo_T *  pOptsInfo  )

static

Prints option syntax and description in standard 'usage' format.

Parameters

argv0	Program name.
pOptsInfo	Options info.

Returns

New column position.

Definition at line 456 of file opts.c.

References OptsInfo_T::arg_name, OptsInfo_T::fn_fmt, OptsInfo_T::has_arg, OptsInfo_T::has_default, HELP_OPT_OVER, HELP_OPT_OVER_2, HelpIndent(), OptsInfo_T::long_opt, NULL, OptsInfo_T::opt_addr, OptsInfo_T::opt_desc, OPTS_NO_SHORT, OptsPrintf(), OptsInfo_T::pvt_opt_dft, and OptsInfo_T::short_opt.

Referenced by OptsHelp().

{
  char        buf[1028], buf2[256];
  size_t      buflen = sizeof(buf), buflen2 = sizeof(buf2);
  int         col;

  // indent
  col = snprintf(buf, buflen, "  ");

  // short option
  if( pOptsInfo->short_opt != OPTS_NO_SHORT )
  {
    col += snprintf(buf+col, buflen-(size_t)col, "-%c", pOptsInfo->short_opt);
  }
  else
  {
    col += snprintf(buf+col, buflen-(size_t)col, "  ");
  }

  // long option
  if( pOptsInfo->long_opt != NULL )
  {
    col += snprintf(buf+col, buflen-(size_t)col, "%s--%s", 
                    (pOptsInfo->short_opt != OPTS_NO_SHORT? ", ": "  "),
                    pOptsInfo->long_opt);
  }

  // option argument name
  if( (pOptsInfo->has_arg != no_argument) && 
      (pOptsInfo->arg_name != NULL) )
  {
    col += snprintf(buf+col, buflen-(size_t)col, "%s%s", 
                    (pOptsInfo->long_opt != NULL? "=": " "),
                    pOptsInfo->arg_name);

  }

  // print option keyword(s) syntax
  buf[sizeof(buf)-1] = 0;
  printf("%s", buf);
  buflen = 0;

  // scoot over to start of description column
  if( col > HELP_OPT_OVER )
  {
    printf("\n");
    col = 0;
  }
  HelpIndent(HELP_OPT_OVER-col);
  col = HELP_OPT_OVER;

  // option default value string
  if( pOptsInfo->has_default
      && (pOptsInfo->fn_fmt != NULL)
      && (pOptsInfo->opt_addr != NULL) )
  {
    pOptsInfo->pvt_opt_dft = 
      pOptsInfo->fn_fmt(buf2, buflen2, pOptsInfo->opt_addr);
  }
  else
  {
    pOptsInfo->pvt_opt_dft = NULL;
  }

  // print description
  col = OptsPrintf(col, HELP_OPT_OVER_2, pOptsInfo->opt_desc, argv0,
                   pOptsInfo);

  printf("\n");

  // print default value
  if( pOptsInfo->pvt_opt_dft != NULL )
  {
    HelpIndent(HELP_OPT_OVER_2);
    printf("DEFAULT: %s\n", pOptsInfo->pvt_opt_dft); 
  }
}

static void OptsVersion ( const char *  argv0, const PkgInfo_T *  pPkgInfo  )

static

Prints command-line program version string(s).

This functions is called to act on –version option.

Parameters

argv0	Program name.
pPkgInfo	Package info.

Definition at line 621 of file opts.c.

References PkgInfo_T::m_sPkgAuthors, PkgInfo_T::m_sPkgDate, PkgInfo_T::m_sPkgDisclaimer, PkgInfo_T::m_sPkgName, PkgInfo_T::m_sPkgOwners, PkgInfo_T::m_sPkgTimeStamp, and PkgInfo_T::m_sPkgVersion.

Referenced by OptsGet().

{
  printf(
"%s (package %s-%s %s)\n" 
"Written by %s\n\n"
"Copyright (C) %s %s\n"
"%s\n",
    argv0,
    pPkgInfo->m_sPkgName, pPkgInfo->m_sPkgVersion, pPkgInfo->m_sPkgTimeStamp,
    pPkgInfo->m_sPkgAuthors,
    pPkgInfo->m_sPkgDate, pPkgInfo->m_sPkgOwners,
    pPkgInfo->m_sPkgDisclaimer);
}

Variable Documentation

int OptsLogLevel = LOG_LEVEL_DFT

static

working log level value

Built-in logging option working variables.

Definition at line 105 of file opts.c.

Nvp_T OptsLogLevelTbl[]

static

Initial value:

=
{
  {"nosym", -1},
  {"off",   LOG_LEVEL_OFF},
  {"error", LOG_LEVEL_ERROR},
  {"diag1", LOG_LEVEL_DIAG1},
  {"diag2", LOG_LEVEL_DIAG2},
  {"diag3", LOG_LEVEL_DIAG3},
  {"diag4", LOG_LEVEL_DIAG4},
  {"diag5", LOG_LEVEL_DIAG5}
}

Name-Value Pair table of names to log levels.

Definition at line 72 of file opts.c.