Output

The Argtable3 library provides a versatile API for formatting and printing command-line argument information. These functions are designed to help developers generate user-friendly output, such as usage instructions, error messages, and detailed glossaries for command-line applications.

The output API simplifies the process of presenting argument details in a structured and readable format. It supports various output styles, including concise syntax descriptions, verbose usage instructions, and GNU-style glossaries. Additionally, the API provides functions for printing errors and formatting text dynamically.

Key Features

  • Option Printing: Use arg_print_option and arg_print_option_ds to print individual command-line options in a structured format.

  • Syntax Descriptions: Functions like arg_print_syntax, arg_print_syntax_ds, arg_print_syntaxv, and arg_print_syntaxv_ds generate concise or verbose usage syntax for commands.

  • Glossary Generation: Create detailed glossaries of command-line arguments using arg_print_glossary, arg_print_glossary_ds, arg_print_glossary_gnu, and arg_print_glossary_gnu_ds.

  • Error Reporting: Print error messages with arg_print_errors and arg_print_errors_ds to help users identify and resolve issues with their input.

  • Custom Formatting: Use arg_print_formatted to dynamically format and print text with custom margins and alignment.

This API is designed to enhance the user experience by providing clear and informative output for command-line applications. Below is a detailed reference for each function in the output API.

API

void arg_print_option(FILE *fp, const char *shortopts, const char *longopts, const char *datatype, const char *suffix)

Prints a formatted command-line option specification to a file stream.

The arg_print_option function generates a formatted representation of a command-line option, including its short options, long options, data type, and an optional suffix. This is useful for displaying option syntax in help messages, usage output, or documentation.

The formatted option is written to the specified file stream (fp). You can control the appearance of the option specification, making it easy to integrate with custom help or documentation systems.

Example usage: 

// Print option to stdout
arg_print_option(stdout, "h", "help", NULL, NULL);

Parameters:

  • fp – Output file stream to write to (e.g., stdout or stderr).

  • shortopts – String of short option characters (e.g., "h" for -h).

  • longopts – String of long option names, comma-separated (e.g., "help" for --help).

  • datatype – String describing the expected data type (e.g., "<file>").

  • suffix – Optional string to append after the option specification.

void arg_print_option_ds(arg_dstr_t ds, const char *shortopts, const char *longopts, const char *datatype, const char *suffix)

Prints a formatted command-line option specification to a dynamic string.

The arg_print_option_ds function generates a formatted representation of a command-line option, including its short options, long options, data type, and an optional suffix. This is useful for displaying option syntax in help messages, usage output, or documentation that is built using dynamic string buffers.

The formatted option is written to the specified dynamic string object (arg_dstr_t). You can control the appearance of the option specification, making it easy to integrate with custom help or documentation systems that require string-based output.

Example usage: 

// Print option to a dynamic string
arg_dstr_t ds = arg_dstr_create();
arg_print_option_ds(ds, "v", "verbose", "<level>", NULL);
printf("%s", arg_dstr_cstr(ds));
arg_dstr_destroy(ds);

Parameters:

  • ds – Dynamic string object to write to.

  • shortopts – String of short option characters (e.g., "h" for -h).

  • longopts – String of long option names, comma-separated (e.g., "help" for --help).

  • datatype – String describing the expected data type (e.g., "<file>").

  • suffix – Optional string to append after the option specification.

void arg_print_syntax(FILE *fp, void **argtable, const char *suffix)

Prints a compact, single-line command-line syntax summary to a file stream.

The arg_print_syntax function generates a concise, single-line usage summary for the command-line options and arguments defined in the argument table. This summary is useful for displaying quick usage information to users, such as in the output of a --help or usage message.

The formatted syntax summary is written to the specified file stream (fp). You can append a custom suffix string to the end of the summary, for example, to indicate positional arguments.

Example usage: 

// Print compact syntax summary to stdout
arg_print_syntax(stdout, argtable, "[FILES...]");

