]> git.ipfire.org Git - thirdparty/u-boot.git/commitdiff
doc: usage: Add general rule for `$?`
authorTom Rini <trini@konsulko.com>
Fri, 24 Oct 2025 16:02:57 +0000 (10:02 -0600)
committerTom Rini <trini@konsulko.com>
Sun, 26 Oct 2025 15:03:35 +0000 (09:03 -0600)
For nearly all commands in U-Boot the '?' variable is handled the same
way with 0 meaning success, 1 meaning any failure.  Explain this in the
general rules section of the cmdline documentation (with a link to a
counter example) and then remove the redundant wording from most
commands. We retain a section about the return value in a number of
places where we are doing something such as always returning a specific
value or we have useful additional information to go along with the
normal return codes.

Signed-off-by: Tom Rini <trini@konsulko.com>
Reviewed-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
45 files changed:
doc/usage/cmd/armffa.rst
doc/usage/cmd/bdinfo.rst
doc/usage/cmd/bind.rst
doc/usage/cmd/blkcache.rst
doc/usage/cmd/cat.rst
doc/usage/cmd/cli.rst
doc/usage/cmd/cls.rst
doc/usage/cmd/cp.rst
doc/usage/cmd/cpu.rst
doc/usage/cmd/cpuid.rst
doc/usage/cmd/dmareset.rst
doc/usage/cmd/ebtupdate.rst
doc/usage/cmd/fatinfo.rst
doc/usage/cmd/fdt.rst
doc/usage/cmd/font.rst
doc/usage/cmd/fuse.rst
doc/usage/cmd/gpio.rst
doc/usage/cmd/host.rst
doc/usage/cmd/i3c.rst
doc/usage/cmd/imxtract.rst
doc/usage/cmd/loadb.rst
doc/usage/cmd/loadm.rst
doc/usage/cmd/loads.rst
doc/usage/cmd/loadx.rst
doc/usage/cmd/loady.rst
doc/usage/cmd/msr.rst
doc/usage/cmd/mtest.rst
doc/usage/cmd/optee.rst
doc/usage/cmd/part.rst
doc/usage/cmd/pause.rst
doc/usage/cmd/pinmux.rst
doc/usage/cmd/pwm.rst
doc/usage/cmd/saves.rst
doc/usage/cmd/scmi.rst
doc/usage/cmd/setexpr.rst
doc/usage/cmd/size.rst
doc/usage/cmd/smbios.rst
doc/usage/cmd/sound.rst
doc/usage/cmd/source.rst
doc/usage/cmd/temperature.rst
doc/usage/cmd/tftpput.rst
doc/usage/cmd/unbind.rst
doc/usage/cmd/wdt.rst
doc/usage/cmd/wget.rst
doc/usage/cmdline.rst

index 4f41e3393fdab7e4a50c608a03ce80a1c0a2d2b3..dbe4d5bc8425fec152e5a2f291f15a621076d8d4 100644 (file)
@@ -90,8 +90,3 @@ Configuration
 -------------
 
 The command is available if CONFIG_CMD_ARMFFA=y and CONFIG_ARM_FFA_TRANSPORT=y.
-
-Return value
-------------
-
-The return value $? is 0 (true) on success, 1 (false) on failure.
index a21fbc83ccf67bce6a2c098ec4b419db325b0fc5..a139c9d855c0c9ed0f7283b95f5501229901a560 100644 (file)
@@ -115,8 +115,3 @@ Configuration
 -------------
 
 The bdinfo command is available if CONFIG_CMD_BDI=y.
-
-Return code
------------
-
-The return code $? is 0 (true).
index 67a0405bab531f6e23e08f5d67bc886c09be967a..d2bef15508d07b30b85703c47766afc24360c07a 100644 (file)
@@ -99,8 +99,3 @@ Configuration
 -------------
 
 The bind command is only available if CONFIG_CMD_BIND=y.
