Command-line arguments and program configuration

Learning objectives

• Explain the roles of argc and argv in a hosted C++ program.
• Validate argument count before reading an argument.
• Parse numeric options and reject overflow or trailing characters.
• Design clear defaults and error messages for a small command-line tool.

Prerequisites: functions, strings, input validation, and compiling programs from a terminal. Review Functions, Strings, Input validation, and Compiler toolchain first. The std::from_chars examples require C++17.

Program entry point parameters

A hosted C++ program can receive command-line arguments through argc and argv. argc is the number of arguments; argv is an array of null-terminated character strings. The first argument is conventionally the program name.

Inspect arguments

#include <iostream>
int main(int argc, char* argv[]) {
    for (int i = 0; i < argc; ++i) std::cout << i << ": " << argv[i] << '\n';
}

For example, running ./app report.txt --verbose typically gives three arguments: the program name, report.txt, and --verbose. Exact formatting of argv[0] is implementation-defined.

Validate before use

#include <charconv>
#include <iostream>
#include <string_view>
int main(int argc, char* argv[]) {
    if (argc != 2) { std::cerr << "Usage: app <count>\n"; return 1; }
    int count{};
    std::string_view text = argv[1];
    auto [end, error] = std::from_chars(text.data(), text.data() + text.size(), count);
    if (error != std::errc{} || end != text.data() + text.size() || count < 0) {
        std::cerr << "count must be a non-negative integer\n"; return 1;
    }
    std::cout << count;
}

std::from_chars is available for integers in C++17. It does not allocate and reports parsing errors explicitly. The code checks that the entire argument was consumed; otherwise input such as 12abc could be partially accepted.

Design a CLI interface

• Show a usage line when arguments are missing or invalid.
• Use clear option names such as --input and --output.
• Reject unknown options rather than silently ignoring them.
• Keep parsing separate from the business logic.
• Do not assume the current working directory is the executable's directory.

Common mistakes

• Reading argv[1] before checking that argc is large enough.
• Assuming every argument is a valid number because it is a C-style string.
• Accepting a numeric prefix and ignoring trailing junk.
• Using std::stoi without handling its exceptions or checking how much input it consumed.

Practice

1. What does argc count?
2. Why must argv strings be validated?
3. Why check that from_chars consumed the full input?

Summary

Command-line arguments make programs automatable. Parse them at the boundary, validate every option, provide usage help, and keep configuration separate from core logic.

References

• cppreference: main function
• cppreference: from_chars