DB_COMMAND(9): update to mention additional macros

Document the existing alias definitions, and augment the example with
one of these. Also, describe the purpose of the newly added _FLAGS
variations of these command definitions.

Make some small style improvements to appease mandoc -Tlint.

Reviewed by:	markj
MFC after:	3 days
Sponsored by:	Juniper Networks, Inc.
Sponsored by:	Klara, Inc.
Differential Revision:	https://reviews.freebsd.org/D35664

share/man/man9/DB_COMMAND.9

@@ -25,22 +25,33 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd August 27, 2008
+.Dd June 24, 2022
 .Dt DB_COMMAND 9
 .Os
 .Sh NAME
 .Nm DB_COMMAND ,
+.Nm DB_COMMAND_FLAGS ,
 .Nm DB_SHOW_COMMAND ,
-.Nm DB_SHOW_ALL_COMMAND
+.Nm DB_SHOW_COMMAND_FLAGS ,
+.Nm DB_SHOW_ALL_COMMAND ,
+.Nm DB_ALIAS ,
+.Nm DB_ALIAS_FLAGS ,
+.Nm DB_SHOW_ALIAS ,
+.Nm DB_SHOW_ALIAS_FLAGS ,
+.Nm DB_SHOW_ALL_ALIAS
 .Nd Extends the ddb command set
 .Sh SYNOPSIS
 .In ddb/ddb.h
-.Fo DB_COMMAND
-.Fa command_name
-.Fa command_function
-.Fc
+.Fn DB_COMMAND "command_name" "command_function"
+.Fn DB_COMMAND_FLAGS "command_name" "command_function" "flags"
 .Fn DB_SHOW_COMMAND "command_name" "command_function"
+.Fn DB_SHOW_COMMAND_FLAGS "command_name" "command_function" "flags"
 .Fn DB_SHOW_ALL_COMMAND "command_name" "command_function"
+.Fn DB_ALIAS "alias_name" "command_function"
+.Fn DB_ALIAS_FLAGS "alias_name" "command_function" "flags"
+.Fn DB_SHOW_ALIAS "alias_name" "command_function"
+.Fn DB_SHOW_ALIAS_FLAGS "alias_name" "command_function" "flags"
+.Fn DB_SHOW_ALL_ALIAS "alias_name" "command_function"
 .Sh DESCRIPTION
 The
 .Fn DB_COMMAND
@@ -56,7 +67,7 @@ The
 .Fn DB_SHOW_COMMAND
 and
 .Fn DB_SHOW_ALL_COMMAND
-are roughly equivalent to
+macros are roughly equivalent to
 .Fn DB_COMMAND
 but in these cases,
 .Fa command_name
@@ -66,6 +77,25 @@ command and
 .Sy show all
 command, respectively.
 .Pp
+The
+.Fn DB_ALIAS ,
+.Fn DB_SHOW_ALIAS ,
+and
+.Fn DB_SHOW_ALL_ALIAS
+macros register the exsting
+.Fa command_function
+under the alternative command name
+.Fa alias_name .
+.Pp
+The _FLAGS variants of these commands allow the programmer to specify a value
+for the
+.Fa flag
+field of the command structure.
+The possible flag values are defined alongside
+.Ft struct db_command
+in
+.In ddb/ddb.h .
+.Pp
 The general command syntax:
 .Cm command Ns Op Li \&/ Ns Ar modifier
 .Ar address Ns Op , Ns Ar count ,
@@ -87,7 +117,7 @@ For example, the
 .Sy examine
 command will display words in decimal form if it is passed the modifier "d".
 .El
-.Sh EXAMPLE
+.Sh EXAMPLES
 In your module, the command is declared as:
 .Bd -literal
 DB_COMMAND(mycmd, my_cmd_func)
@@ -97,11 +127,18 @@ DB_COMMAND(mycmd, my_cmd_func)
 }
 .Ed
 .Pp
+An alias for this command is declared as:
+.Bd -literal
+DB_ALIAS(mycmd2, my_cmd_func);
+.Ed
+.Pp
 Then, when in ddb:
 .Bd -literal
 .Bf Sy
 db> mycmd 0x1000
 Calling my command with address 0x1000
+db> mycmd2 0x2500
+Calling my command with address 0x2500
 db>
 .Ef
 .Ed

share/man/man9/Makefile

@@ -965,8 +965,15 @@ MLINKS+=crypto_session.9 crypto_auth_hash.9 \
 	crypto_session.9 crypto_get_params.9 \
 	crypto_session.9 crypto_newsession.9 \
 	crypto_session.9 crypto_freesession.9
-MLINKS+=DB_COMMAND.9 DB_SHOW_ALL_COMMAND.9 \
-	DB_COMMAND.9 DB_SHOW_COMMAND.9
+MLINKS+=DB_COMMAND.9 DB_ALIAS.9 \
+	DB_COMMAND.9 DB_ALIAS_FLAGS.9 \
+	DB_COMMAND.9 DB_COMMAND_FLAGS.9 \
+	DB_COMMAND.9 DB_SHOW_ALIAS.9 \
+	DB_COMMAND.9 DB_SHOW_ALIAS_FLAGS.9 \
+	DB_COMMAND.9 DB_SHOW_ALL_ALIAS.9 \
+	DB_COMMAND.9 DB_SHOW_ALL_COMMAND.9 \
+	DB_COMMAND.9 DB_SHOW_COMMAND.9 \
+	DB_COMMAND.9 DB_SHOW_COMMAND_FLAGS.9
 MLINKS+=DECLARE_MODULE.9 DECLARE_MODULE_TIED.9
 MLINKS+=dev_clone.9 drain_dev_clone_events.9
 MLINKS+=dev_refthread.9 devvn_refthread.9 \