GNU Long Options Extension

A number of GNU commands like the gcc(1) compiler for example have a large number of options to support. Besides the fact that you can exhaust all possible characters for those options, a user just cannot remember them all. The GNU solution to this problem is the convention of long options.

FreeBSD 3.4 Release includes gcc(1), allowing the following demonstration of a long option:

$ gcc --version
2.7.2.3
$

Long options begin with two hyphens and must be followed by one or more characters. In order to process long options, the GNU function getopt_long(3) must be used.

The GNU getopt_long(3) Function

The getopt_long(3) function will process both the traditional short options and the newer GNU long options. The synopsis for getopt_long(3) is as follows:

#include <getopt.h>

int getopt_long(int argc, char * const argv[],
    const char *optstring,
    const struct option *longopts,
    int *longindex);

The function prototype is almost identical to getopt(3), except for the two new arguments longopts and longindex. The argument longindex points to an integer, where an index value is returned.

Understanding the option Structure

The longopts structure pointer points to the array of option structure entries. The option structure is composed of four members:

• name points to a C string containing the name of the long option, without the leading hyphens.

• has_arg is defined as an integer but used as a Boolean value. It must be zero (false) if there is no argument or non-zero (true) if there is an argument for this option.

• flag either points to an integer or is null.

• val is used in different ways, depending upon how flag is initialized.

Setting Up the option Structure

The last array entry in the option structure array must be initialized with a null pointer for its name member, zero for the has_arg member, a null pointer for the flag member, and zero for the val member. This entry indicates to getopt_long(3) that there are no more entries in that array. Here is an example of two long options defined in the static option structure long_opts[].

static struct option long_opts[] = {
    {  "help", 0, 0, 'h'} ,    /* name, has_arg, flag, val */
    {  "version", 0, 0, 'v'} , /* name, has_arg, flag, val */
    {  0, 0, 0, 0 }
};

Using a Null option.flag Pointer

The members flag and val of the option structure work together as a team. The easiest way to use these is through the following procedure:

Making a Long Option Look Short

A common practice is to set val to the short option letter equivalent of the long option. For example, if a command supports both --help and -h, then option member flag would be set to a null pointer, and val would be set to the ASCII value 'h'. The structure would be initialized as follows:

static struct option long_opts[] = {
    {  "help", 0, 0, 'h'} , /* name, has_arg, flag, val */
    {  0, 0, 0, 0 }
};

Processing when the option.flag Pointer Is Null

When processing the long option --help, the getopt_long(3) function performs the following basic steps:

A C code fragment illustrates the last three steps:

*longindex = x;               /* 4. Return array index */
if ( !long_opts[x].flag )     /* 5. if flag is null then */
    return long_opts[x].val;  /* 6. return 'h'*/

Your options loop within your program is now tricked into thinking the -h option was processed instead, because the value 'h' was returned. This is the easiest way to use long options.

Using a Non-Null option.flag Pointer

When the structure option member flag is a non-null pointer, something different happens. First, examine Listing 9.3.

Code Listing 9.3. A Non-Null option.flag Member

1:    static int cmdopt_v = 0;      /* Initialized to false */
2:    static struct option long_opts[] = {
3:        {  "help", 0, 0, 'h'} ,    /* name, has_arg, flag, val */
4:        {  "version", 0, &cmdopt_v, 1 } ,
5:        {  0, 0, 0, 0 }
6:    } ;

Listing 9.3 shows how the variables and the long_opts[] array are declared. The following points explain the reasoning behind this code:

With the declarations arranged as they are in Listing 9.3, the actions of getopt_long(3) when it processes the --version option can be explained.

Steps 9 and 10 are carried out when the flag member is not null. Step 6 in the list from the "Processing when option.flag Pointer Is Null" section is used when the flag member is null. Note again how getopt_long(3) returns zero in step 10.

The following code fragment summarizes steps 7 through 10 of the procedure:

    *longindex = x;               /* 7. Return array index */
    if ( !long_opts[x].flag )     /* 8. if flag is null */
        return long_opts[x].val;  /*    return val */
    /* Return val via flag ptr */
    *(long_opts[x].flag) = long_opts[x].val; /* 9. Use ptr */
    return 0;                     /* 10. Indicate flag use */
}