-
-Return code
------------
-
-The return code $? is 0 (true) on success and 1 (false) on failure.
index 0329261ba9af8fbfd2d6fa2fd74dd97741dbc114..764a4903ca05d39d32096b4bd7e02dca1d743d1a 100644 (file)
@@ -69,9 +69,3 @@ Configuration
 -------------
 
 The blkcache command is only available if CONFIG_CMD_BLOCK_CACHE=y.
-
-Return code
------------
-
-If the command succeeds, the return code $? is set 0 (true). In case of an
-error the return code is set to 1 (false).
index b22dc6184a272d9b77d1b68cf075bd3ff5e0f25a..fa70e5f6a093c014fa764bd7f8bcce7caf84991c 100644 (file)
@@ -45,8 +45,3 @@ Configuration
 -------------
 
 The cat command is only available if CONFIG_CMD_CAT=y.
-
-Return value
-------------
-
-The return value $? is set to 0 (true) if the file is readable, otherwise it returns a non-zero error code.
index 23e5ee7a902e02cefde8564e054b35dd5eb87a05..97de5331d1b269e40ebee06d8d6a4a61c633942b 100644 (file)
@@ -70,8 +70,3 @@ compiled::
     modern
     => cli set old
     Want to set current parser to old, but its code was not compiled!
-
-Return value
-------------
-
-The return value $? indicates whether the command succeeded.
index 828276742b9bfaac740d974267ca2926524b5bc7..b8fa335079ea2882a987411e3ccd51a25ddc3f18 100644 (file)
@@ -22,8 +22,3 @@ Configuration
 -------------
 
 The cls command is only available if CONFIG_CMD_CLS=y.
-
-Return value
-------------
-
-The return value $? is 0 (true) on success and 1 (false) on failure.
index 434dfedfc2b79a3a5a9b1d6ac0c49f82c1b7f66d..7bf2f468421ba0ee8497508595bbc3f7bf11ad8b 100644 (file)
@@ -79,9 +79,3 @@ Configuration
 The cp command is available if CONFIG_CMD_MEMORY=y. Support for 64 bit words
 (cp.q) is only available on 64-bit targets. Copying to flash depends on
 CONFIG_MTD_NOR_FLASH=y.
-
-Return value
-------------
-
-The return value $? is set to 0 (true) if the command was successfully,
-1 (false) otherwise.
index 8b0b7d5a6991afd306e1c6ecbc4614d0a6d76f76..705fb2dd69131be1f292c8a7938f1aebb892d185 100644 (file)
@@ -93,9 +93,3 @@ Configuration
 -------------
 
 The cpu command is available if CONFIG_CMD_CPU=y.
-
-Return code
------------
-
-The return value $? is set to 0 (true) if the command is successful,
-1 (false) otherwise.
index cccf9262ed4d80c7a6bd117804b8f6e51a83e43b..568c7e86ca15dad4f74bdfeb8f3961335b94af68 100644 (file)
@@ -25,11 +25,6 @@ Configuration
 
 The cpuid command is only available on x86.
 
-Return value
-------------
-
-The return value $? is 0 (true).
-
 Example
 -------
 
index ab06979251beadd6f16b45ce4cc465adb715b2f7..56180595363ed307874dfc90665b889f356d54d4 100644 (file)
@@ -47,9 +47,3 @@ Configuration
 
 The dmareset command is only available if CONFIG_CMD_C5_PL330_DMA=y in
 "Shell scripting commands".
-
-Return value
-------------
-
-If the command succeeds, the return value $? is set to 0 (true).
-If an error occurs, the return value $? is set to 1 (false).
index 22415ee07b43490076f4744c360665407d48312a..5102e6090a494f8fd9e4c48379f8ee696af7e2e8 100644 (file)
@@ -64,9 +64,3 @@ Configuration
 
 The ebtupdate command is only available if CONFIG_CMD_EBTUPDATE=y and
 only on Tegra 2 and Tegra 3 configurations.
