ARGTABLE2(3)

📦

version 13 · 2 versions

13 · debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking (latest)
2.13 · alpine 3.23, alpine 3.24, arch rolling, fedora 43, fedora 44

, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

ARGTABLE2(3) — the Argtable programmer's manual 🎀

okay so bestie, this is ARGTABLE2(3) from the Argtable programmer's manual, and it's lowkey the moment your C program stops hand-rolling argv parsing like a Victorian orphan and starts serving real GNU-style options. it's long, so buckle up — part 1 of 2, and we're not even done 💅

✨ NAME ✨

argtable2 — an ANSI C library for parsing GNU style command line options. periodt. 👑

🦋 SYNOPSIS 🦋

#include <argtable2.h>

struct arg_lit
struct arg_int
struct arg_dbl
struct arg_str
struct arg_rex
struct arg_file
struct arg_date
struct arg_rem
struct arg_end

struct arg_lit* arg_lit0(const char *shortopts, const char *longopts, const char *glossary)
struct arg_lit* arg_lit1(const char *shortopts, const char *longopts, const char *glossary)
struct arg_lit* arg_litn(const char *shortopts, const char *longopts, int mincount, int maxcount, const char *glossary)

struct arg_int* arg_int0(const char* shortopts, const char* longopts, const char* datatype, const char* glossary)
struct arg_int* arg_int1(const char *shortopts, const char *longopts, const char* datatype, const char *glossary)
struct arg_int* arg_intn(const char *shortopts, const char *longopts, const char* datatype, int mincount, int maxcount, const char *glossary)

struct arg_dbl* arg_dbl0(const char *shortopts, const char *longopts, const char* datatype, const char *glossary)
struct arg_dbl* arg_dbl1(const char *shortopts, const char *longopts, const char* datatype, const char *glossary)
struct arg_dbl* arg_dbln(const char *shortopts, const char *longopts, const char* datatype, int mincount, int maxcount, const char *glossary)

struct arg_str* arg_str0(const char *shortopts, const char *longopts, const char* datatype, const char *glossary)
struct arg_str* arg_str1(const char *shortopts, const char *longopts, const char* datatype, const char *glossary)
struct arg_str* arg_strn(const char *shortopts, const char *longopts, const char* datatype, int mincount, int maxcount, const char *glossary)

struct arg_rex* arg_rex0(const char* shortopts, const char* longopts, const char* pattern, const char* datatype, int flags, const char* glossary)
struct arg_rex* arg_rex1(const char* shortopts, const char* longopts, const char* pattern, const char* datatype, int flags, const char* glossary)
struct arg_rex* arg_rexn(const char* shortopts, const char* longopts, const char* pattern, const char* datatype, int mincount, int maxcount, int flags, const char* glossary)

struct arg_file* arg_file0(const char* shortopts, const char* longopts, const char* datatype, const char* glossary)
struct arg_file* arg_file1(const char *shortopts, const char *longopts, const char* datatype, const char *glossary)
struct arg_file* arg_filen(const char *shortopts, const char *longopts, const char* datatype, int mincount, int maxcount, const char *glossary)

struct arg_date* arg_date0const char* shortopts, const char* longopts, const char* format, const char* datatype, const char *glossary)
struct arg_date* arg_date1const char* shortopts, const char* longopts, const char* format, const char* datatype, const char *glossary)
struct arg_date* arg_datenconst char* shortopts, const char* longopts, const char* format, const char* datatype, int mincount, int maxcount, const char *glossary)

struct arg_rem* arg_rem(const char *datatype, const char *glossary)
struct arg_end* arg_end(int maxerrors)

int arg_nullcheck(void **argtable)
int arg_parse(int argc, char **argv, void **argtable)
void arg_print_option(FILE *fp, const char *shortopts, const char *longopts, const char *datatype, const char *suffix)
void arg_print_syntax(FILE *fp, void **argtable, const char *suffix)
void arg_print_syntaxv(FILE *fp, void **argtable, const char *suffix)
void arg_print_glossary(FILE *fp, void **argtable, const char *format)
void arg_print_glossary_gnu(FILE *fp, void **argtable)
void arg_print_errors(FILE *fp, struct arg_end *end, const char *progname)
void arg_freetable(void **argtable, size_t n)

not me typing those three arg_date lines exactly the way they appear in the original, typos and all 💀 bestie we keep it faithful, no cap.

🌸 DESCRIPTION 🌸

Argtable is an ANSI C library for parsing GNU style command line arguments with a minimum of fuss. it literally lets you define your program's argument syntax right there in the source code, as an array of structs. then the command line gets parsed according to that spec, and the resulting values get stored directly into user-defined program variables where your main program can reach them. no drama, no middleman. 🫶

