1.. SPDX-License-Identifier: GPL-2.0+
2
3setexpr command
4===============
5
6Synopsis
7--------
8
9::
10
11    setexpr[.b, .w, .l .s] <name> [*]<value> <op> [*]<value2>
12    setexpr[.b, .w, .l] <name> [*]<value>
13    setexpr <name> fmt <format> [value]...
14    setexpr <name> gsub r s [t]
15    setexpr <name> sub r s [t]
16
17Description
18-----------
19
20The setexpr command is used to set an environment variable to the result
21of an evaluation.
22
23setexpr[.b, .w, .l .s] <name> [*]<value> <op> [*]<value2>
24     Set environment variable <name> to the result of the evaluated
25     expression specified by <op>.
26
27setexpr[.b, .w, .l] name [*]value
28     Load <value> into environment variable <name>
29
30setexpr name fmt <format> value
31     Set environment variable <name> to the result of the C like
32     format string <format> evaluation of <value>.
33
34setexpr name gsub <r> <s> [<t>]
35     For each substring matching the regular expression <r> in the
36     string <t>, substitute the string <s>.
37     The result is assigned to <name>.
38     If <t> is not supplied, use the old value of <name>.
39
40setexpr name sub <r> <s> [<t>]
41     Just like gsub(), but replace only the first matching substring
42
43The setexpr command takes the following arguments:
44
45format
46    This parameter contains a C or Bash like format string.
47    The number of arguments is limited to 4.
48    The following format types are supported:
49
50    c
51        single character
52    d, i
53        decimal value
54    o
55        octal value
56    s
57        string
58    u
59        unsigned decimal value
60    x, X
61        hexadecimal value
62    '%'
63        no conversion, instead a % character will be written
64
65    Backslash escapes:
66
67    \" = double quote
68    \\ = backslash
69    \a = alert (bell)
70    \b = backspace
71    \c = produce no further output
72    \f = form feed
73    \n = new line
74    \r = carriage return
75    \t = horizontal tab
76    \v = vertical tab
77    \NNN = octal number (NNN is 0 to 3 digits)
78
79name
80    The name of the environment variable to be set
81
82op
83    '|'
84        name = value | value2
85    '&'
86        name = value & value2
87    '+'
88        name = value + value2
89        (This is the only operator supported for strings.
90	It acts as concatenation operator on strings)
91    '^'
92        name = value ^ value2
93    '-'
94        name = value - value2
95    '*'
96        name = value * value2
97    '/'
98        name = value / value2
99    '%'
100        name = value % value2
101
102r
103    Regular expression
104
105s
106    Substitution string
107
108t
109    string
110
111value
112    Can either be an integer value, a string.
113    If the pointer prefix '*' is given value is treated as memory address.
114
115value2
116    See value
117
118Example
119-------
120
121::
122
123    => setexpr foo fmt %d 0x100
124    => echo $foo
125    256
126    =>
127
128    => setexpr foo fmt 0x%08x 63
129    => echo $foo
130    0x00000063
131    =>
132
133    => setexpr foo fmt %%%o 8
134    => echo $foo
135    %10
136    =>
137
138Configuration
139-------------
140
141The setexpr gsub and sub operations are only available if CONFIG_REGEX=y.
142
143Return value
144------------
145
146The return value $? is set to 0 (true) if the operation was successful.
147
148If an error occurs, the return value $? is set to 1 (false).
149