-
-Return value
-------------
-
-The return value $? is set to 0 (true) if everything went successfully. If an
-error occurs, the return value $? is set to 1 (false).
index 2e05ab8becee2301b8076fc03de8b132a13b2f01..e5a89f37ba6688fcd73f89de7884f7b20751cee8 100644 (file)
@@ -46,9 +46,3 @@ Configuration
 -------------
 
 The fatinfo command is only available if CONFIG_CMD_FAT=y.
-
-Return value
-------------
-
-The return value $? is set to 0 (true) if the partition is a FAT partition.
-Otherwise it is set to 1 (false).
index 71a9fc627e558a7af34fe25ebe85bee730d7aee2..493ed895bc78bbc4418fcebd12d5b65e7724006e 100644 (file)
@@ -66,8 +66,3 @@ address and expand it to 0xf000 in size::
     Working FDT set to 10000
     => md 10000 4
     00010000: edfe0dd0 00f00000 78000000 7c270000  ...........x..'|
-
-Return value
-------------
-
-The return value $? indicates whether the command succeeded.
index 44a04f5d075e6e94f731a2edd01f44b6d5997822..a1860466ac1b089f33b8b060bc6837868c1111e8 100644 (file)
@@ -54,9 +54,3 @@ Configuration
 -------------
 
 The command is only available if CONFIG_CONSOLE_TRUETYPE=y.
-
-Return value
-------------
-
-The return value $? is 0 (true) if the command completes.
-The return value is 1 (false) if the command fails.
index 42c6e209f9928c1519e6a9c3c5c6e7fbb688ba29..50cf5a4b657868a70763b0b5a41d624996daf20a 100644 (file)
@@ -168,9 +168,3 @@ Configuration
 
 The fuse commands are available if CONFIG_CMD_FUSE=y.
 The fuse writebuff command is available if CONFIG_CMD_FUSE_WRITEBUFF=y.
-
-Return code
------------
-
-The return value $? is set to 0 (true) if the command is successful,
-1 (false) otherwise.
index 4b0dc2716e57f02080febb878d302529bcd01c94..0159d3478c2d7f4ed424bd5acd51358c65590317 100644 (file)
@@ -127,9 +127,3 @@ Configuration
 
 The *gpio* command is only available if CONFIG_CMD_GPIO=y.
 The *gpio read* command is only available if CONFIG_CMD_GPIO_READ=y.
-
-Return value
-------------
-
-If the command succeds the return value $? is set to 0. If an error occurs, the
-return value $? is set to 1.
index a70a432b6f2b27ce04b4816312eefb86fb254c3f..672d8f2112bc0dc216f5a6f95defc2a416ed950c 100644 (file)
@@ -111,9 +111,3 @@ Unbind a device::
     => host info
     dev       blocks label           path
       1         2048 fat             1MB.fat32.img
-
-
-Return value
-------------
-
-The return value $? indicates whether the command succeeded.
index 922fa3ea37c0436fb346f12f2ea734d0d443a675..f49fcd4e76635236d672d9f2bfcfc9e4a547cb32 100644 (file)
@@ -129,12 +129,6 @@ Configuration
 
 The ``i3c`` command is only available if CONFIG_CMD_I3C=y.
 
-Return value
-------------
-
-If the command succeeds, the return value ``$?`` is set to 0. If an error
-occurs, the return value ``$?`` is set to 1.
-
 Note
 ----
 
index 235d15e445b07df31068dc470d46ee0fed0c27c6..1621a4a68b2204b5ac7acf8abf2f9f314acd3376 100644 (file)
@@ -76,9 +76,3 @@ Configuration
 The imxtract command is only available if CONFIG_CMD_XIMG=y. Support for FIT
 images requires CONFIG_FIT=y. Support for legacy U-Boot images requires
 CONFIG_LEGACY_IMAGE_FORMAT=y.
-
-Return value
-------------
-
-On success the return value $? of the command is 0 (true). On failure the
-return value is 1 (false).
index 4f9a52c793f3333b3f4f0cf662e268eb674bd8f0..9e6a41e7fa04cb96e803c269028e064b318db12c 100644 (file)
@@ -66,8 +66,3 @@ Configuration
 -------------
 
 The command is only available if CONFIG_CMD_LOADB=y.