This man page is only for reference. Introductory documentation and example source code is typically installed under /usr/share/doc/argtable2/ and is also available from the argtable homepage at http://argtable.sourceforge.net. iykyk.

🧚 Constructing an `arg_<xxx>` data structure

Each arg_<xxx> struct has it own unique set of constructor functions (defined above) which are typically of the form:

struct arg_int* arg_int0("f", "foo", "<int>", "the foo factor")
struct arg_int* arg_int1("f", "foo", "<int>", "the foo factor")
struct arg_int* arg_intn("f", "foo", "<int>", 2, 4, "the foo factor")

where arg_int0() and arg_int1() are merely abbreviated forms of arg_intn(). They are provided for convenience when defining command line options that have either zero-or-one occurrences (mincount=0,maxcount=1) or exactly one occurrence (mincount=1,maxcount=1) respectively. so 0 and 1 are just the lazy-girl versions of n, and honestly? we respect it. 💅

The shortopts="f" parameter defines the option's short form tag (eg -f). Multiple alternative tags may be defined by concatenating them (eg shortopts="abc" defines options -a, -b and -c as equivalent). Specify shortopts=NULL when no short option is required.

The longopts="foo" parameter defines the option's long form tag (eg --foo). Multiple alternative long form tags may be separated by commas (eg longopts="size,limit" defines --size and --limit). Do not include any whitespace in the longopts string. Specify longopts=NULL when no long option is required.

If both shortopts and longopts are NULL then the option is an untagged argument. 👀

The datatype="<int>" parameter is a descriptive string that denotes the argument data type in error messages, as in --foo=<int>. Specifying datatype=NULL indicates the default datatype should be used. Specifying datatype="" effectively disables the datatype display.

The mincount=2 and maxcount=3 parameters specify the minimum and maximum number of occurrences of the option on the command line. If the command line option does not appear the required number of times then the parser reports a syntax error. the vibe check failed, basically. 😭

The glossary="the foo factor" parameter is another descriptive string. It appears only in the glossary table that is generated automatically by the arg_print_glossary function (described later).

-f, --foo=<int>    the foo factor

Specifying a NULL glossary string causes that option to be omitted from the glossary table. shy option, stays home. 🙈

⭐ LITERAL COMMAND LINE OPTIONS ⭐

-x, -y, -z, --help, --verbose

struct arg_lit
   {
   struct arg_hdr hdr;  /* internal argtable header */
   int count;           /* number of matching command line options */
   };

Literal options take no argument values. Upon a successful parse, count is guaranteed to be within the mincount and maxcount limits specified at construction.

🔥 INTEGER COMMAND LINE OPTIONS 🔥

-x2, -z 32MB, --size=734kb, --hex 0x7, --binary 0b10011010, --octal 0o123

Argtable accepts command line integers in decimal (eg 123), hexadecimal (eg 0xFF12), octal (eg 0o123) and binary (eg 0b0101110) formats. It also accepts integers that are suffixed by "KB" (x1024), "MB" (x1048576) or "GB" (x1073741824). All characters are case insensitive. it's giving "numbers? we speak every dialect." 🌈

struct arg_int
   {
   struct arg_hdr hdr;  /* internal argtable header */
   int count;           /* number of values returned in ival[] */
   int *ival;           /* array of parsed integer values */
   };

Upon a successful parse, count is guaranteed to be within the mincount and maxcount limits set for the option at construction with the appropriate values store in the ival array. The parser will not accept any values beyond that limit.

Hint: It is legal to set default values in the ival array prior to calling the arg_parse function. Argtable will not alter ival entries for which no command line argument is received. 💖

Hint: Untagged numeric arguments are not recommended because GNU getopt mistakes negative values (eg -123) for tagged options (eg -1 -2 -3). Tagged arguments (eg -x -123, --tag=-123) do not suffer this problem. so like, tag your numbers, bestie, or they'll get jumped by getopt. 💀

💜 REAL/DOUBLE COMMAND LINE OPTIONS 💜

-x2.234, -y 7e-03, -z-3.3E+6, --pi=3.1415, --tolerance 1.0E-6

struct arg_dbl
   {
   struct arg_hdr hdr;  /* internal argtable header */
   int count;           /* number of values returned in dval[] */
   double *dval;        /* array of parsed double values */
   };

Same as arg_int except the parsed values are stored in dval as doubles. same energy, more precision. ✨

🎀 STRING COMMAND LINE OPTIONS 🎀

-Dmacro, -t mytitle, -m "my message string", --title="hello world"

struct arg_str
   {
   struct arg_hdr hdr;  /* internal argtable header */
   int count;           /* number of strings returned in sval[] */
   const char **sval;   /* array of pointers to parsed argument strings */
   };

