aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorThomas Voss <mail@thomasvoss.com> 2024-04-27 20:49:33 +0200
committerThomas Voss <mail@thomasvoss.com> 2024-04-27 20:49:33 +0200
commit95c062edfa87cda142cc617bb0b4e21a644f4a15 (patch)
tree68665b15229b9aab33447ae33afa00b9b203c6e9
parente3e3dc622662f3e2cd0397b02ca1370d733ca226 (diff)
Add the usage(3) manual
-rw-r--r--man/usage.373
1 files changed, 73 insertions, 0 deletions
diff --git a/man/usage.3 b/man/usage.3
new file mode 100644
index 0000000..fcd49bf
--- /dev/null
+++ b/man/usage.3
@@ -0,0 +1,73 @@
+.Dd 27 April 2024
+.Dt USAGE 3
+.Os
+.Sh NAME
+.Nm usage
+.Nd print a program usage diagnostic
+.Sh LIBRARY
+.Lb mlib
+.Sh SYNOPSIS
+.In errors.h
+.Ft void
+.Fn usage "const char *s" "..."
+.Sh DESCRIPTION
+The
+.Fn usage
+macro prints a program usage diagnostic to the standard error.
+The one-or-more program usages are provided as null-terminated strings to
+.Fn usage ,
+and the program name must be set via a prior invocation of
+.Fn mlib_setprogname .
+None of the provided arguments should be
+.Dv nullptr .
+.Sh EXAMPLES
+The following call to
+.Fn usage
+prints a diagnostic showing the different command-line arguments that can
+be provided to the example executable.
+.Bd -literal -offset indent
+#include <stdlib.h>
+
+#include <errors.h>
+#include <macros.h>
+#include <optparse.h>
+
+static const struct op_option opts[] = {
+ {'a', nullptr, OPT_NONE},
+ {'b', nullptr, OPT_NONE},
+ {'h', nullptr, OPT_NONE},
+};
+
+int
+main(int argc, char **argv)
+{
+ mlib_setprogname("my-prog");
+
+ rune opt;
+ struct optparse op = mkoptparser(argv);
+ while (opt = optparse(&op, opts, lengthof(opts))) {
+ switch (opt) {
+ /* … */
+ case 'h':
+ [[fallthrough]];
+ default:
+ /* Prints the following diagnostic:
+
+ Usage: my-prog [-ab]
+ my-prog -h
+ */
+ usage("[-ab]", "-h");
+ exit(opt == 'h' ? EXIT_SUCCESS : EXIT_FAILURE);
+ }
+ }
+
+ /* … */
+
+ return EXIT_SUCCESS;
+}
+.Ed
+.Sh SEE ALSO
+.Xr mlib_setprogname 3 ,
+.Xr optparse.h 3
+.Sh AUTHORS
+.An Thomas Voss Aq Mt mail@thomasvoss.com