mp4v2::platform::prog Namespace Reference
mp4v2::platform::prog Namespace Reference

Command-line argument parsing. More...

Classes

struct  Option

Functions

int getOption (int argc, char *const *argv, const char *optstr, const Option *longopts, int *idx)
 Get option character from command line argument list.
int getOptionSingle (int argc, char *const *argv, const char *optstr, const Option *longopts, int *idx)
 Get option character from command line argument list and allow long-options with single-hyphens.

Variables

const char * optarg
int optind
int optopt
int opterr
 Initialized to 1 and may be set to 0 to disable error messages.
int optreset

Detailed Description

Command-line argument parsing.

WARNING: THIS IS A PRIVATE NAMESPACE. NOT FOR PUBLIC CONSUMPTION.

This namespace provides a mechanism to parse command-line arguments and options for executables. It is identical in behavior to getopt_long functions available with many popular posix-platforms such as Darwin, FreeBSD and Linux. Virtually any OS which has getopt_long will adequately document this functionality. However, to avoid symbol ambiguity with the popular posix implementation, the following identifiers have been renamed:

Function Documentation

◆ getOption()

int mp4v2::platform::prog::getOption ( int argc,
char *const * argv,
const char * optstr,
const Option * longopts,
int * idx )

Get option character from command line argument list.

getOption() is similar to posix getopt() but it accepts options in two forms: words and characters. The getOption() function provides a superset of the functionality of getopt(). The getOption() function can be used in two ways. In the first way, every long-option understood by the program has a corresponding short-option, and the Option structure is only used to translate from long-options to short-options. When used in this fashion, getOption() behaves identically to getopt(). This is a good way to add long-option processing to an esxisting program with a minimum of rewriting.

In the second mechanism, a long-option sets a flag in the Option structure structure passed, or will store a pointer to the command line argument in the Option structure passed to it for options that take arguments. Additionally, the long-option's argument may be specified as a single argument with an equal sign, eg:

myprogram --myoption=somevalue

When a long-option is processed, the call to getOption() will return 0. For this reason, long-option processing without shortcuts is not backwards compatible with getopt().

It is possible to combine these methods, providing for long-options processing with short-option equivalents for some options. Less frequently used options would be processed as long-options only.

Parameters
argcnumber of arguments.
argvargument array of strings.
optstrstring containing the following elements: individual characters, and characters followed by a colon to indicate an option argument is to follow. For example, an option string "x" recognizes an option "-x", and an option string "x:" recognizes an option and argument "-x argument".
longoptsarray of Option entries. The last element must be filled with zeroes to indicate end-of-array.
idxIf not NULL, then the integer pointed to it will be set to the index of the long-option relative to longops.
Returns
If the flag field is NULL, val field is returned, which is usually just the corresponding short-option. If flag is not NULL, 0 is returned and val is stored in the location pointed to by flag field. A ':' will be returned if there was a missing option argument. A '?' will be returned if an unknown or ambiguous option was used. A -1 will be returned when the argument list has been exhausted.

◆ getOptionSingle()

int mp4v2::platform::prog::getOptionSingle ( int argc,
char *const * argv,
const char * optstr,
const Option * longopts,
int * idx )

Get option character from command line argument list and allow long-options with single-hyphens.

Behaves identically to getOption() with the exception that long-options may start with '-' in addition to '–'. If an option starting with '-' does not match a long option but does match a single-character option, the single-character option is returned.

Parameters
argcnumber of arguments.
argvargument array of strings.
optstrstring containing the following elements: individual characters, and characters followed by a colon to indicate an option argument is to follow. For example, an option string "x" recognizes an option "-x", and an option string "x:" recognizes an option and argument "-x argument".
longoptsarray of Option entries. The last element must be filled with zeroes to indicate end-of-array.
idxIf not NULL, then the integer pointed to it will be set to the index of the long-option relative to longops.
Returns
If the flag field is NULL, val field is returned, which is usually just the corresponding short-option. If flag is not NULL, 0 is returned and val is stored in the location pointed to by flag field. A ':' will be returned if there was a missing option argument. A '?' will be returned if an unknown or ambiguous option was used. A -1 will be returned when the argument list has been exhausted.

Variable Documentation

◆ optarg

const char* mp4v2::platform::prog::optarg
extern

On return from getOption() or getOptionSingle(), points to an option argument, if it is anticipated.

◆ optind

int mp4v2::platform::prog::optind
extern

On return from getOption() or getOptionSingle(), contains the index to the next argv argument for a subsequent call to getOption() or getOptionSingle(). Initialized to 1 and must be set manually to 1 prior to invoking getOption() or getOptionSingle() to evaluate multiple sets of arguments.

◆ optopt

int mp4v2::platform::prog::optopt
extern

On return from getOption() or getOptionSingle(), saves the last known option character returned by getOption() or getOptionSingle(). On error, contains the character/code of option which caused error.

◆ optreset

int mp4v2::platform::prog::optreset
extern

Must be set to 1 before evaluating the 2nd or each additional set of arguments.