| Rasmus Villemoes | 880b7b4 | 2025-05-13 10:40:34 +0200 | [diff] [blame] | 1 | .. SPDX-License-Identifier: GPL-2.0-or-later |
| 2 | |
| 3 | .. index:: |
| 4 | single: test (command) |
| 5 | |
| 6 | test command |
| 7 | ============ |
| 8 | |
| 9 | Synopsis |
| 10 | -------- |
| 11 | |
| 12 | :: |
| 13 | |
| 14 | test <str-op> <s> |
| 15 | test <s1> <str-cmp> <s2> |
| 16 | test <n1> <num-cmp> <n2> |
| 17 | test ! <expr> |
| 18 | test <expr1> -o <expr2> |
| 19 | test <expr1> -a <expr2> |
| 20 | test -e <interface> <dev[:part]> <path> |
| 21 | test <s> =~ <re> |
| 22 | |
| 23 | Description |
| 24 | ----------- |
| 25 | |
| 26 | The ``test`` command is similar to the ordinary shell built-in by the |
| 27 | same name. Unlike in ordinary shells, it cannot be spelled ``[``. |
| 28 | |
| 29 | Strings |
| 30 | ~~~~~~~ |
| 31 | |
| 32 | The string tests ``-n`` and ``-z``, and string comparison operators |
| 33 | ``=``, ``!=``, ``<`` and ``>``, work exactly as in ordinary shells. |
| 34 | |
| 35 | Numbers |
| 36 | ~~~~~~~ |
| 37 | |
| 38 | The number comparison operators ``-lt``, ``-le``, ``-gt``, ``-gt``, |
| 39 | ``-eq`` and ``-ne`` work as in ordinary shells. |
| 40 | |
| 41 | .. note:: |
| 42 | Numbers are parsed with ``simple_strtol(, 0)``, meaning that they |
| 43 | are treated as decimal unless there is a `0x` prefix, any errors in |
| 44 | parsing are ignored, and parsing stops as soon as a non-digit (for |
| 45 | the selected base) is encountered. And most U-Boot commands that |
| 46 | generate "numeric" environment variables store them as hexadecimal |
| 47 | *without* a `0x` prefix. |
| 48 | |
| 49 | For example, this is not a correct way of testing whether a given file |
| 50 | has a size less than 4KiB:: |
| 51 | |
| 52 | # Assuming readme.txt exists, sets 'filesize' environment variable |
| 53 | $ size mmc 0:1 readme.txt |
| 54 | $ if test "$filesize" -lt 4096 ; then ... |
| 55 | |
| 56 | If the file size is actually 8000 (decimal), its hexadecimal |
| 57 | representation, and thus the value of ``$filesize``, is ``1f40``, so |
| 58 | the comparison that is done ends up being "1 < 4096". |
| 59 | |
| 60 | Logic |
| 61 | ~~~~~ |
| 62 | |
| 63 | The ``!`` operator negates the sense of the test of the expression |
| 64 | ``<expr>``. |
| 65 | |
| 66 | The ``-o`` and ``-a`` operators perform logical OR and logical AND, |
| 67 | respectively, of the two expressions. |
| 68 | |
| 69 | File existence |
| 70 | ~~~~~~~~~~~~~~ |
| 71 | |
| 72 | Like ordinary shells, the ``-e`` operator can be used to test for |
| 73 | existence of a file. However, the U-Boot version takes three |
| 74 | arguments: |
| 75 | |
| 76 | - The interface (e.g. ``mmc``). |
| 77 | - The device number, possibly including a partition specification. |
| 78 | - The usual path argument, which is interpreted relative to the root |
| 79 | of the filesystem. |
| 80 | |
| 81 | Regular expressions |
| 82 | ~~~~~~~~~~~~~~~~~~~ |
| 83 | |
| 84 | When ``CONFIG_REGEX`` is enabled, an additional operator ``=~`` is |
| 85 | available. This is similar to the same operator available with bash's |
| 86 | extended test command ``[[ ]]``. The left operand is a string which is |
| 87 | matched against the regular expression described by the right operand. |
| 88 | |
| 89 | The regular expression engine supports these features: |
| 90 | |
| 91 | - Anchoring ``^`` and ``$``, matching at the beginning/end of the |
| 92 | string. |
| 93 | - Matching any single character (including whitespace) using ``.``. |
| 94 | - Character classes ``[ ]``, including ranges ``[0-9]`` and negation |
| 95 | ``[^ /.]``. |
| 96 | - Grouping ``( )``. |
| 97 | - Alternation ``|``. |
| 98 | - Postfix qualifiers ``*``, ``+`` and ``?`` and their non-greedy |
| 99 | variants ``*?``, ``+?`` and ``??`` |
| 100 | |
| 101 | For extracting the parts matching a capture group and/or performing |
| 102 | substitutions, including back references, see :doc:`setexpr`. |