NNG_OPTS_PARSE(3supp)

💖 NAME 💖

Okay so nng_opts_parse — parse command line options. Bestie, this is the NNG_OPTS_PARSE(3supp) page from the NNG Reference Manual, and it’s literally here to make option parsing not a whole thing.

✨ SYNOPSIS ✨

           #include <nng/nng.h>
           #include <nng/supplemental/util/options.h>

           typedef struct nng_optspec {
               const char *o_name;  // Long style name (may be NULL for short only)
               int         o_short; // Short option (no clustering!)
               int         o_val;   // Value stored on a good parse (>0)
               bool        o_arg;   // Option takes an argument if true
           } nng_optspec;

           int nng_opts_parse(int argc, char *const *argv, const nng_optspec *spec, int *val, char **arg, int *idx);

🌸 DESCRIPTION 🌸

Okay so nng_opts_parse() is a supplemental function meant to help you parse command line arguments. It’s basically here to stand in for getopt() from POSIX systems — but it’s available everywhere that NNG is, and it includes some capabilities missing from getopt(). Slay.

The function parses arguments from main() (using argc and argv), starting at the index referenced by idx. New invocations typically set the value pointed to by idx to 1.

Options get parsed according to spec (peep the Option Specification section below). The parsed option’s value gets stored at the address indicated by val, and idx gets incremented to reflect the next option to parse.

💡 Tip — If you’re parsing command-line-like strings that do not include the command name itself, set the value referenced by idx to zero instead of one. iykyk.

If the option had an argument, a pointer to that argument is returned at the address referenced by arg.

This function should be called repeatedly, until it returns either -1 (indicating the end of options is reached) or a non-zero error code is returned.

🛠️ Option Specification 🛠️

The calling program must first create an array of nng_optspec structures describing the options to be supported. This structure has these members:

• o_name — the long style name for the option, like "verbose". It gets parsed on the command line when it’s prefixed with two dashes. It may be NULL if only a short option is to be supported.
• o_short — a single letter (at present only ASCII letters are supported). These options appear as just a single letter, prefixed with a single dash on the command line. Using a slash in lieu of the dash is not supported, in order to avoid confusion with path name arguments. This value may be set to 0 if no short option is needed.
• o_val — a numeric value that is unique to this option. It’s assigned by the application program, and must be non-zero for a valid option. If this is zero, then it indicates the end of the specifications, and the rest of this structure is ignored. The value will be returned to the caller in val by nng_opts_parse() when this option is parsed from the command line.
• o_arg — this value should be set to true if the option should take an argument.

🌈 Long Options 🌈

Long options are parsed from the argv array, and they’re indicated when the element being scanned starts with two dashes. For example, the "verbose" option would be specified as --verbose on the command line. If a long option takes an argument, it can either immediately follow the option as the next element in argv, or it can be appended to the option, separated from the option by an equals sign (=) or a colon (:).

🦋 Short Options 🦋

Short options appear by themselves in an argv element, prefixed by a dash (-). If the short option takes an argument, it can either be appended in the same element of argv, or may appear in the next argv element.

📝 Note — Option clustering, where multiple options can be crammed together in a single argv element, is not supported by this function (yet). No sneaky little pile-ups, bestie.

👑 Prefix Matching 👑

When using long options, the parser will match if it is equal to a prefix of the o_name member of an option specification, provided that it does so unambiguously — meaning it must not match any other option specification.

🎀 EXAMPLE 🎀

The following program fragment demonstrates this function.

               enum { OPT_LOGFILE, OPT_VERBOSE };
               char *logfile; // options to be set
               bool verbose;

               static nng_optspec specs[] = {
                   {
                       .o_name = "logfile",
                       .o_short = 'D',
                       .o_val = OPT_LOGFILE,
                       .o_arg = true,
                   }, {
                       .o_name = "verbose",
                       .o_short = 'V',
                       .o_val = OPT_VERBOSE,
                       .o_arg = false,
                   }, {
                       .o_val = 0; // Terminate array
                   }
               };

               for (int idx = 1;;) {
                   int rv, opt;
                   char *arg;
                   rv = nng_opts_parse(argc, argv, specs, &opt, &arg, &idx);
                   if (rv != 0) {
                       break;
                   }
                   switch (opt) {
                   case OPT_LOGFILE:
                       logfile = arg;
                       break;
                   case OPT_VERBOSE:
                       verbose = true;
                       break;
                   }
               }
               if (rv != -1) {
                   printf("Options error: %s\n", nng_strerror(rv));
                   exit(1);
               }

🌟 RETURN VALUES 🌟

This function returns 0 if an option parsed correctly, -1 if no more options are available to be parsed, or an error number otherwise.

💀 ERRORS 💀

• NNG_EAMBIGUOUS — parsed option matches more than one specification.
• NNG_ENOARG — option requires an argument, but one is not present.
• NNG_EINVAL — an invalid (unknown) argument is present.

🔗 SEE ALSO 🔗

• nng_strerror(3)
• nng(7)

🫶 That’s the whole page, bestie — from the NNG Reference Manual, NNG_OPTS_PARSE(3supp), dated 2026-01-13. Mwah! 💋