Same as arg_int except pointers to the parsed strings are returned in sval rather than a separate copy of the string. Indeed, these pointers actually reference the original string buffers stored in argv[], so their contents should not be altered. However, it is legal to initialise the string pointers in the sval array to reference user-supplied default strings prior to calling arg_parse. Argtable will only alter the contents of sval when matching command line arguments are detected. like, no duplicating, no editing — we're borrowing, not keeping. 🫶

🍓 REGULAR EXPRESSION COMMAND LINE OPTIONS 🍓

commit, update, --command=commit, --command=update

struct arg_rex
   {
   struct arg_hdr hdr;  /* internal argtable header */
   int count;           /* number of strings returned in sval[] */
   const char **sval;   /* array of pointers to parsed argument strings */
   };

Similar to arg_str except the string argument values are only accepted if they match a predefined regular expression. Regular expressions are useful for matching command line keywords, particularly if case insensitive strings or pattern matching is required. The regular expression is defined by the pattern parameter passed to the arg_rex constructor and evaluated using regex. Its behaviour can be controlled via standard regex bit flags. These are passed to argtable via the flags parameter in the arg_rex constructor. However the only two of the standard regex flags are relevant to argtable, namely REG_EXTENDED (use extended regular expressions rather than basic ones) and REG_ICASE (ignore case). These flags may be logically ORed if desired. See regex(3) for more details of regular expression matching.

Restrictions: Argtable does not support arg_rex functionality under Microsoft Windows platforms because the Microsoft compilers do include the necessary regex support as standard. 😭

🌈 FILENAME COMMAND LINE OPTIONS 🌈

-o myfile, -Ihome/foo/bar, --input=~/doc/letter.txt, --name a.out

okay so next up in the arg_xxx family reunion is arg_file and honestly? she's the overachiever of the string options 🎀

     struct arg_file
        {
        struct arg_hdr hdr;      /* internal argtable header */
        int count;               /* number of filename strings returned */
        const char **filename;   /* pointer to full filename string */
        const char **basename;   /* pointer to filename excluding leading path */
        const char **extension;  /* pointer to the filename extension */
        };

So basically she's arg_str's cousin, except the strings are presumed to be filenames, which means argtable does a lil extra parsing to pull out the basename and the extension when they exist 🦋 The three arrays filename[], basename[], extension[] each hold up to maxcount entries, and the i'th entry of each one points at different components of the same string buffer. like, one string, three views, main character energy ✨

So for example, -o /home/heitmann/mydir/foo.txt gets parsed as:

           filename[i]  = "/home/heitmann/mydir/foo.txt"
           basename[i]  =                      "foo.txt"
           extension[i] =                         ".txt"

If the filename has no leading path then the basename is just the same as the filename, no drama 💅 And if no extension could be identified, it's given as NULL. Extensions are considered as all text from the last dot in the filename.

💡 Hint: Argtable only ever treats the filenames as strings and never attempts to open them as files or perform any directory lookups on them. she is not touching your filesystem bestie, she's just looking respectfully 👀

✨ DATE/TIME COMMAND LINE OPTIONS ✨

here's the vibe she's serving: 12/31/04, -d 1982-11-28, --time 23:59 🕰️

     struct arg_date
        {
        struct arg_hdr hdr;  /* internal argtable header */
        const char *format;  /* user-supplied date format string that was passed to constructor */
        int count;           /* number of datestamps returned in tmval[] */
        struct tm *tmval;    /* array of datestamps */
        };

She takes a timestamp string off the command line and converts it into struct tm format using the system strptime function 🌸 The time format is defined by the format string you passed to the arg_date constructor, and it gets passed directly to strptime. Wanna know more about that format string? See strptime(3), iykyk 📖

⚠️ Restrictions: Argtable does not support arg_date functionality under Microsoft Windows, because the Microsoft compilers do include the necessary strptime support as standard. so yeah. windows girlies, this one's not for you 😭

✨ REMARK OPTIONS ✨

     struct arg_rem
        {
        struct arg_hdr hdr;  /* internal argtable header */
        };

The arg_rem struct is a dummy struct in the sense that it does not represent a command line option to be parsed. nope, not a real option, she's a vibe 🌈

Instead she provides a means to include additional datatype and glossary strings in the output of the arg_print_syntax, arg_print_syntaxv, and arg_print_glossary functions. So you can use arg_rem structs in the argument table to insert extra lines of text into the glossary descriptions, or to insert extra text fields into the syntax description. she's the ✨decor✨ of your help output, periodt 💅

✨ END-OF-TABLE OPTION ✨

     struct arg_end
        {
        struct arg_hdr hdr;  /* internal argtable header */
        int count;           /* number of errors returned */
        int *error;          /* array of error codes */
        void **parent;       /* pointers to the erroneous command line options */
        const char **argval; /* pointers to the erroneous command line argument values */
        };