Parameters:

  • fp – Output file stream to write to (e.g., stdout or stderr).

  • argtable – Array of argument table structs describing the available options and arguments.

  • suffix – String to append at the end of the syntax summary (e.g., for positional arguments).

void arg_print_syntax_ds(arg_dstr_t ds, void **argtable, const char *suffix)

Prints a compact, single-line command-line syntax summary to a dynamic string.

The arg_print_syntax_ds function generates a concise, single-line usage summary for the command-line options and arguments defined in the argument table. This summary is useful for displaying quick usage information to users, such as in the output of a --help or usage message, and is written to a dynamic string object (arg_dstr_t).

You can append a custom suffix string to the end of the summary, for example, to indicate positional arguments.

Example usage: 

// Print compact syntax summary to a dynamic string
arg_dstr_t ds = arg_dstr_create();
arg_print_syntax_ds(ds, argtable, "[FILES...]");
printf("%s", arg_dstr_cstr(ds));
arg_dstr_destroy(ds);

Parameters:

  • ds – Dynamic string object to write to.

  • argtable – Array of argument table structs describing the available options and arguments.

  • suffix – String to append at the end of the syntax summary (e.g., for positional arguments).

void arg_print_syntaxv(FILE *fp, void **argtable, const char *suffix)

Prints a verbose, multi-line command-line syntax summary to a file stream.

The arg_print_syntaxv function generates a detailed, multi-line usage summary for the command-line options and arguments defined in the argument table. This verbose style provides more clarity than the compact single-line form, making it easier for users to understand complex command-line interfaces.

The formatted syntax summary is written to the specified file stream (fp). You can append a custom suffix string to the end of the summary, for example, to indicate positional arguments.

Example usage: 

// Print verbose syntax summary to stdout
arg_print_syntaxv(stdout, argtable, "[FILES...]");

Parameters:

  • fp – Output file stream to write to (e.g., stdout or stderr).

  • argtable – Array of argument table structs describing the available options and arguments.

  • suffix – String to append at the end of the syntax summary (e.g., for positional arguments).

void arg_print_syntaxv_ds(arg_dstr_t ds, void **argtable, const char *suffix)

Prints a verbose, multi-line command-line syntax summary to a dynamic string.

The arg_print_syntaxv_ds function generates a detailed, multi-line usage summary for the command-line options and arguments defined in the argument table. This verbose style provides more clarity than the compact single-line form, making it easier for users to understand complex command-line interfaces.

The formatted syntax summary is written to the specified dynamic string object (arg_dstr_t). You can append a custom suffix string to the end of the summary, for example, to indicate positional arguments.

Example usage: 

// Print verbose syntax summary to a dynamic string
arg_dstr_t ds = arg_dstr_create();
arg_print_syntaxv_ds(ds, argtable, "[FILES...]");
printf("%s", arg_dstr_cstr(ds));
arg_dstr_destroy(ds);

Parameters:

  • ds – Dynamic string object to write to.

  • argtable – Array of argument table structs describing the available options and arguments.

  • suffix – String to append at the end of the syntax summary (e.g., for positional arguments).

void arg_print_glossary(FILE *fp, void **argtable, const char *format)

Prints the argument glossary in a customizable format to a file stream.

The arg_print_glossary function generates a glossary of command-line options and arguments, formatted according to the specified format string. This glossary provides users with a summary of available options, their data types, and descriptions, making it easier to understand the command-line interface.

The formatted glossary is written to the specified file stream (fp). The format string allows you to control the layout and appearance of each glossary entry, enabling integration with custom help or documentation systems.

Example usage: 

// Print glossary to stdout with a custom format
arg_print_glossary(stdout, argtable, "  %-20s %s\n");

Parameters:

  • fp – Output file stream to write to (e.g., stdout or stderr).

  • argtable – Array of argument table structs describing the available options and arguments.

  • format – Format string controlling the layout of each glossary entry.

void arg_print_glossary_ds(arg_dstr_t ds, void **argtable, const char *format)

