Command-line Argument Parsing with C utility library

Before diving into this article, you should be comfortable with a few C core concepts. You should know how to write, compile, and run C programs using gcc.

If you have ever built a command-line application in C, you know that parsing arguments can be quite a chore. You could parse argv manually, or reach forgetopt() but once your tool grows, with more flags, positional arguments, and help text, things get messy fast.

The GNU C library includes a cleaner, more structured alternative; argp library. The argp library is a powerful, elegant, and standard GNU library for parsing command-line arguments in C. In this article, we’ll explore what argp is, why you should use it, and how to get started building a robust CLI tool with it.

The argp library is one of the most underrated gems in the C ecosystem. it combines power, structure, and simplicity. it is perfect for anyone building modern command-line tools in C.

The argp library extends the capabilities of getopt() by providing built-in help and version output, structured parsing and callbacks, automatic usage text generation, subparsers, and modular command handling. It is an essential part of the root project, meaning it is included by default in most Linux systems. This means you likely already have everything you need to start using argp without any extra installation steps.

Let’s build a simple example to visualize how to use the argp library. We’ll create a program that takes a few command-line arguments and displays them. This will demonstrate the basic structure and parsing capabilities of the library.

Importing Headers

#include <stdlib.h>
#include <stdio.h>
#include <argp.h>

#include <argp.h> includes the main header file for the argp library. It provides access to its functions and data structures. #include <stdio.h> includes the standard input/output library. This provides functions for basic input and output operations. #include <stdlib.h> includes the standard library, providing general utility functions, including memory allocation and conversion functions.

Documentation Strings

static char doc[] = "A sample CLI tool";
static char args_doc[] = "[ARG1] [ARG2]";

doc[] defines a string that serves as a short description of the command-line tool. This text will be used in the help message generated by argp. args_doc[] defines a string that describes the expected command-line arguments. This text will also be included in the help message.

Command-Line Argument Options

static struct argp_option options[] = {
  {"verbose", 'v', 0, 0, "Returns verose output"},
  {"output", 'o', 0, 0, "Returns output to file instead of standard input"},
  {0},
};

options[] variable defines an array of argp_option structures. Each structure represents a command-line option. The first value in the array defines a long option “verbose” (can be used with — verbose) and a short option ‘v’. The 0, 0 part indicates that this option doesn’t require an argument. The last string provides a description of the option for the help message. The second value in the options[] defines a long option “output” and a short option “o.” Similar to the previous option, it doesn’t require an argument and provides a description.

Argument Structure

struct arguments {
  char *args[2];
  int verbose;
  char *output_file;
};

The arguments struct defines a structure to hold the parsed command-line arguments. args[2] can only contain an array of character pointers to store two positional arguments. verbose is an integer flag to indicate whether the verbose option is enabled and output_file is a character pointer to store the name of the output file if the output option is used.

Parsing Options

static error_t parse_opt (int key, char *arg, struct argp_state *state) {
    struct arguments *arguments = state->input;

    switch (key) {
        case 'v':
            arguments->verbose = 1;
            break;
        case 'o':
            arguments->output_file = arg;
            break;
        case ARGP_KEY_ARG:
            if (state->arg_num >= 2)
                argp_usage(state);
            arguments->args[state->arg_num] = arg;
            break;
        case ARGP_KEY_END:
            if (state->arg_num < 2)
                argp_usage(state);
            break;
        default:
            return ARGP_ERR_UNKNOWN;
    }
    return 0;
}

The parse_opt function is the core of the argument parsing process. It takes three arguments: key, arg, and state. This key is an integer representing the identified command-line option, for example, ‘v’ for verbose and ‘o’ for output. The arg argument is a character pointer to the argument value if the option requires one. The state is a pointer to the argp_state structure, which contains information about the parsing process, such as the current argument number.

The function uses a switch statement to handle different options. It goes through the short option name and checks whether it has been defined in the terminal when the program was invoked. Then, it assigns the value it was invoked with to the arguments structure. If the key is v, it sets the verbose flag in the arguments structs to 1, enabling verbose output. If the key is o, it assigns the provided argument to the output_file member of the arguments struct. This stores the name of the file where the output should be directed.

argp also handles positional arguments. It handles it using the CaseARGP_KEY_ARG`in the switch statement. It checks if the number of arguments already parsed (state->arg_num) is greater than the required number of arguments. If so, it callsargp_usage(state)to display the program’s usage message and exit, as it means too many arguments were provided. Otherwise, it stores the current argument (arg) in theargsarray of theargumentsstruct at the index indicated bystate->arg_num`.

The CaseARGP_KEY_END`case is triggered when all command-line arguments have been processed. It checks if fewer than required arguments were provided. If so, it callsargp_usage(state)to display the usage message and exit, as the program expects exactly a number of positional arguments. TheDefaultcase is there If the key doesn’t match any of the defined cases, it returnsARGP_ERR_UNKNOWN` to signal an error.

Finally, the function returns 0 to indicate successful parsing of the option.

Parser

static struct argp argp = {options, parse_opt, args_doc, doc};

This argp structure acts as a configuration blueprint, providing essential details to the argp_parse function. Specifically, it specifies the command line options that the program should recognize. It defines the parse_opt function, which is responsible for interpreting and handling the parsed arguments. It includes args_doc, a description of the expected command-line arguments to be used in the help message. It provides doc which is a brief description of the CLI tool, also used in the help message. It also accepts a fifth argument, but it is mainly used to build CLI programs with subcommands.

Main Function

int main (int argc, char **argv) {
    struct arguments arguments;
    arguments.verbose = 0;
    arguments.output_file = "-";

    argp_parse (&argp, argc, argv, 0, 0, &arguments);

    printf("ARG1 = %s\nARG2 = %s\nOUTPUT_FILE = %s\nVERBOSE = %s\n",
        arguments.args[0], arguments.args[1],
        arguments.output_file,
        arguments.verbose ? "yes" : "no");

  return 0;
}

The main function brings all the pieces together. It first declares and initializes a struct arguments to store the parsed values, setting default values for verbose and output_file. The core of the parsing happens with the argp_parse function. It takes the argp structure (containing all the parsing configurations), the argument count (argc), the argument values (argv), and a pointer to the arguments structure. After argp_parse finishing, the function prints the parsed arguments to the console, demonstrating the values extracted from the command line. Finally, the function returns 0, indicating successful execution. The full code is displayed below.

[embed]

Conclusion

The next time you’re building a C-based CLI tool, don’t settle for getopt() or manually parse the arguments yourself. Take some time to explore argp. Once you start using it, you’ll wonder how you ever managed without it.

Further Reading

The GNU C Library Reference Manual