ArgParseRun

Documentation

API Reference

ArgParseRun

Description

Walk argv and populate every registered target. Prints errors or --help straight to the diagnostic channel; caller only needs to inspect the return value.

argv[0] is treated as the program path (skipped during parsing).

Success

Returns ARG_RUN_OK; every registered target is set.

Failure

Returns ARG_RUN_HELP (help printed) or ARG_RUN_ERROR (parse error logged + usage hint).

Usage example (Cross-references)

Usage examples (Cross-references)

In ArgParse.c:618:

    }
    
    ArgRun ArgParseRun(ArgParse *self, int argc, char **argv) {
        if (!self || argc < 0 || (argc > 0 && !argv)) {
            LOG_ERROR("ArgParseRun: bad arguments");

In ArgParse.c:620:

    ArgRun ArgParseRun(ArgParse *self, int argc, char **argv) {
        if (!self || argc < 0 || (argc > 0 && !argv)) {
            LOG_ERROR("ArgParseRun: bad arguments");
            return ARG_RUN_ERROR;
        }

In Resolve.c:26:

            ArgPositional(&ap, "hostname", &hostname, "name to resolve");
    
            ArgRun rc = ArgParseRun(&ap, argc, argv);
            ArgParseDeinit(&ap);
            if (rc != ARG_RUN_OK) {

In Beam.c:393:

            ArgRequired(&ap, "-u", "--upstream", &upstream_spec, "upstream host:port");
    
            ArgRun rc = ArgParseRun(&ap, argc, argv);
            ArgParseDeinit(&ap);
            if (rc != ARG_RUN_OK) {

In ArgParse.c:25:

    
        char  *argv[] = {(char *)"prog", (char *)"--listen", (char *)"0.0.0.0:8080"};
        ArgRun rc     = ArgParseRun(&p, 3, argv);
    
        bool ok = (rc == ARG_RUN_OK) && listen && ZstrCompare(listen, "0.0.0.0:8080") == 0;

In ArgParse.c:41:

    
        char  *argv[] = {(char *)"prog", (char *)"--listen=0.0.0.0:8080"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
    
        bool ok = (rc == ARG_RUN_OK) && listen && ZstrCompare(listen, "0.0.0.0:8080") == 0;

In ArgParse.c:57:

    
        char  *argv[] = {(char *)"prog", (char *)"-l", (char *)"127.0.0.1:9"};
        ArgRun rc     = ArgParseRun(&p, 3, argv);
    
        bool ok = (rc == ARG_RUN_OK) && listen && ZstrCompare(listen, "127.0.0.1:9") == 0;

In ArgParse.c:73:

    
        char  *argv[] = {(char *)"prog"};
        ArgRun rc     = ArgParseRun(&p, 1, argv);
    
        bool ok = (rc == ARG_RUN_OK) && timeout == 30;

In ArgParse.c:89:

    
        char  *argv[] = {(char *)"prog", (char *)"--timeout", (char *)"5"};
        ArgRun rc     = ArgParseRun(&p, 3, argv);
    
        bool ok = (rc == ARG_RUN_OK) && timeout == 5;

In ArgParse.c:105:

    
        char  *argv[] = {(char *)"prog", (char *)"--verbose"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
    
        bool ok = (rc == ARG_RUN_OK) && verbose == true;

In ArgParse.c:121:

    
        char  *argv[] = {(char *)"prog"};
        ArgRun rc     = ArgParseRun(&p, 1, argv);
    
        bool ok = (rc == ARG_RUN_OK) && verbose == false;

In ArgParse.c:137:

    
        char  *argv[] = {(char *)"prog", (char *)"-v", (char *)"-v", (char *)"-v"};
        ArgRun rc     = ArgParseRun(&p, 4, argv);
    
        bool ok = (rc == ARG_RUN_OK) && verbose == 3;

In ArgParse.c:153:

    
        char  *argv[] = {(char *)"prog", (char *)"-vvv"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
    
        bool ok = (rc == ARG_RUN_OK) && verbose == 3;

In ArgParse.c:171:

    
        char  *argv[] = {(char *)"cp", (char *)"a.txt", (char *)"b.txt"};
        ArgRun rc     = ArgParseRun(&p, 3, argv);
    
        bool ok = (rc == ARG_RUN_OK) && ZstrCompare(src, "a.txt") == 0 && ZstrCompare(dst, "b.txt") == 0;

In ArgParse.c:191:

    
        char  *argv[] = {(char *)"cp", (char *)"a.txt", (char *)"-v", (char *)"b.txt"};
        ArgRun rc     = ArgParseRun(&p, 4, argv);
    
        bool ok = (rc == ARG_RUN_OK) && ZstrCompare(src, "a.txt") == 0 && ZstrCompare(dst, "b.txt") == 0 && verbose == true;

In ArgParse.c:211:

    
        char  *argv[] = {(char *)"prog", (char *)"--n=12345"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
    
        bool ok = (rc == ARG_RUN_OK) && n == 12345;

In ArgParse.c:227:

    
        char  *argv[] = {(char *)"prog", (char *)"--v", (char *)"-42"};
        ArgRun rc     = ArgParseRun(&p, 3, argv);
    
        bool ok = (rc == ARG_RUN_OK) && v == -42;

In ArgParse.c:243:

    
        char  *argv[] = {(char *)"prog", (char *)"--ratio=2.5"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
    
        bool ok = (rc == ARG_RUN_OK) && ratio > 2.4 && ratio < 2.6;

In ArgParse.c:259:

    
        char  *argv[] = {(char *)"prog", (char *)"--name", (char *)"alice"};
        ArgRun rc     = ArgParseRun(&p, 3, argv);
    
        bool ok = (rc == ARG_RUN_OK) && StrLen(&name) == 5 && StrBegin(&name)[0] == 'a' && StrBegin(&name)[4] == 'e';

In ArgParse.c:280:

    
        char  *argv[] = {(char *)"prog"};
        ArgRun rc     = ArgParseRun(&p, 1, argv);
    
        bool ok = (rc == ARG_RUN_ERROR) && listen == NULL;

In ArgParse.c:298:

    
        char  *argv[] = {(char *)"cp", (char *)"a.txt"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
    
        bool ok = (rc == ARG_RUN_ERROR);

In ArgParse.c:314:

    
        char  *argv[] = {(char *)"prog", (char *)"--bogus"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
    
        bool ok = (rc == ARG_RUN_ERROR);

In ArgParse.c:330:

    
        char  *argv[] = {(char *)"prog", (char *)"--n", (char *)"abc"};
        ArgRun rc     = ArgParseRun(&p, 3, argv);
    
        bool ok = (rc == ARG_RUN_ERROR) && n == 0;

In ArgParse.c:346:

    
        char  *argv[] = {(char *)"prog", (char *)"--v=256"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
    
        bool ok = (rc == ARG_RUN_ERROR) && v == 0;

In ArgParse.c:362:

    
        char  *argv[] = {(char *)"prog", (char *)"first", (char *)"extra"};
        ArgRun rc     = ArgParseRun(&p, 3, argv);
    
        bool ok = (rc == ARG_RUN_ERROR);

In ArgParse.c:380:

        ArgOptional(&p, NULL, "--enable", out, "toggle");
        char  *argv[] = {(char *)"prog", (char *)"--enable", (char *)text};
        ArgRun rc     = ArgParseRun(&p, 3, argv);
        ArgParseDeinit(&p);
        DefaultAllocatorDeinit(&a);

In ArgParse.c:414:

        ArgOptional(&p, NULL, "--enable", &v, "toggle");
        char  *argv[] = {(char *)"prog", (char *)"--enable", (char *)"maybe"};
        ArgRun rc     = ArgParseRun(&p, 3, argv);
        bool   ok     = (rc == ARG_RUN_ERROR) && (v == true);
        ArgParseDeinit(&p);

In ArgParse.c:432:

        ArgCount(&p, "-v", "--verbose", &n, "v");
        char  *argv[] = {(char *)"prog", (char *)"-v", (char *)"-v"};
        ArgRun rc     = ArgParseRun(&p, 3, argv);
        bool   ok     = (rc == ARG_RUN_OK) && (n == 2);
        ArgParseDeinit(&p);

In ArgParse.c:445:

        ArgCount(&p, "-v", "--verbose", &n, "v");
        char  *argv[] = {(char *)"prog", (char *)"-vvvv"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
        bool   ok     = (rc == ARG_RUN_OK) && (n == 4);
        ArgParseDeinit(&p);

In ArgParse.c:458:

        ArgCount(&p, "-v", "--verbose", &n, "v");
        char  *argv[] = {(char *)"prog", (char *)"-v", (char *)"-v", (char *)"-v"};
        ArgRun rc     = ArgParseRun(&p, 4, argv);
        bool   ok     = (rc == ARG_RUN_OK) && (n == 3);
        ArgParseDeinit(&p);

In ArgParse.c:477:

        ArgRequired(&p, "-l", "--listen", &listen, "host:port");
        char  *argv[] = {(char *)"prog", (char *)"--listen"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
        bool   ok     = (rc == ARG_RUN_ERROR) && (listen == NULL);
        ArgParseDeinit(&p);

In ArgParse.c:491:

        ArgFlag(&p, "-v", "--verbose", &v, "v");
        char  *argv[] = {(char *)"prog", (char *)"--verbose=1"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
        bool   ok     = (rc == ARG_RUN_ERROR) && (v == false);
        ArgParseDeinit(&p);

In ArgParse.c:504:

        ArgCount(&p, "-v", "--verbose", &n, "v");
        char  *argv[] = {(char *)"prog", (char *)"--verbose=3"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
        bool   ok     = (rc == ARG_RUN_ERROR) && (n == 0);
        ArgParseDeinit(&p);

In ArgParse.c:519:

        ArgRequired(&p, "-l", "--listen", &listen, "host:port");
        char  *argv[] = {(char *)"prog", (char *)"-lhost"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
        bool   ok     = (rc == ARG_RUN_ERROR);
        ArgParseDeinit(&p);

In ArgParse.c:536:

        ArgOptional(&p, NULL, "--hi", &hi, "hi");
        char  *argv[] = {(char *)"prog", (char *)"--lo=-32768", (char *)"--hi=32767"};
        ArgRun rc     = ArgParseRun(&p, 3, argv);
        bool   ok     = (rc == ARG_RUN_OK) && (lo == -32768) && (hi == 32767);
        ArgParseDeinit(&p);

In ArgParse.c:549:

        ArgOptional(&p, NULL, "--v", &v, "v");
        char  *argv[] = {(char *)"prog", (char *)"--v=32768"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
        bool   ok     = (rc == ARG_RUN_ERROR) && (v == 5);
        ArgParseDeinit(&p);

In ArgParse.c:570:

        // forces it to be a positional.
        char  *argv[] = {(char *)"cat", (char *)"--", (char *)"--unusual-name"};
        ArgRun rc     = ArgParseRun(&p, 3, argv);
    
        bool ok = (rc == ARG_RUN_OK) && ZstrCompare(file, "--unusual-name") == 0;

In ArgParse.c:592:

    
        char  *argv[] = {(char *)"prog", (char *)"--help"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
    
        // --help should beat the missing-required check.

In ArgParse.c:624:

        p->out        = &tmp;
        char  *argv[] = {(char *)"prog", (char *)"--help"};
        ArgRun rc     = ArgParseRun(p, 2, argv);
        p->out        = NULL;

In ArgParse.c:895:

        p->out        = &tmp;
        char  *argv[] = {(char *)"prog", (char *)"--help"};
        ArgRun rc     = ArgParseRun(p, 2, argv);
        p->out        = NULL;

In ArgParse.c:933:

        ArgOptional(&p, NULL, "--n", out, "count");
        char *argv[] = {(char *)"prog", (char *)"--n", (char *)text};
        *rc          = ArgParseRun(&p, 3, argv);
        ArgParseDeinit(&p);
        DefaultAllocatorDeinit(&a);

In ArgParse.c:944:

        ArgOptional(&p, NULL, "--n", out, "count");
        char *argv[] = {(char *)"prog", (char *)"--n", (char *)text};
        *rc          = ArgParseRun(&p, 3, argv);
        ArgParseDeinit(&p);
        DefaultAllocatorDeinit(&a);

In ArgParse.c:1053:

        ArgOptional(&p, NULL, "--v", &v, "");
        char  *argv[] = {(char *)"prog", (char *)"--v=200"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
        bool   ok     = (rc == ARG_RUN_OK) && (v == 200);
        ArgParseDeinit(&p);

In ArgParse.c:1067:

        ArgOptional(&p, NULL, "--v", &v, "");
        char  *argv[] = {(char *)"prog", (char *)"--v=255"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
        bool   ok     = (rc == ARG_RUN_OK) && (v == 255);
        ArgParseDeinit(&p);

In ArgParse.c:1081:

        ArgOptional(&p, NULL, "--v", &v, "");
        char  *argv[] = {(char *)"prog", (char *)"--v=65535"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
        bool   ok     = (rc == ARG_RUN_OK) && (v == 65535);
        ArgParseDeinit(&p);

In ArgParse.c:1095:

        ArgOptional(&p, NULL, "--v", &v, "");
        char  *argv[] = {(char *)"prog", (char *)"--v=65536"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
        bool   ok     = (rc == ARG_RUN_ERROR) && (v == 9);
        ArgParseDeinit(&p);

In ArgParse.c:1110:

        ArgOptional(&p, NULL, "--v", &v, "");
        char  *argv[] = {(char *)"prog", (char *)"--v=70000"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
        bool   ok     = (rc == ARG_RUN_OK) && (v == 70000);
        ArgParseDeinit(&p);

In ArgParse.c:1124:

        ArgOptional(&p, NULL, "--v", &v, "");
        char  *argv[] = {(char *)"prog", (char *)"--v=4294967296"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
        bool   ok     = (rc == ARG_RUN_ERROR) && (v == 11);
        ArgParseDeinit(&p);

In ArgParse.c:1138:

        ArgOptional(&p, NULL, "--v", &v, "");
        char  *argv[] = {(char *)"prog", (char *)"--v=5000000000"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
        bool   ok     = (rc == ARG_RUN_OK) && (v == 5000000000ULL);
        ArgParseDeinit(&p);

In ArgParse.c:1153:

        ArgOptional(&p, NULL, "--name", &name, "n");
        char  *argv[] = {(char *)"prog", (char *)"--name", (char *)"bob"};
        ArgRun rc     = ArgParseRun(&p, 3, argv);
        bool ok = (rc == ARG_RUN_OK) && (StrLen(&name) == 3) && (StrBegin(&name)[0] == 'b') && (StrBegin(&name)[2] == 'b');
        ArgParseDeinit(&p);

In ArgParse.c:1168:

        ArgOptional(&p, NULL, "--name", &s, "n");
        char  *argv[] = {(char *)"prog", (char *)"--name", (char *)"carol"};
        ArgRun rc     = ArgParseRun(&p, 3, argv);
        bool   ok     = (rc == ARG_RUN_OK) && s && (ZstrCompare(s, "carol") == 0);
        ArgParseDeinit(&p);

In ArgParse.c:1182:

        ArgOptional(&p, NULL, "--v", &v, "");
        char  *argv[] = {(char *)"prog", (char *)"--v=-5"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
        bool   ok     = (rc == ARG_RUN_OK) && (v == -5);
        ArgParseDeinit(&p);

In ArgParse.c:1197:

        ArgOptional(&p, NULL, "--v", &v, "");
        char  *argv[] = {(char *)"prog", (char *)"--v", (char *)"zzz"};
        ArgRun rc     = ArgParseRun(&p, 3, argv);
        bool   ok     = (rc == ARG_RUN_ERROR) && (v == 7);
        ArgParseDeinit(&p);

In ArgParse.c:1211:

        ArgOptional(&p, NULL, "--v", &v, "");
        char  *argv[] = {(char *)"prog", (char *)"--v=-100000"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
        bool   ok     = (rc == ARG_RUN_OK) && (v == -100000);
        ArgParseDeinit(&p);

In ArgParse.c:1225:

        ArgOptional(&p, NULL, "--v", &v, "");
        char  *argv[] = {(char *)"prog", (char *)"--v", (char *)"nope"};
        ArgRun rc     = ArgParseRun(&p, 3, argv);
        bool   ok     = (rc == ARG_RUN_ERROR) && (v == 13);
        ArgParseDeinit(&p);

In ArgParse.c:1240:

        ArgOptional(&p, NULL, "--v", &v, "");
        char  *argv[] = {(char *)"prog", (char *)"--v=2.5"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
        bool   ok     = (rc == ARG_RUN_OK) && (v > 2.4f) && (v < 2.6f);
        ArgParseDeinit(&p);

In ArgParse.c:1254:

        ArgOptional(&p, NULL, "--v", &v, "");
        char  *argv[] = {(char *)"prog", (char *)"--v", (char *)"xyz"};
        ArgRun rc     = ArgParseRun(&p, 3, argv);
        bool   ok     = (rc == ARG_RUN_ERROR) && (v > 8.9f) && (v < 9.1f);
        ArgParseDeinit(&p);

In ArgParse.c:1512:

        ArgParse         p = ArgParseInit("prog", NULL, &a);
    
        ArgRun rc = ArgParseRun(&p, 0, NULL);
    
        bool ok = (rc == ARG_RUN_OK);

In ArgParse.c:1534:

    
        char  *argv[] = {(char *)"prog", (char *)"--listen=host:9"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
    
        bool ok = (rc == ARG_RUN_OK) && listen && ZstrCompare(listen, "host:9") == 0;

In ArgParse.c:1558:

    
        char  *argv[] = {(char *)"prog", (char *)"-b"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
    
        // Real: only -b matched -> bflag set, aflag untouched.

In ArgParse.c:1584:

        // "-vx": -v is a valid count (so the bundle is attempted), x is unknown.
        char  *argv[] = {(char *)"prog", (char *)"-vx"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
    
        bool ok = (rc == ARG_RUN_ERROR);

In ArgParse.c:1604:

    
        char  *argv[] = {(char *)"prog", (char *)"-vv"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
    
        bool ok = (rc == ARG_RUN_OK) && (verbose == 2);

In ArgParse.c:1626:

    
        char  *argv[] = {(char *)"prog", (char *)"-fg"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
    
        bool ok = (rc == ARG_RUN_OK) && (f == true) && (g == true);

In ArgParse.c:1649:

    
        char  *argv[] = {(char *)"prog", (char *)"-ff"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
    
        bool ok = (rc == ARG_RUN_OK) && (f == true);

In ArgParse.c:1673:

        // Valid "-vv" bundle, but the required --listen is never supplied.
        char  *argv[] = {(char *)"prog", (char *)"-vv"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
    
        bool ok = (rc == ARG_RUN_ERROR) && (verbose == 2) && (listen == NULL);

In ArgParse.c:1694:

    
        char  *argv[] = {(char *)"prog", (char *)"-v"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
    
        bool ok = (rc == ARG_RUN_OK) && (v == true);

In ArgParse.c:1781:

    
        p->out    = &tmp;
        ArgRun rc = ArgParseRun(p, argc, argv);
        p->out    = NULL;

In ArgParse.c:1938:

    
        char  *argv[] = {(char *)"prog", (char *)"--help"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);
    
        ArgParseDeinit(&p);

Last updated on July 1, 2026

ArgParseInit ArgPositional