Prints the argument glossary in a customizable format to a dynamic string.

The arg_print_glossary_ds function generates a glossary of command-line options and arguments, formatted according to the specified format string. This glossary provides users with a summary of available options, their data types, and descriptions, making it easier to understand the command-line interface.

The formatted glossary is written to the specified dynamic string object (arg_dstr_t). The format string allows you to control the layout and appearance of each glossary entry, enabling integration with custom help or documentation systems.

Example usage: 

// Print glossary to a dynamic string with a custom format
arg_dstr_t ds = arg_dstr_create();
arg_print_glossary_ds(ds, argtable, "  %-20s %s\n");
printf("%s", arg_dstr_cstr(ds));
arg_dstr_destroy(ds);

Parameters:

  • ds – Dynamic string object to write to.

  • argtable – Array of argument table structs describing the available options and arguments.

  • format – Format string controlling the layout of each glossary entry.

void arg_print_glossary_gnu(FILE *fp, void **argtable)

Prints the argument glossary using strict GNU formatting conventions to a file stream.

The arg_print_glossary_gnu function generates a glossary of command-line options and arguments, formatted to comply with GNU style conventions. In this format, long options are vertically aligned in a second column, and lines are wrapped at 80 characters for improved readability and consistency with GNU command-line tool documentation.

The formatted glossary is written to the specified file stream (fp). This function is useful for generating help output that matches the look and feel of standard GNU utilities.

Example usage: 

// Print GNU-style glossary to stdout
arg_print_glossary_gnu(stdout, argtable);

Parameters:

  • fp – Output file stream to write to (e.g., stdout or stderr).

  • argtable – Array of argument table structs describing the available options and arguments.

void arg_print_glossary_gnu_ds(arg_dstr_t ds, void **argtable)

Prints the argument glossary using strict GNU formatting conventions to a dynamic string.

The arg_print_glossary_gnu_ds function generates a glossary of command-line options and arguments, formatted to comply with GNU style conventions. In this format, long options are vertically aligned in a second column, and lines are wrapped at 80 characters for improved readability and consistency with GNU command-line tool documentation.

The formatted glossary is written to the specified dynamic string object (arg_dstr_t). This function is useful for generating help output that matches the look and feel of standard GNU utilities, especially when you need the output as a string for further processing, logging, or GUI display.

Example usage: 

// Print GNU-style glossary to a dynamic string
arg_dstr_t ds = arg_dstr_create();
arg_print_glossary_gnu_ds(ds, argtable);
printf("%s", arg_dstr_cstr(ds));
arg_dstr_destroy(ds);

Prints the argument glossary using strict GNU formatting conventions to a dynamic string.

Differences to arg_print_glossary() are:

  • wraps lines after 80 chars

  • indents lines without shortops

  • does not accept formatstrings

Contributed by Uli Fouquet

Parameters:

  • ds – Dynamic string object to write to.

  • argtable – Array of argument table structs describing the available options and arguments.

void arg_print_errors(FILE *fp, arg_end_t *end, const char *progname)

Prints the details of all errors stored in the end data structure.

The arg_print_errors function writes formatted error messages for all errors recorded in the specified arg_end_t structure to the given file stream (fp). The progname string is prepended to each error message, making it suitable for displaying or logging error output in command-line applications.

This function is useful for reporting parsing errors to the user after calling arg_parse. It provides clear feedback about missing required arguments, invalid values, or other issues encountered during command-line parsing.

Example usage: 

arg_lit_t *help = arg_lit0("h", "help", "Display help");
arg_int_t *count = arg_int0("c", "count", "<n>", "Number of times");
arg_end_t *end = arg_end(20);
void *argtable[] = {help, count, end};

int nerrors = arg_parse(argc, argv, argtable);
if (nerrors > 0) {
    arg_print_errors(stderr, end, argv[0]);
}

See also

arg_parse, arg_print_errors_ds, arg_dstr_create, arg_dstr_cstr