-
-Return value
-------------
-
-The return value $? is 0 (true) on success, 1 (false) on error.
index 005840a27bb0e6d779d55039dfb8d4e6b828ab18..722690be2c570fd83a9b26d525ac2824db17cc60 100644 (file)
@@ -43,10 +43,3 @@ Configuration
 -------------
 
 The command is only available if CONFIG_CMD_LOADM=y.
-
-Return value
-------------
-
-The return value $? is set 0 (true) if the loading is succefull, and
-is set to 1 (false) in case of error.
-
index 0a2ac14acfe8c1e6e169c1e24eb8c2d62c98d21e..278d17850d7552d5045c5b6746608c5d864ac33e 100644 (file)
@@ -92,8 +92,3 @@ Configuration
 
 The command is only available if CONFIG_CMD_LOADS=y. The parameter to set the
 baud rate is only available if CONFIG_SYS_LOADS_BAUD_CHANGE=y
-
-Return value
-------------
-
-The return value $? is 0 (true) on success, 1 (false) otherwise.
index 661b36723c32f80f1221296a6f67489d6bb9143b..50182eaa9d3b421797f3839250e698960f286f7b 100644 (file)
@@ -73,8 +73,3 @@ The command is only available if CONFIG_CMD_LOADB=y.
 Initial timeout in seconds while waiting for transfer is configured by
 config option CMD_LOADXY_TIMEOUT or by env variable $loadxy_timeout.
 Setting it to 0 means infinite timeout.
-
-Return value
-------------
-
-The return value $? is 0 (true) on success, 1 (false) otherwise.
index 8367759471e3a56d628149a0d10dd47378a7e4fa..8d21d7c326791765f8b9e5a35fc76b06377fffa0 100644 (file)
@@ -70,8 +70,3 @@ The command is only available if CONFIG_CMD_LOADB=y.
 Initial timeout in seconds while waiting for transfer is configured by
 config option CMD_LOADXY_TIMEOUT or by env variable $loadxy_timeout.
 Setting it to 0 means infinite timeout.
-
-Return value
-------------
-
-The return value $? is 0 (true) on success, 1 (false) otherwise.
index 04ee52cc1c75da5ecce986627cd3178e8c4604b6..8bb1212cdc17c1f568b8f6bf8fbc4f9f4212c998 100644 (file)
@@ -38,11 +38,6 @@ Configuration
 
 The msr command is only available on x86.
 
-Return value
-------------
-
-The return value $? is 0 (true).
-
 Example
 -------
 
index e01f2a6d575e5f46f9e14cf196d928532667015a..a5705076af7a945b1315373da23d455357efdb20 100644 (file)
@@ -62,8 +62,3 @@ Configuration
 -------------
 
 The mtest command is enabled by CONFIG_CMD_MEMTEST=y.
-
-Return value
-------------
-
-The return value $? is 0 (true) if the command succeeds, 1 (false) otherwise.
index 46c569a105fdd44b4c3dd785b486dba8e91d39d1..caefdceeb7b607ef802337b9945f6fffb5d88c8b 100644 (file)
@@ -63,8 +63,3 @@ Configuration
 -------------
 
 The optee command is enabled by CONFIG_OPTEE=y and CONFIG_CMD_OPTEE=y.
-
-Return value
-------------
-
-The return value $? is 0 (true) if the command succeeds, 1 (false) otherwise.
index e7f6e54ecea4d336259ca7baf838aefd8a681928..72f5d8b8de74148d3e8fac057bbc44653b3ab145 100644 (file)
@@ -223,9 +223,3 @@ This shows looking at a device with multiple partition tables::
             type:      ebd0a0a2-b9e5-4433-87c0-68b6b72699c7
             guid:      a0891d7e-b930-4513-94da-f629dbd637b2
     =>
