You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.

Skip to main content

NSPR: Command line option processing

NSPR provides a mechanism to process command line options. This facility is similar to that available on many UNIX platforms known as getopt (see UNIX man getopt). The NSPR version of this capability allows processing based on the standard C language main() function definition's argc and argv. There are no modifications to values of those symbols during the processing.

The syntax of the command line is generically as follows:

    > command -abc value naked -xyz
In this example, 'a', 'b', 'c', 'x', 'y' and 'z' are options. "abc" are clustered behind a single '-' as are "xyz". This command line is identical in semantics to
    > command -a -b -c value naked -x -y -z
The string "value" is associated with the option 'c'. The options 'a', 'b', 'x', 'y' and 'z' have no associated values.
The token "naked" is not associated with any option (and is therefore naked). Any number of naked values may be included in the command line. Since they have no known option association, they are position dependent, but none the less, useful.

An object is created by the client to hold the state of the options processing. Sharing that handle with other threads may produce non-deterministic results. Having multiple such state objects, each accessed by a different thread, is supported (though we struggle for a reason why). 

PLOptState *PL_CreateOptState(
    PRIntn argc, char **argv, const char *options);
If the function fails to return a valid handle the reason for the failure will be contained in the calling thread's error structure (see PR_GetError()). A non-NULL return pointer will point to an object of type PLOptState. The pointer will remain valid until it is destroyed by calling PL_DestroyOptState() and is required for all subsequent processing.
argc The number of arguments on the command line. This is the same value as that the C program's main() function argument, argc.
argv The pointer to a vector of strings that represent the arguments provided on the command line. For instance, argv[0] is a string representation of the program's execution name.
options The string that defines the options expected on the command line. All options are single characters and case sensitive. If an option has an associated value, the option identifier must be followed by a ':' in the options string.
Given the example cited earlier for the command line, a complete options list to parse the command line might be written as "ABC:XYZ". The order of specification of the options strings to PL_CreateOptState() is not significant. The order that the options are specified on the command line may be, particularly if one is using naked values. 
typedef struct PLOptState
{
    char option;
    const char *value;
    PLOptionInternal *internal;
} PLOptState;
The object PLOptState not only allows the implementation to record the progress of the processing, it is also used as the area where the majority of the results are made available to the client. The actual value returned from the option processing function only indicates the validity of the values stored in this object.
option The value of the option on the command line just processed. Processing of the command line progresses from left to right. The value of this field will be either one of those specified in the options string of PL_CreateOptState a nul (0) if the option is naked.
value This field contains the option's associated value or NULL if the option has no associated value.
internal A reference to the implementation's private (and opaque) state processing object.
The PL_CreateOptState function returns one of three values from the enumerated byte PLOptStatus. 
typedef enum {PL_OPT_OK, PL_OPT_EOL, PL_OPT_BAD } PLOptStatus;
PL_OPT_OK The processing completed normally.
PL_OPT_EOL All the tokens from the command line have been processed.
PL_OPT_BAD The option is invalid.

Once the options processing has run to completion, the state object allocated by PL_CreateOptState() must be dismissed. That is accomplished by calling DestroyOptState(). 
void PL_DestroyOptState(PLOptState *opt);


Last updated: Tue Mar 10 10:02:19 PST 1998
Copyright © 1998 Netscape Communications Corporation