git: b83d53cb687e - main - DB_COMMAND(9): update to mention additional macros

From: Mitchell Horne <mhorne_at_FreeBSD.org>
Date: Tue, 05 Jul 2022 15:09:01 UTC
The branch main has been updated by mhorne:

URL: https://cgit.FreeBSD.org/src/commit/?id=b83d53cb687e65372dd23496578c436243b11c93

commit b83d53cb687e65372dd23496578c436243b11c93
Author:     Mitchell Horne <mhorne@FreeBSD.org>
AuthorDate: 2022-07-05 14:55:18 +0000
Commit:     Mitchell Horne <mhorne@FreeBSD.org>
CommitDate: 2022-07-05 14:56:55 +0000

    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 | 53 ++++++++++++++++++++++++++++++++++++++-------
 share/man/man9/Makefile     | 11 ++++++++--
 2 files changed, 54 insertions(+), 10 deletions(-)

diff --git a/share/man/man9/DB_COMMAND.9 b/share/man/man9/DB_COMMAND.9
index b116a372fbfe..5bd224156f0f 100644
--- a/share/man/man9/DB_COMMAND.9
+++ b/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
diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index e1d2d66b8a26..1913f03a48fd 100644
--- a/share/man/man9/Makefile
+++ b/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 \