Parameters:

  • fp – Output file stream to write to (e.g., stdout or stderr).

  • end – Pointer to the arg_end structure containing error details.

  • progname – The name of the program to prepend to each error message.

void arg_print_errors_ds(arg_dstr_t ds, arg_end_t *end, const char *progname)

Prints the details of all errors stored in the end data structure to a dynamic string.

The arg_print_errors_ds function writes formatted error messages for all errors recorded in the specified arg_end_t structure to the provided dynamic string object (arg_dstr_t). The progname string is prepended to each error message, making it suitable for displaying or logging error output in applications that use dynamic string buffers instead of standard output streams.

This function is useful for applications that want to capture error messages for later display, logging, or integration with GUI or web interfaces.

Example usage: 

arg_dstr_t ds = arg_dstr_create();
int nerrors = arg_parse(argc, argv, argtable);
if (nerrors > 0) {
    arg_print_errors_ds(ds, end, argv[0]);
    fprintf(stderr, "%s", arg_dstr_cstr(ds));
}
arg_dstr_destroy(ds);

See also

arg_print_errors, arg_parse, arg_dstr_create, arg_dstr_cstr

Parameters:

  • ds – Pointer to the dynamic string object to which the error messages are written.

  • end – Pointer to the arg_end structure containing error details.

  • progname – The name of the program to prepend to each error message.

void arg_print_formatted(FILE *fp, const unsigned lmargin, const unsigned rmargin, const char *text)

Prints a formatted block of text with specified left and right margins.

The arg_print_formatted function outputs the given text to the specified file stream (fp), arranging it in a column with the provided left and right margins. This is useful for generating neatly aligned help messages, glossaries, or any output where column formatting is desired.

The function automatically wraps lines as needed to ensure that text does not exceed the specified right margin, and indents each line according to the left margin.

Example usage: 

const char* msg = "This is a long help message that will be wrapped and "
                  "indented according to the specified margins.";
arg_print_formatted(stdout, 4, 60, msg);

Prints a formatted block of text with specified left and right margins.

The lines are wrapped at whitspaces next to right margin. The function does not indent the first line, but only the following ones.

Example: arg_print_formatted( fp, 0, 5, “Some text that doesn’t fit.” ) will result in the following output:

Some text that doesn’ t fit.

Too long lines will be wrapped in the middle of a word.

arg_print_formatted( fp, 2, 7, “Some text that doesn’t fit.” ) will result in the following output:

Some text that doesn’ t fit.

As you see, the first line is not indented. This enables output of lines, which start in a line where output already happened.

Author: Uli Fouquet

Parameters:

  • fp – Output file stream to write to (e.g., stdout or stderr).

  • lmargin – Left margin (number of spaces to indent each line).

  • rmargin – Right margin (maximum line width).

  • text – Text to be printed and formatted.

void arg_make_get_help_msg(arg_dstr_t res)

Generates and retrieves the default help message for the application.

The arg_make_get_help_msg function constructs a standard help message describing the usage, options, and arguments for the main application or module. The generated help text is written to a dynamic string buffer, which can be displayed to the user, printed to the console, or included in documentation.

This function is typically used to provide users with a quick reference to the application’s command-line interface, especially when no specific command or argument table is provided. It is useful for displaying help output in response to --help or similar flags.

The help message typically includes the application name and its usage syntax, a glossary of available options and arguments with descriptions, and any additional remarks or formatting defined in the argument table.

Example usage: 

arg_dstr_t ds = arg_dstr_create();
arg_make_get_help_msg(ds);
printf("%s", arg_dstr_cstr(ds));
arg_dstr_destroy(ds);

See also

arg_make_help_msg, arg_dstr_create, arg_dstr_cstr

Parameters:

  • res – Dynamic string handle to store the generated help message.

void arg_make_help_msg(arg_dstr_t ds, const char *cmd_name, void **argtable)

Generates a formatted help message for the command-line interface.

The arg_make_help_msg function constructs a comprehensive help message describing the usage, options, and arguments for a command-line application or sub-command. The generated help text is written to a dynamic string buffer, which can be displayed to the user, printed to the console, or included in documentation.

