↑ Software ↑


opt_util - Option Scanning Utilities

The opt_util package handles full-word (possibly abbreviated) command-line options as well as single-letter options, and can also break a string into an argc/argv[] array of arguments. I've used this package on UNIX, VxWorks, VMS, Windows, Nintendo DS, Palm Pilot, ... The package also worked well with Tcl/Tk programs such as my gentle Tcl interpreter server; the Tcl interpreter passes a command's arguments in an argc/argv[] array to the C function that implements the command.

This package does not implement GNU-style dash-dash "long" options. Full-word options can already be abbreviated, so I haven't had a need for single-letter options myself. As far as being able to group together single-letter options, I've only found that useful, out of habit, with tar(1).

This file contains a package of functions used to scan and parse UNIX-style command line arguments. The OPT_UTIL utilities support:

  1. single-letter options; e.g., "-a"
  2. single-letter options expecting arguments; e.g., "-o file"
  3. name options; e.g., "-readonly"
  4. name options with arguments; e.g., "-list file"
  5. redirection of standard input and output on systems that don't support it at the shell level; e.g., "> outputFile"

The scanning algorithm used by the OPT_UTIL functions allows name options to be abbreviated on the command line. For example, the "-list file" name option in (4) above can be entered on the command line as "-l file", "-li file", "-lis file", or "-list file". If the one-character abbreviation of a name conflicts with a single-letter option, the single-letter option takes priority.

The following command line

    % program -a -o objectFile -readonly -list file

would be scanned and parsed as follows using the OPT_UTIL package:

    #include  "opt_util.h"			-- Option scanning definitions.
    char  *argument ;
    int  option ;

    opt_init (argc, argv, 0, "ao:{readonly}{object:}", NULL) ;
    while (option = opt_get (NULL, &argument)) {
        switch (option) {
        case 1:  ... process "-a" option ...
        case 2:  ... process "-o file" option argument ...
        case 3:  ... process "-readonly" option ...
        case 4:  ... process "-list file" option ...
        case NONOPT:
            ... process non-option argument ...
        case OPTERR:
            ... invalid option or missing argument ...

Applications that will scan multiple command lines using the same set of allowable options can cache the original scan context, resetting it for each new command line (represented by a new argc/argv[] set of arguments):

    static  char  *option_list[] = {		-- Command line options.
        "a", "o:", "{readonly}", "{object:}", NULL
    } ;
    static  OptContext  scan = NULL ;
    for (... each new argc/argv[] set of arguments ...) {
        if (scan == NULL)  opt_init (argc, argv, 1, option_list, &scan) ;
        opt_reset (scan, argc, argv) ;
        while (option = opt_get (scan, &argument)) {
            ... process options ...

Note in the example above that the valid command line options are specified in list form rather than in-line.

VxWorks programs can use the OPT_UTIL functions to provide a simple command line invocation consistent between UNIX and VxWorks:

    % program option(s) ...		(UNIX)

    -> sp program, "option(s) ..."	(VxWorks)

The single options string under VxWorks has several advantages over separate positional arguments: (i) it's easier to type in, (ii) it's easier to extend with new options, and (iii) it's more portable. The following code fragment from a program called RPM shows how to declare a main routine expecting command line arguments under both UNIX and VxWorks:

    #ifdef VXWORKS
        int  rpm (char *command_line)
        int  main (int argc, char *argv[])
        ... local variable declarations ...

    #ifdef VXWORKS
        char  **argv ;
        int  argc ;
        opt_create_argv ("rpm", command_line, &argc, &argv) ;

        ... call the other OPT_UTIL functions to parse the argc/argv[] array of arguments ...


Public Procedures

opt_create_argv() - creates an argv[] array of arguments for a command line.
opt_delete_argv() - deletes an argv[] array of arguments.
opt_errors() - enables/disables the display of error messages.
opt_get() - gets the next option (and its argument) from the command line.
opt_index() - returns the index of the current option or its argument.
opt_init() - initializes a command line scan.
opt_name() - returns the name of an option returned by opt_get().
opt_reset() - resets a command line scan.
opt_set() - sets the option/argument index of a command line scan.
opt_term() - terminates a command line scan.

Source Files


(See libgpl for the complete source, including support routines and build files.)

Alex Measday  /  E-mail