Add code to export and print the description associated to sysctl

variables. Use the -d flag in sysctl(8) to see this information.

Possible extensions to sysctl:
 + report variables that do not have a description
 + given a name, report the oid it maps to.

Note to developers: have a look at your code, there are a number of
	variables which do not have a description.

Note to developers: do we want this in 4.5 ? It is a very small change
	and very useful for documentation purposes.

Suggested by: Orion Hodson

sbin/sysctl/sysctl.8

@@ -44,7 +44,7 @@
 .Ar name Ns Op = Ns Ar value
 .Ar ...
 .Nm
-.Op Fl beNnox
+.Op Fl bdeNnox
 .Fl a
 .Sh DESCRIPTION
 The
@@ -71,6 +71,8 @@ the command line.
 Force the value of the variable(s) to be output in raw, binary format.
 No names are printed and no terminating newlines are output.
 This is mostly useful with a single variable.
+.It Fl d
+Print the description of the variable instead of its value.
 .It Fl e
 Separate the name and the value of the variable(s) with
 .Ql = .

sbin/sysctl/sysctl.c

@@ -58,7 +58,7 @@ static const char rcsid[] =
 #include <string.h>
 #include <unistd.h>
 
-static int	aflag, bflag, eflag, Nflag, nflag, oflag, xflag;
+static int	aflag, bflag, dflag, eflag, Nflag, nflag, oflag, xflag;
 
 static int	oidfmt(int *, int, char *, u_int *);
 static void	parse(char *);
@@ -71,8 +71,8 @@ usage(void)
 {
 
 	(void)fprintf(stderr, "%s\n%s\n",
-	    "usage: sysctl [-beNnox] variable[=value] ...",
-	    "       sysctl [-beNnox] -a");
+	    "usage: sysctl [-bdeNnox] variable[=value] ...",
+	    "       sysctl [-bdeNnox] -a");
 	exit(1);
 }
 
@@ -83,7 +83,7 @@ main(int argc, char **argv)
 	setbuf(stdout,0);
 	setbuf(stderr,0);
 
-	while ((ch = getopt(argc, argv, "AabeNnowxX")) != -1) {
+	while ((ch = getopt(argc, argv, "AabdeNnowxX")) != -1) {
 		switch (ch) {
 		case 'A':
 			/* compatibility */
@@ -95,6 +95,9 @@ main(int argc, char **argv)
 		case 'b':
 			bflag = 1;
 			break;
+		case 'd':
+			dflag = 1;
+			break;
 		case 'e':
 			eflag = 1;
 			break;
@@ -409,6 +412,15 @@ show_var(int *oid, int nlen)
 	else
 		sep = ": ";
 
+	if (dflag) {	/* just print description */
+		qoid[1] = 5;
+		j = sizeof(buf);
+		i = sysctl(qoid, nlen + 2, buf, &j, 0, 0);
+		if (!nflag)
+			printf("%s%s", name, sep);
+		printf("%s", buf);
+		return (0);
+	}
 	/* find an estimate of how much we need for this var */
 	j = 0;
 	i = sysctl(oid, nlen, 0, &j, 0, 0);

sys/kern/kern_sysctl.c

@@ -310,6 +310,8 @@ sysctl_remove_oid(struct sysctl_oid *oidp, int del, int recurse)
 		}
 		sysctl_unregister_oid(oidp);
 		if (del) {
+			if (oidp->descr)
+				free(oidp->descr, M_SYSCTLOID);
 			free((void *)(uintptr_t)(const void *)oidp->oid_name,
 			     M_SYSCTLOID);
 			free(oidp, M_SYSCTLOID);
@@ -370,6 +372,12 @@ sysctl_add_oid(struct sysctl_ctx_list *clist, struct sysctl_oid_list *parent,
 		oidp->oid_arg2 = arg2;
 	}
 	oidp->oid_fmt = fmt;
+	if (descr) {
+		int len = strlen(descr) + 1;
+		oidp->descr = malloc(len, M_SYSCTLOID, M_WAITOK);
+		if (oidp->descr)
+			strcpy(oidp->descr, descr);
+	}
 	/* Update the context, if used */
 	if (clist != NULL)
 		sysctl_ctx_entry_add(clist, oidp);
@@ -409,6 +417,7 @@ SYSINIT(sysctl, SI_SUB_KMEM, SI_ORDER_ANY, sysctl_register_all, 0);
  * {0,2,...}	return the next OID.
  * {0,3}	return the OID of the name in "new"
  * {0,4,...}	return the kind & format info for the "..." OID.
+ * {0,5,...}	return the description the "..." OID.
  */
 
 static void
@@ -708,6 +717,24 @@ sysctl_sysctl_oidfmt(SYSCTL_HANDLER_ARGS)
 
 SYSCTL_NODE(_sysctl, 4, oidfmt, CTLFLAG_RD, sysctl_sysctl_oidfmt, "");
 
+static int
+sysctl_sysctl_oiddescr(SYSCTL_HANDLER_ARGS)
+{
+	struct sysctl_oid *oid;
+	int error;
+
+	error = sysctl_find_oid(arg1, arg2, &oid, NULL, req);
+	if (error)
+		return (error);
+
+	if (!oid->descr)
+		return (ENOENT);
+	error = SYSCTL_OUT(req, oid->descr, strlen(oid->descr) + 1);
+	return (error);
+}
+
+SYSCTL_NODE(_sysctl, 5, oiddescr, CTLFLAG_RD, sysctl_sysctl_oiddescr, "");
+
 /*
  * Default "handler" functions.
  */

sys/sys/sysctl.h

@@ -140,6 +140,7 @@ struct sysctl_oid {
 	int 		(*oid_handler)(SYSCTL_HANDLER_ARGS);
 	const char	*oid_fmt;
 	int		oid_refcnt;
+	char		*descr;
 };
 
 #define SYSCTL_IN(r, p, l) (r->newfunc)(r, p, l)
@@ -181,7 +182,7 @@ TAILQ_HEAD(sysctl_ctx_list, sysctl_ctx_entry);
 #define SYSCTL_OID(parent, nbr, name, kind, a1, a2, handler, fmt, descr) \
 	static struct sysctl_oid sysctl__##parent##_##name = {		 \
 		&sysctl_##parent##_children, { 0 },			 \
-		nbr, kind, a1, a2, #name, handler, fmt, 0 };		 \
+		nbr, kind, a1, a2, #name, handler, fmt, 0, descr };	 \
 	DATA_SET(sysctl_set, sysctl__##parent##_##name);
 
 #define SYSCTL_ADD_OID(ctx, parent, nbr, name, kind, a1, a2, handler, fmt, descr) \