Every argument table must have an arg_end structure as its last entry 🔥 No exceptions, bestie. She marks the end of an argument table and stores the error codes generated by the parser as it processed the argument table.

The maxerrors parameter you pass to the arg_end constructor specifies the maximum number of errors that the structure can store. Any further errors are discarded and replaced with the single error code ARG_ELIMIT, which is later reported to the user by the message "too many errors". And like, a maxerrors limit of 20 is quite reasonable, fr fr 👑

Good news though: the arg_print_errors function will print the errors stored in the arg_end struct in the same order as they occurred, so there is genuinely no need to understand the internals of the arg_end struct. she handles it, you just call her 🫶

✨ FUNCTION REFERENCE ✨

`int arg_nullcheck (void **argtable)`

Returns non-zero if the argtable[] array contains any NULL entries up until the terminating arg_end* entry. Returns zero otherwise. that's it, that's the function, she's simple and she's iconic 💖

`int arg_parse (int argc, char argv, void argtable)`

Parses the command line arguments in argv[] using the command line syntax specified in argtable[], and returns the number of errors encountered. The error details get recorded in the argument table's arg_end structure, from where they can be displayed later with the arg_print_errors function 📝

Upon a successful parse, the arg_xxx structures referenced in argtable[] will contain the argument values extracted from the command line. slay 🌟

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

This function prints an option's syntax, as in -K|--scalar=<int>, where the short options, long options, and datatype are all given as parameters of this function 🎀

She's primarily used within the arg_xxx structures' errorfn functions as a way of displaying an option's syntax inside of error messages. However, she can also be used in user code if desired, no gatekeeping here ✨

The suffix string is provided as a convenience for appending newlines and so forth to the end of the display, and can be given as NULL if not required.

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

Prints the GNU style command line syntax for the given argument table, as in:

[-abcv] [--scalar=<n>] [-o myfile] <file> [<file>]

The suffix string is provided as a convenience for appending newlines and so forth to the end of the display, and can be given as NULL if not required 💅

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

Prints the verbose form of the command line syntax for the given argument table, as in:

[-a] [-b] [-c] [--scalar=<n>] [-o myfile] [-v|--verbose] <file> [<file>]

The suffix string is provided as a convenience for appending newlines and so forth to the end of the display, and can be given as NULL if not required 🌸

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

Prints a glossary table describing each option in the given argument table 📖 The format string is passed to printf to control the formatting of each entry in the the glossary. It must have exactly two "%s" format parameters, as in "%-25s %s\n" — the first is for the option's syntax and the second is for its glossary string.

🫶 If an option's glossary string is NULL, then that option is omitted from the glossary display. shy options get to sit this one out.

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

An alternate form of arg_print_glossary() that prints the glossary using strict GNU formatting conventions, wherein long options are vertically aligned in a second column, and lines are wrapped at 80 characters. aesthetically pleasing, aligned, chef's kiss 👑

`void arg_print_errors (FILE fp, struct arg_end end, const char *progname)`

Prints the details of all errors stored in the end data structure. The progname string is prepended to each error message. so like myprog: too many errors but make it real 😭

`void arg_freetable (void ** argtable, size_t n)`

Deallocates the memory used by each arg_xxx struct referenced by argtable[] 💀 She does this by calling free for each of the n pointers in the argtable array, and then nulling them for safety. clean up after yourself bestie, no memory leaks in this house 🧹✨

✨ FILES ✨

/usr/include/argtable2.h
/usr/lib/libargtable2.a
/usr/lib/libargtable2.so
/usr/man3/argtable2.3
/usr/share/doc/argtable2/
/usr/share/doc/argtable2/example/

✨ AUTHOR ✨

Stewart Heitmann <sheitmann@users.sourceforge.net> — the legend herself, thank you for the library king 👑💖

and that's the whole page bestie!! this was version Argtable2-13 from Jan 2008, filed under ARGTABLE2(3) 🌈 go forth and parse some arguments, you've got this, no cap 🦋💜

📦 where this page comes from

debian bookworm: libargtable2-dev 13-1.1 · LGPL-2.0-or-later
debian trixie: libargtable2-dev 13-4 · LGPL-2.0-or-later
ubuntu jammy: libargtable2-dev 13-1.1 · LGPL-2.0-or-later
ubuntu noble: libargtable2-dev 13-2 · LGPL-2.0-or-later
ubuntu questing: libargtable2-dev 13-4
ubuntu resolute: libargtable2-dev 13-4build1 · LGPL-2.0-or-later
ubuntu stonking: libargtable2-dev 13-4build1 · LGPL-2.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms