git: 1fc7922f9f90 - main - devd.conf(5): explain difference between internal and shell variables

The branch main has been updated by joerg:

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

commit 1fc7922f9f905b62ef9a6c03be498c282e7b382e
Author:     Joerg Wunsch <joerg@FreeBSD.org>
AuthorDate: 2024-12-20 20:16:52 +0000
Commit:     Joerg Wunsch <joerg@FreeBSD.org>
CommitDate: 2024-12-20 20:20:50 +0000

    devd.conf(5): explain difference between internal and shell variables
    
    devd.conf by default considers many variables as internal, possibly
    expanding them to an empty string.  Shell variables thus need to be
    wrapped into braces.
    
    Reviewed by:    imp, Andre Albsmeier
    MFC after:      1 week
    Differential Revision:  <https://reviews.freebsd.org/D48154>
---
 sbin/devd/devd.conf.5 | 57 ++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 56 insertions(+), 1 deletion(-)

diff --git a/sbin/devd/devd.conf.5 b/sbin/devd/devd.conf.5
index ceff27e8be60..5027ce78eae0 100644
--- a/sbin/devd/devd.conf.5
+++ b/sbin/devd/devd.conf.5
@@ -38,7 +38,7 @@
 .\" ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
 .\" SOFTWARE.
 .\"
-.Dd March 6, 2024
+.Dd December 20, 2024
 .Dt DEVD.CONF 5
 .Os
 .Sh NAME
@@ -694,6 +694,26 @@ For example:
 // part of the previous comment.
 .Ed
 .Ss Notes on Variable Expansion
+Variables are expanded by preceding them by a
+.Dq $
+sign.
+Any text immediately following that sign, starting with a letter, a minus sign
+.Dq - ,
+an underscore
+.Dq _ ,
+or an asterisk
+.Dq *
+is considered an internal variable, and expanded accordingly.
+If that variable does not exist, it silently expands to an empty string.
+Consequently, if the intention is to pass a
+.Xr sh 1
+variable, it must be surrounded by braces to prevent it from being
+considered an internal variable.
+.Pp
+See
+.Sx EXAMPLES
+for a detailed example.
+.Pp
 To prevent issues with special shell characters, the following happens for each
 variable
 .Ic $foo .
@@ -711,6 +731,10 @@ The value of the
 .Ic foo
 variable is inserted into the buffer with all single quote characters
 prefixed by a backslash.
+.It
+A final
+.Dq '
+is inserted.
 .El
 .Pp
 See
@@ -822,6 +846,37 @@ detach 0 {
 };
 .Ed
 .Pp
+The following example illustrates the difference betwen internal and shell variables:
+.Bd -literal
+attach 20 {
+        device-name             "umodem[0-9]+";
+        match "vendor"          "0x2047";
+        match "product"         "0x001(0|3|4)";
+        match "interface"       "0";
+        action "cd /dev; p=$product; dn=$device-name; \\
+                un=$(sysctl -n dev.umodem.${dn#umodem}.ttyname); \\
+                chmod 666 cua${un}; ln -sf cua${un} mspfet${p#0x}";
+};
+.Ed
+.Pp
+.Dq product ,
+and
+.Dq device-name
+are internal variables.
+Their contents are initially assigned to shell variables
+.Dq p ,
+and
+.Dq dn ,
+respectively.
+Then, variable
+.Dq dn
+is used inside a shell command substitution, assigning to shell variable
+.Dq un .
+Finally, this shell variable is used in two other shell statements, where
+it needs to be wrapped in braces in order to prevent it from being
+considered in internal variable to
+.Nm devd .
+.Pp
 The installed
 .Pa /etc/devd.conf
 has many additional examples.