diff options
| -rw-r--r-- | man/usage.3 | 73 |
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 |