-
-Return value
-------------
-
-The return value $? is set to 0 (true) if the command succededd. If an
-error occurs, the return value $? is set to 1 (false).
index 6cdd83d316366c6960ef5dce7dd56b92e180119e..b55825f5d93acc4f2c8dcbdfbfd31b19c1db9292 100644 (file)
@@ -48,9 +48,3 @@ Note that complex prompts require proper quoting:
     
     Usage:
     pause [prompt] - Wait until users presses any key. [prompt] can be used to customize the message.
-
-Return value
-------------
-
-The return value $? is always set to 0 (true), unless invoked in an invalid
-manner.
index 30c5eb16a689202fc5b571f3d85ee2a4f932a77b..c066db1770cbfd7cde3b72b8bd69bd036fb28ad5 100644 (file)
@@ -90,9 +90,3 @@ Configuration
 -------------
 
 The pinmux command is only available if CONFIG_CMD_PINMUX=y.
-
-Return value
-------------
-
-The return value $? is set to 0 (true) if the command succeded and to 1 (false)
-otherwise.
index 522acb5afa33ed44bdcc237636b102ccae8c7413..6f7daba0736d410dbe0ac676c0dae45b4f819830 100644 (file)
@@ -83,9 +83,3 @@ Configuration
 -------------
 
 The ``pwm`` command is only available if CONFIG_CMD_PWM=y.
-
-Return value
-------------
-
-If the command succeeds, the return value ``$?`` is set to 0. If an error occurs, the
-return value ``$?`` is set to 1.
index b380a4feb6f0f11d5c6658600154da2cbb3f50d1..d429eeceddf20faf9b97dbb4974d608bbf34cc9d 100644 (file)
@@ -84,8 +84,3 @@ Configuration
 
 The command is only available if CONFIG_CMD_SAVES=y. The parameter to set the
 baud rate is only available if CONFIG_SYS_LOADS_BAUD_CHANGE=y
-
-Return value
-------------
-
-The return value $? is 0 (true) on success, 1 (false) otherwise.
index 9591cdc07a5a4d4461343027aaa90ad35c94d863..c6e80a56a603498c60f33894a2dbcaa5892bbd3e 100644 (file)
@@ -119,11 +119,4 @@ Configuration
 The scmi command is only available if CONFIG_CMD_SCMI=y.
 Default n because this command is mainly for debug purpose.
 
-Return value
-------------
-
-The return value ($?) is set to 0 if the operation succeeded,
-1 if the operation failed or -1 if the operation failed due to
-a syntax error.
-
 .. _`SCMI specification`: https://developer.arm.com/documentation/den0056/e/?lang=en
index 5bc37ae50fc02986b47b2de9e81ebe9c4a4c0cd0..96894a2754f62ff7a34d2b628163df15ea467281 100644 (file)
@@ -147,10 +147,3 @@ Configuration
 * The *setexpr gsub* and *setexpr sub* sub-commands are only available
   if CONFIG_REGEX=y. For an overview of the supported regex syntax,
   see :doc:`test`.
-
-Return value
-------------
-
-The return value $? is set to 0 (true) if the operation was successful.
-
-If an error occurs, the return value $? is set to 1 (false).
index 306fcba0ba4a151a48136259388d20adaf357265..42e2dec6323c7c76e1bfc8ddcb33858ef9ad5ce6 100644 (file)
@@ -35,9 +35,3 @@ Configuration
 -------------
 
 The size command is only available if CONFIG_CMD_FS_GENERIC=y.
-
-Return value
-------------
-
-The return value $? is set to 0 (true) if the command succeded and to 1 (false)
-otherwise.
index 1ffd706d7deebf2acf5bf1135e96dc9b16caef5e..3c98795698e7bd1768626f091e30a847148f893f 100644 (file)
@@ -86,8 +86,3 @@ Configuration
 -------------
 
 The command is only available if CONFIG_CMD_SMBIOS=y.
