diff options
Diffstat (limited to 'ref/print.html')
| -rw-r--r-- | ref/print.html | 129 |
1 files changed, 77 insertions, 52 deletions
diff --git a/ref/print.html b/ref/print.html index 1c2806df..00a5ad95 100644 --- a/ref/print.html +++ b/ref/print.html @@ -3621,8 +3621,6 @@ as in diagnostic messages or log entries.</p> <tr><td><code>NNG_EWRITEONLY</code><a name="NNG_EWRITEONLY"></a></td><td>25</td><td>Write only resource. A read operation failed because the object only supports writes.</td></tr> <tr><td><code>NNG_ECRYPTO</code><a name="NNG_ECRYPTO"></a></td><td>26</td><td>Cryptographic error. Usually indicates an invalid key was used for TLS.</td></tr> <tr><td><code>NNG_EPEERAUTH</code><a name="NNG_EPEERAUTH"></a></td><td>27</td><td>Peer could not be authenticated.</td></tr> -<tr><td><code>NNG_ENOARG</code><a name="NNG_ENOARG"></a></td><td>28</td><td>Option requires argument. A command-line option was supplied without an argument. Only used with <a href="api//api/cmd_opts.html#parse-command-line-options"><code>nng_opts_parse</code></a>.</td></tr> -<tr><td><code>NNG_EAMBIGUOUS</code><a name="NNG_EAMBIGUOUS"></a></td><td>29</td><td>Ambiguous option. The command line option could not be unambiguously resolved. Only used with <a href="api//api/cmd_opts.html#parse-command-line-options"><code>nng_opts_parse</code></a>.</td></tr> <tr><td><code>NNG_EBADTYPE</code><a name="NNG_EBADTYPE"></a></td><td>30</td><td>Incorrect type. A type-specific function was used for an object of the wrong type.</td></tr> <tr><td><code>NNG_ECONNSHUT</code><a name="NNG_ECONNSHUT"></a></td><td>31</td><td>Connection shutdown. The connection was shut down and cannot be used.</td></tr> <tr><td><code>NNG_ESTOPPED</code><a name="NNG_ESTOPPED"></a></td><td>1000</td><td>Operation stopped. The operation was stopped with <a href="api//api/aio.html#cancellation"><code>nng_aio_stop</code></a> or [<code>nng_aio_close</code>].</td></tr> @@ -4411,34 +4409,46 @@ Given a sufficiently large range, this is unlikely to be a concern.</p> } </style> -<h1 id="command-options"><a class="header" href="#command-options">Command Options</a></h1> -<p>Some <em>NNG</em> utilities need to parse command line options, -and the supplementary function here allows applications that -need the same support to benefit from this.</p> -<p>To make use of this, the supplemental header <code><nng/supplemental/util/options.h></code> -must be included.</p> -<h2 id="parse-command-line-options"><a class="header" href="#parse-command-line-options">Parse Command Line Options</a></h2> -<pre><code class="language-c">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 +<h1 id="command-arguments"><a class="header" href="#command-arguments">Command Arguments</a></h1> +<p>Some NNG utilities need to parse command line options, +and for this purpose a header library is supplied.</p> +<p>To make use of this, the header <code><nng/args.h></code> must be included.</p> +<div class="mdbook-alerts mdbook-alerts-tip"> +<p class="mdbook-alerts-title"> + <span class="mdbook-alerts-icon"></span> + tip +</p> +<p>The functionality described here is entirely contained in the +<code>nng/args.h</code> header file, and may be used without previously +initializing the library with <a href="api//api/init.html#initialization"><code>nng_init</code></a>, and may even be used +in programs that are not linked against the NNG library.</p> +</div> +<h2 id="parse-command-line-arguments"><a class="header" href="#parse-command-line-arguments">Parse Command Line Arguments</a></h2> +<pre><code class="language-c">typedef struct nng_arg_spec { + const char *a_name; // Long style name (may be NULL for short only) + int a_short; // Short option (no clustering!) + int a_val; // Value stored on a good parse (>0) + bool a_arg; // Option takes an argument if true } nng_optspec; -int nng_opts_parse(int argc, char *const *argv, +#define NNG_ARG_END (-1) +#define NNG_ARG_INVAL (-2) +#define NNG_ARG_AMBIG (-3) +#define NNG_ARG_MISSING (-4) + +int nng_args_parse(int argc, char *const *argv, const nng_optspec *spec, int *val, char **arg, int *idx); </code></pre> -<p>The <a name="a001"></a><code>nng_opts_parse</code> function is a intended to facilitate parsing +<p>The <a name="a001"></a><code>nng_args_parse</code> function is intended to facilitate parsing <a name="a002"></a>command-line arguments. This function exists largely to stand in for <a name="a003"></a><code>getopt</code> from POSIX systems, -but it is available everywhere that <em>NNG</em> is, and it includes -some capabilities missing from <code>getopt</code>.</p> +but it is available on all platforms, and it includes some capabilities missing from <code>getopt</code>.</p> <p>The function parses arguments from -<code>main</code><sup><a name="to-footnote-1"><a href="api/cmd_opts.html#footnote-1">1</a></a></sup> +<code>main</code><sup><a name="to-footnote-1"><a href="api/args.html#footnote-1">1</a></a></sup> (using <em>argc</em> and <em>argv</em>), starting at the index referenced by <em>idx</em>. (New invocations typically set the value pointed to by <em>idx</em> to 1.)</p> -<p>Options are parsed as specified by <em>spec</em> (see <a href="api/cmd_opts.html#option-specification">Option Specification</a>.) +<p>Options are parsed as specified by <em>spec</em> (see <a href="api/args.html#argument-specification">Argument Specification</a>.) The value of the parsed option will be stored at the address indicated by <em>val</em>, and the value of <em>idx</em> will be incremented to reflect the next option to parse.</p> @@ -4457,27 +4467,27 @@ referenced by <em>arg</em>.</p> returned.</p> <p>This function may return the following errors:</p> <ul> -<li><a href="api//api/errors.html#NNG_EAMBIGUOUS"><code>NNG_EAMBIGUOUS</code></a>: Parsed option matches more than one specification.</li> -<li><a href="api//api/errors.html#NNG_ENOARG"><code>NNG_ENOARG</code></a>: Option requires an argument, but one is not present.</li> -<li><a href="api//api/errors.html#NNG_EINVAL"><code>NNG_EINVAL</code></a>: An invalid (unknown) argument is present.</li> +<li>[<code>NNG_ARG_AMBIGU</code>]: Parsed option matches more than one specification.</li> +<li>[<code>NNG_ARG_MISSING</code>]: Option requires an argument, but one is not present.</li> +<li>[<code>NNG_ARG_INVAL</code>]: An invalid (unknown) argument is present in <em>argv</em>.</li> </ul> <h3 id="option-specification"><a class="header" href="#option-specification">Option Specification</a></h3> -<p>The calling program must first create an array of <a name="a004"></a><code>nng_optspec</code> structures +<p>The calling program must first create an array of <a name="a004"></a><code>nng_arg_spec</code> structures describing the options to be supported. This structure has the following members:</p> <ul> <li> -<p><code>o_name</code>:</p> +<p><code>a_name</code>:</p> <p>The long style name for the option, such as “verbose”. -This will be parsed as a <a href="api/cmd_opts.html#long-options">long option</a> on the command line when it is prefixed with two dashes. -It may be <code>NULL</code> if only a <a href="api/cmd_opts.html#short-options">short option</a> is to be supported.</p> +This will be parsed as a <a href="api/args.html#long-options">long option</a> on the command line when it is prefixed with two dashes. +It may be <code>NULL</code> if only a <a href="api/args.html#short-options">short option</a> is to be supported.</p> </li> <li> -<p><code>o_short</code>:</p> +<p><code>a_short</code>:</p> <p>This is a single letter (at present only ASCII letters are supported). These options appear as just a single letter, and are prefixed with a single dash on the command line. The use of a slash in lieu of the dash is <em>not</em> supported, in order to avoid confusion with path name arguments. -This value may be set to 0 if no <a href="api/cmd_opts.html#short-options">short option</a> is needed.</p> +This value may be set to 0 if no <a href="api/args.html#short-options">short option</a> is needed.</p> </li> <li> <p><code>o_val</code>:</p> @@ -4485,11 +4495,11 @@ This value may be set to 0 if no <a href="api/cmd_opts.html#short-options">short This value is 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 <em>val</em> by <code>nng_opts_parse</code> when +The value will be returned to the caller in <em>val</em> by <code>nng_args_parse</code> when this option is parsed from the command line.</p> </li> <li> -<p><code>o_arg</code>:</p> +<p><code>a_arg</code>:</p> <p>This value should be set to <code>true</code> if the option should take an argument.</p> </li> </ul> @@ -4516,7 +4526,7 @@ a single <em>argv</em> element, is not supported by this function (yet).</p> </div> <h3 id="prefix-matching"><a class="header" href="#prefix-matching">Prefix Matching</a></h3> <p>When using long options, the parser will match if it is equal to a prefix -of the <code>o_name</code> member of a option specification, provided that it do so +of the <code>a_name</code> member of a option specification, provided that it do so unambiguously (meaning it must not match any other option specification.)</p> <h2 id="example"><a class="header" href="#example">Example</a></h2> <p>The following program fragment demonstrates this function.</p> @@ -4524,26 +4534,26 @@ unambiguously (meaning it must not match any other option specification.)</p> char *logfile; // options to be set bool verbose; - static nng_optspec specs[] = { + static nng_arg_spec specs[] = { { - .o_name = "logfile", - .o_short = 'D', - .o_val = OPT_LOGFILE, - .o_arg = true, + .a_name = "logfile", + .a_short = 'D', + .a_val = OPT_LOGFILE, + .a_arg = true, }, { - .o_name = "verbose", - .o_short = 'V', - .o_val = OPT_VERBOSE, - .o_arg = false, + .a_name = "verbose", + .a_short = 'V', + .a_val = OPT_VERBOSE, + .a_arg = false, }, { - .o_val = 0; // Terminate array + .a_val = 0; // Terminate array } }; for (int idx = 1;;) { int rv, opt; char *arg; - rv = nng_opts_parse(argc, argv, specs, &opt, &arg, &idx); + rv = nng_args_parse(argc, argv, specs, &opt, &arg, &idx); if (rv != 0) { break; } @@ -4556,8 +4566,18 @@ unambiguously (meaning it must not match any other option specification.)</p> break; } } - if (rv != -1) { - printf("Options error: %s\n", nng_strerror(rv)); + if (rv != NNG_ARG_END) { + switch (rv) { + case NNG_ARG_AMBIG: + printf("Options error: ambiguous option\n"); + break; + case NNG_ARG_MISSING: + printf("Options error: required option argument missing\n"); + break; + case NNG_ARG_INVAL: + printf("Options error: unknown option present\n"); + break; + } exit(1); } </code></pre> @@ -4567,7 +4587,7 @@ unambiguously (meaning it must not match any other option specification.)</p> <!-- Transports --> <!-- Concept index --> <p><hr/> -<p><a name="footnote-1"><a href="api/cmd_opts.html#to-footnote-1">1</a></a>: Parsing argument strings from other sources can be done as well, +<p><a name="footnote-1"><a href="api/args.html#to-footnote-1">1</a></a>: Parsing argument strings from other sources can be done as well, although usually then <em>idx</em> will be initialized to zero.</p> <div style="break-before: page; page-break-before: always;"></div><style> .mdbook-alerts { @@ -6813,12 +6833,13 @@ This was implemented mostly to aid legacy nanomsg applications, and it was both suboptimal in terms of performance.</p> <p>Modern code should use one of <a href="migrate//api/sock.html#nng_sendmsg"><code>nng_sendmsg</code></a>, <a href="migrate//api/sock.html#nng_recvmsg"><code>nng_recvmsg</code></a>, <a href="migrate//api/sock.html#nng_socket_send"><code>nng_socket_send</code></a>, or <a href="migrate//api/sock.html#nng_socket_recv"><code>nng_socket_recv</code></a> to get the maximum performance benefit. Working directly with <a href="migrate//api/msg.html#message-structure"><code>nng_msg</code></a> structures gives more control, reduces copies, and reduces allocation activity.</p> -<h2 id="new-aio-error-code-nng_estopped"><a class="header" href="#new-aio-error-code-nng_estopped">New AIO Error Code NNG_ESTOPPED</a></h2> +<h2 id="error-code-changes"><a class="header" href="#error-code-changes">Error Code Changes</a></h2> <p>When an operation fails with <a href="migrate//api/errors.html#NNG_ESTOPPED"><code>NNG_ESTOPPED</code></a>, it means that the associated [<code>nni_aio</code>] object has been permanently stopped and must not be reused. Applications must watch for this error code, and not resubmit an operation that returns it. This is particularly important for callbacks that automatically resubmit operations. Failure to observe this rule will lead to an infinite loop as any further operations on the object will fail immediately with <code>NNG_ESTOPPED</code>.</p> +<p>The error codes <code>NNG_EAMBIGUOUS</code> and <code>NNG_ENOARG</code> have been removed.</p> <h2 id="aio-provider-api-changes"><a class="header" href="#aio-provider-api-changes">AIO Provider API changes</a></h2> <p>The API used for providers for asynchronous I/O operations has changed slightly.</p> <ul> @@ -7042,6 +7063,10 @@ with the functions [<code>nng_listener_get_security_descriptor</code>] and and is presently only supported for IPC when Named Pipes are used. Planned future changes to switch to UNIX domain sockets may eliminate support for security descriptors altogether in NNG.</p> +<h2 id="command-line-argument-parser-changes"><a class="header" href="#command-line-argument-parser-changes">Command Line Argument Parser Changes</a></h2> +<p>The supplemental function <code>nng_opts_parse</code> and supporting definitions have moved. +This functionality is now supplied by a header only library, available in <code>nng/args.h</code>. +See <a href="migrate//api/args.html#parse-command-line-arguments"><code>nng_args_parse</code></a> for more information.</p> <h2 id="zerotier-support-removed"><a class="header" href="#zerotier-support-removed">ZeroTier Support Removed</a></h2> <p>The Layer 2 special ZeroTier transport has been removed. It is possible to use NNG with ZeroTier using TCP/IP, and a future update @@ -7202,7 +7227,7 @@ There are some exceptions. Be aware that the numeric values are <em>not</em> the <div class="table-wrapper"><table><thead><tr><th>Nanomsg Error</th><th>NNG Error</th><th>Notes</th></tr></thead><tbody> <tr><td><code>EINTR</code></td><td><a href="migrate//api/errors.html#NNG_EINTR"><code>NNG_EINTR</code></a></td><td></td></tr> <tr><td><code>ENOMEM</code></td><td><a href="migrate//api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a></td><td></td></tr> -<tr><td><code>EINVAL</code></td><td><a href="migrate//api/errors.html#NNG_EINVAL"><code>NNG_EINVAL</code></a>, <a href="migrate//api/errors.html#NNG_EADDRINVAL"><code>NNG_EADDRINVAL</code></a>, <a href="migrate//api/errors.html#NNG_EBADTYPE"><code>NNG_EBADTYPE</code></a>, <a href="migrate//api/errors.html#NNG_EAMBIGUOUS"><code>NNG_EAMBIGUOUS</code></a></td><td>NNG discrimates between different types of errors.</td></tr> +<tr><td><code>EINVAL</code></td><td><a href="migrate//api/errors.html#NNG_EINVAL"><code>NNG_EINVAL</code></a>, <a href="migrate//api/errors.html#NNG_EADDRINVAL"><code>NNG_EADDRINVAL</code></a>, <a href="migrate//api/errors.html#NNG_EBADTYPE"><code>NNG_EBADTYPE</code></a></td><td>NNG discrimates between different types of errors.</td></tr> <tr><td><code>EBUSY</code></td><td><a href="migrate//api/errors.html#NNG_EBUSY"><code>NNG_EBUSY</code></a></td><td></td></tr> <tr><td><code>ETIMEDOUT</code></td><td><a href="migrate//api/errors.html#NNG_ETIMEDOUT"><code>NNG_ETIMEDOUT</code></a></td><td></td></tr> <tr><td><code>ECONNREFUSED</code></td><td><a href="migrate//api/errors.html#NNG_ECONNREFUSED"><code>NNG_ECONNREFUSED</code></a></td><td></td></tr> @@ -7252,7 +7277,7 @@ body, <a href="api/msg.html#a002">1</a><br/> <em>BUS</em> protocol, <a href="proto/bus.html#a001">1</a><br/> callback, <a href="api/aio.html#a005">1</a><br/> clock, <a href="api/time.html#a008">1</a><br/> -command-line arguments, <a href="api/cmd_opts.html#a002">1</a><br/> +command-line arguments, <a href="api/args.html#a002">1</a><br/> concurrency, <a href="api/thread.html#a002">1</a><br/> concurrent, <a href="api/ctx.html#a002">1</a><br/> condition variable, <a href="api/synch.html#a009">1</a><br/> @@ -7264,7 +7289,7 @@ error message, <a href="api/errors.html#a002">1</a><br/> event loop, <a href="api/sock.html#a042">1</a><br/> flow control, <a href="proto/index.html#a006">1</a><br/> gather, <a href="api/aio.html#a024">1</a><br/> -<code>getopt</code>, <a href="api/cmd_opts.html#a003">1</a><br/> +<code>getopt</code>, <a href="api/args.html#a003">1</a><br/> half-duplex, <a href="proto/index.html#a004">1</a><br/> header, <a href="api/msg.html#a003">1</a><br/> idempotent, <a href="proto/req.html#a004">1</a><br/> @@ -7304,6 +7329,8 @@ named pipes, <a href="tran/ipc.html#a004">1</a><br/> <code>nng_aio_stop</code>, <a href="api/aio.html#a011">1</a><br/> <code>nng_aio_wait</code>, <a href="api/aio.html#a014">1</a><br/> <code>nng_alloc</code>, <a href="api/memory.html#a003">1</a><br/> +<code>nng_arg_spec</code>, <a href="api/args.html#a004">1</a><br/> +<code>nng_args_parse</code>, <a href="api/args.html#a001">1</a><br/> <code>nng_bus0_open</code>, <a href="api/sock.html#a009">1</a><br/> <code>nng_bus0_open_raw</code>, <a href="api/sock.html#a022">1</a><br/> <code>nng_clock</code>, <a href="api/time.html#a007">1</a><br/> @@ -7386,8 +7413,6 @@ named pipes, <a href="tran/ipc.html#a004">1</a><br/> <code>NNG_OPT_SOCKET_FD</code>, <a href="tran/socket.html#a002">1</a><br/> <code>NNG_OPT_SUB_PREFNEW</code>, <a href="proto/sub.html#a004">1</a><br/> <code>NNG_OPT_SURVEYOR_SURVEYTIME</code>, <a href="proto/surveyor.html#a007">1</a><br/> -<code>nng_opts_parse</code>, <a href="api/cmd_opts.html#a001">1</a><br/> -<code>nng_optspec</code>, <a href="api/cmd_opts.html#a004">1</a><br/> <code>nng_pair0_open</code>, <a href="api/sock.html#a010">1</a><br/> <code>nng_pair0_open_raw</code>, <a href="api/sock.html#a023">1</a><br/> <code>nng_pair1_open</code>, <a href="api/sock.html#a011">1</a><br/> |