The help message typically includes the command or sub-command name and its usage syntax, a glossary of available options and arguments with descriptions, and any additional formatting or custom remarks defined in the argument table.

This function is useful for providing users with clear guidance on how to invoke the application and what options are available. It is commonly called when the user requests help (e.g., with -h or --help).

Example usage: 

arg_dstr_t ds = arg_dstr_create();
arg_make_help_msg(ds, "myapp", argtable);
printf("%s", arg_dstr_cstr(ds));
arg_dstr_destroy(ds);

See also

arg_dstr_create, arg_dstr_cstr, arg_rem, arg_print_glossary

Parameters:

  • ds – Dynamic string to store the generated help message.

  • cmd_name – Name of the command or sub-command to display in the usage line.

  • argtable – Array of argument table structs describing the available options and arguments.

void arg_make_syntax_err_msg(arg_dstr_t ds, void **argtable, arg_end_t *end)

Generates a concise syntax error message for command-line parsing errors.

The arg_make_syntax_err_msg function constructs a brief error message summarizing the syntax errors detected during argument parsing. The message is written to a dynamic string buffer, which can then be displayed to the user or logged for diagnostics. This function is useful for applications that want to provide immediate feedback about what went wrong, without including full usage or help information.

The generated message typically includes a summary of the errors encountered and the relevant arguments or options that caused the error.

For a more comprehensive help message that includes usage and glossary information, use arg_make_syntax_err_help_msg.

Example usage: 

arg_dstr_t ds = arg_dstr_create();
int nerrors = arg_parse(argc, argv, argtable);
if (nerrors > 0) {
    arg_make_syntax_err_msg(ds, argtable, end);
    fprintf(stderr, "%s", arg_dstr_cstr(ds));
}
arg_dstr_destroy(ds);

See also

arg_make_syntax_err_help_msg, arg_parse, arg_print_errors, arg_dstr_create, arg_dstr_cstr

Parameters:

  • ds – Pointer to a dynamic string object to store the generated message.

  • argtable – An array of argument table structs describing the expected arguments.

  • end – Pointer to the arg_end structure containing error details.

int arg_make_syntax_err_help_msg(arg_dstr_t ds, const char *name, int help, int nerrors, void **argtable, arg_end_t *end, int *exitcode)

Generates a detailed syntax error help message for command-line parsing errors.

The arg_make_syntax_err_help_msg function constructs a comprehensive help message when syntax errors are detected during argument parsing. It combines error details, usage information, and optional help text into a dynamic string buffer, which can then be displayed to the user or logged for diagnostics.

This function is typically used in applications that want to provide users with clear feedback about what went wrong, what the correct syntax is, and how to get further help. It is especially useful for CLI tools that need to guide users through complex argument requirements.

The generated message may include the command name and a summary of the errors, the correct usage syntax for the command, a glossary of available options and arguments, and additional help text if the help flag is set.

Example usage: 

arg_dstr_t ds = arg_dstr_create();
int exitcode = 0;
int nerrors = arg_parse(argc, argv, argtable);
if (nerrors > 0) {
    arg_make_syntax_err_help_msg(ds, argv[0], 0, nerrors, argtable, end,
                                 &exitcode);
    fprintf(stderr, "%s", arg_dstr_cstr(ds));
}
arg_dstr_destroy(ds);

See also

arg_parse, arg_print_errors, arg_dstr_create, arg_dstr_cstr

Parameters:

  • ds – Pointer to a dynamic string object to store the generated message.

  • name – The name of the command or application.

  • help – Nonzero if the help flag was specified; zero otherwise.

  • nerrors – The number of syntax errors detected during parsing.

  • argtable – An array of argument table structs describing the expected arguments.

  • end – Pointer to the arg_end structure containing error details.

  • exitcode – Pointer to an integer where the recommended exit code will be stored.

Returns:

Returns 0 on success, or a nonzero error code on failure.