-
-Return value
-------------
-
-The return value $? is 0 (true) on success, 1 (false) otherwise.
index 97d610f3745c468118752212776ee3498e5e466a..4474ce95420232feb5657fb4155e235410169cde 100644 (file)
@@ -56,8 +56,3 @@ Configuration
 -------------
 
 The sound command is enabled by CONFIG_CMD_SOUND=y.
-
-Return value
-------------
-
-The return value $? is 0 (true) if the command succeeds, 1 (false) otherwise.
index 0de5f33390e79510238eebd5503f05016d63c867..bd585f3741407317e7113d83f1f596620c57e330 100644 (file)
@@ -188,9 +188,3 @@ The FIT image file format requires CONFIG_FIT=y.#
 The legacy U-Boot image file format requires CONFIG_LEGACY_IMAGE_FORMAT=y.
 On hardened systems support for the legacy U-Boot image format should be
 disabled as these images cannot be signed and verified.
-
-Return value
-------------
-
-If the scripts is executed successfully, the return value $? is 0 (true).
-Otherwise it is 1 (false).
index 945bc8204ac7644540a4abf2f33467bb90627495..d5ea1196f4523f615b361f9b7ccefb2cb297a5ed 100644 (file)
@@ -45,9 +45,3 @@ Configuration
 -------------
 
 The *temperature* command is only available if CONFIG_CMD_TEMPERATURE=y.
-
-Return value
-------------
-
-The return value $? is set to 0 (true) if the command succeeded and to 1 (false)
-otherwise.
index 2bcb3032cb2444926da28454eefdb2b128a7389f..bdffa3af4635734ac0c391fc02a2e8dfe7bb63c9 100644 (file)
@@ -79,8 +79,3 @@ after which an ACK response is required. The window size defaults to 1.
 
 If CONFIG_TFTP_TSIZE=y, the progress bar is limited to 50 '#' characters.
 Otherwise an '#' is written per UDP package which may decrease performance.
-
-Return value
-------------
-
-The return value $? is 0 (true) on success and 1 (false) otherwise.
index 1ae9c1b172c1058aaeb0cba8f71f0a24cd6cc160..5a165cfee2304b3d595574f58b19aa1d315c8c68 100644 (file)
@@ -91,8 +91,3 @@ Configuration
 -------------
 
 The unbind command is only available if CONFIG_CMD_BIND=y.
-
-Return code
------------
-
-The return code $? is 0 (true) on success and 1 (false) on failure.
index f48b8840907d253ea05fa106bbae98f728b23264..711b74d20dabc5f5d9eae1bfcc23b4e6d02da3ad 100644 (file)
@@ -73,8 +73,3 @@ Configuration
 -------------
 
 The command is only available if CONFIG_CMD_WDT=y.
-
-Return value
-------------
-
-The return value $? is 0 if the command succeeds, 1 upon failure.
index 8feda0248b20fec935d5c7dd7332f3cba12f7d3a..e6c42f967b9b31e9801ab437f93dae4dc3b33437 100644 (file)
@@ -184,8 +184,3 @@ CONFIG_WGET_CACERT=y (for the wget cacert command).
 TCP Selective Acknowledgments in the legacy network stack can be enabled via
 CONFIG_PROT_TCP_SACK=y. This will improve the download speed. Selective
 Acknowledgments are enabled by default with lwIP.
-
-Return value
-------------
-
-The return value $? is 0 (true) on success and 1 (false) otherwise.
index 58240c5279cdb728cab9ea381f2677256e4df60c..79b9baf7bfe5bd6de14d305ccc9f82fd4ac8b4d6 100644 (file)
@@ -55,6 +55,12 @@ General rules
    command will cause "run" to terminate, i. e. the remaining
    variables are not executed.
 
+#. The variable ``$?`` will be set as the return value of any command. The
+   possible values are 0 on success or 1 on any error e. g. invalid syntax or
+   failure of the command. Any exceptions to this are documented by the
+   specific command, e.g. the :doc:`for command <cmd/for>` sets ``$?`` based on
+   the last command run within the loop.
+
 Representing numbers
 --------------------