doc/usage/setexpr.rst

   1 .. SPDX-License-Identifier: GPL-2.0+
   2
   3 setexpr command
   4 ===============
   5
   6 Synopsis
   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
  17 Description
  18 -----------
  19
  20 The setexpr command is used to set an environment variable to the result
  21 of an evaluation.
  22
  23 setexpr[.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
  27 setexpr[.b, .w, .l] name [*]value
  28      Load <value> into environment variable <name>
  29
  30 setexpr name fmt <format> value
  31      Set environment variable <name> to the result of the C like
  32      format string <format> evaluation of <value>.
  33
  34 setexpr 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
  40 setexpr name sub <r> <s> [<t>]
  41      Just like gsub(), but replace only the first matching substring
  42
  43 The setexpr command takes the following arguments:
  44
  45 format
  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
  79 name
  80     The name of the environment variable to be set
  81
  82 op
  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
 102 r
 103     Regular expression
 104
 105 s
 106     Substitution string
 107
 108 t
 109     string
 110
 111 value
 112     Can either be an integer value, a string.
 113     If the pointer prefix '*' is given value is treated as memory address.
 114
 115 value2
 116     See value
 117
 118 Example
 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
 138 Configuration
 139 -------------
 140
 141 The setexpr gsub and sub operations are only available if CONFIG_REGEX=y.
 142
 143 Return value
 144 ------------
 145
 146 The return value $? is set to 0 (true) if the operation was successful.
 147
 148 If an error occurs, the return value $? is set to 1 (false).