[PATCH 5/7] request-key: Add help text

[David Howells <dhowells@redhat.com>]

Add --help text to /sbin/request-key.

Signed-off-by: David Howells <dhowells@redhat.com>
---
 man/request-key.8 | 42 +++++++++++++++++++++++++++-------
 request-key.c     | 57 ++++++++++++++++++++++++++++++++++++++++++-----
 2 files changed, 85 insertions(+), 14 deletions(-)

diff --git a/man/request-key.8 b/man/request-key.8
index 50a7506..15b6bb8 100644
--- a/man/request-key.8
+++ b/man/request-key.8
@@ -7,20 +7,37 @@
 .\" as published by the Free Software Foundation; either version
 .\" 2 of the License, or (at your option) any later version.
 .\"
-.TH REQUEST-KEY 8 "15 Nov 2011" Linux "Linux Key Management Utilities"
+.TH REQUEST-KEY 8 "22 Aug 2025" Linux "Linux Key Management Utilities"
 .SH NAME
 request\-key \- handle key instantiation callback requests from the kernel
 .SH SYNOPSIS
-\fB/sbin/request\-key \fR<op> <key> <uid> <gid> <threadring> <processring>
-	<sessionring> [<info>]
+.nf
+\fB/sbin/request\-key\fP [\fB--help\fP|\fB--version\fP]
+\fB/sbin/request\-key\fP \fIop key uid gid t-ring p-ring s-ring\fP [\fIinfo\fP]
+\fB/sbin/request\-key -d [-lnv] -D\fP \fIdesc\fP \fIop key\fP...
+.fi
 .SH DESCRIPTION
 This program is invoked by the kernel when the kernel is asked for a key that
 it doesn't have immediately available. The kernel creates a partially set up
-key and then calls out to this program to instantiate it. It is not intended
-to be called directly.
+key and then calls out to this program to instantiate it. It is not intended to
+be called directly.  A debugging capability is available through command line
+options, however, to aid in testing and in debugging configuration.
 .PP
-However, for debugging purposes, it can be given some options on the command
-line:
+The normally required parameters are:
+.IP \fBop\fP
+The operation being done, such as "create" if a key is being instantiated for
+creation.
+.IP \fBkey\fP
+The ID of the key being operated upon.
+.IP "\fBuid\fP, \fBgid\fP"
+The ownership of the task that caused the key to be created.
+.IP "\fBt-ring\fP, \fBp-ring\fP, \fBs-ring\fP"
+The thread, process and session keyrings of the task that caused the key to be
+created.
+.IP \fBinfo\fP
+The optional callout info that can be passed by \fIrequest_key(2)\fP.
+.PP
+The options that may also be supplied are:
 .IP \fB-d\fP
 Turn on debugging mode.  In this mode, no attempts are made to access any keys
 and, if a handler program is selected, it won't be executed; instead, this
@@ -39,10 +56,19 @@ will be copied to the system log - this will prevent that.
 .IP \fB-v\fP
 Turn on debugging output.  This may be specified multiple times to produce
 increasing levels of verbosity.
+.IP \fB--help\fP
+Print help text and exit.
 .IP \fB--version\fP
 Print the program version and exit.
+.SH EXAMPLES
+When using the debugging mode, all the parameters must be given, though a lot
+of them don't matter and can be just set to 0, e.g.:
+.PP
+.nf
+request-key -d -D "user;0;0;0;debug:bar" create 0 0 0 0 0 0 foo
+.fi
 .SH ERRORS
-All errors will be logged to the syslog.
+All errors will be logged to the syslog unless the \fB-n\fP option is given.
 .SH FILES
 .ul
 /etc/request\-key.d/*.conf
diff --git a/request-key.c b/request-key.c
index d1feec3..9a7d741 100644
--- a/request-key.c
+++ b/request-key.c
@@ -111,7 +111,7 @@ static void error(const char *fmt, ...)
 {
 	va_list va;
 
-	if (verbosity) {
+	if (verbosity || debug_mode) {
 		va_start(va, fmt);
 		vfprintf(stderr, fmt, va);
 		va_end(va);
@@ -138,6 +138,45 @@ static void oops(int x)
 	error("Died on signal %d", x);
 }
 
+static const char help_text[] =
+	"Usage: request-key [OPTIONS] [PARAMS]\n"
+	"       request-key [OPTIONS] -d -D <desc> [PARAMS]\n"
+	"\n"
+	"Where the required parameters, [PARAMS], are, in order:\n"
+	"  <op>     : The operation type (e.g. 'create')\n"
+	"  <key>    : The ID of the key to be operated upon\n"
+	"  <uid>    : The UID of the requesting process\n"
+	"  <gid>    : The GID of the requesting process\n"
+	"  <t-ring> : The thread keyring of the requesting process (or 0)\n"
+	"  <p-ring> : The process keyring of the requesting process (or 0)\n"
+	"  <s-ring> : The session keyring of the requesting process (or 0)\n"
+	"  <callout>: The callout data supplied to the request\n"
+	"\n"
+	"and [OPTIONS] are none or more of\n"
+	"  -d       : Debug mode for direct cmdline testing\n"
+	"  -D <desc>: Description for debug mode\n"
+	"  -l       : Use config from local dir, not /etc\n"
+	"  -n       : Don't log to syslog\n"
+	"  -v       : Turn up verbosity (can use multiple times)\n"
+	"  --version: Print version and exit\n"
+	"  --help   : Print this text and exit\n"
+	"\n"
+	"Service program lookup testing can be done with the '-d' option, but\n"
+	"as there is no actual key to query, the called must supply the key's\n"
+	"attributes manually using '-D' in the form returned by the\n"
+	"'keyctl rdescribe' command, for example:\n"
+	"\n"
+	"  ./request-key -d -D \"user;0;0;0;debug:bar\" create 0 0 0 0 0 0 foo\n"
+	"\n"
+	"where 'user' is the key type and 'debug:bar' is the key description.\n"
+	;
+
+static struct option long_options[] = {
+	{ .name = "help",	.val = 1 },
+	{ .name = "version",	.val = 2 },
+	{}
+};
+
 /*****************************************************************************/
 /*
  *
@@ -149,19 +188,25 @@ int main(int argc, char *argv[])
 	char *buf;
 	int ret, ntype, dpos, n, fd, opt;
 
-	if (argc == 2 && strcmp(argv[1], "--version") == 0) {
-		printf("request-key from %s (Built %s)\n",
-		       keyutils_version_string, keyutils_build_string);
-		return 0;
+	if (argc == 1) {
+		fputs(help_text, stderr);
+		exit(2);
 	}
 
 	signal(SIGSEGV, oops);
 	signal(SIGBUS, oops);
 	signal(SIGPIPE, SIG_IGN);
 
-	while (opt = getopt(argc, argv, "D:dlnv"),
+	while (opt = getopt_long(argc, argv, "D:dlnv", long_options, NULL),
 	       opt != -1) {
 		switch (opt) {
+		case 1:
+			fputs(help_text, stderr);
+			exit(2);
+		case 2:
+			printf("request-key from %s (Built %s)\n",
+			       keyutils_version_string, keyutils_build_string);
+			return 0;
 		case 'D':
 			test_desc = optarg;
 			break;