diff mbox series

doc: man-page for if

Message ID 20240316095741.58258-1-heinrich.schuchardt@canonical.com
State Accepted, archived
Commit a9122d2c45d267adf80e84ae778eb5ac60bca94f
Delegated to: Heinrich Schuchardt
Headers show
Series doc: man-page for if | expand

Commit Message

Heinrich Schuchardt March 16, 2024, 9:57 a.m. UTC 
Provide a man-page for the if command.

Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
---
 doc/usage/cmd/if.rst | 72 ++++++++++++++++++++++++++++++++++++++++++++
 doc/usage/index.rst  |  1 +
 2 files changed, 73 insertions(+)
 create mode 100644 doc/usage/cmd/if.rst
diff mbox series

Patch

diff --git a/doc/usage/cmd/if.rst b/doc/usage/cmd/if.rst
new file mode 100644
index 00000000000..6b3dbe7b0a0
--- /dev/null
+++ b/doc/usage/cmd/if.rst
@@ -0,0 +1,72 @@ 
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+.. index::
+   single: if (command)
+
+if command
+==========
+
+Synopsis
+--------
+
+::
+
+    if <test statement>
+    then
+        <statements>
+    fi
+
+    if <test statement>
+    then
+        <statements>
+    else
+        <statements>
+    fi
+
+Description
+-----------
+
+The if command is used to conditionally execute statements.
+
+test statement
+    Any command. The test statement set the $? variable. If the value of
+    $? becomes 0 (true) the statements after the **then** statement will
+    be executed. Otherwise the statements after the **else** statement.
+
+Example
+-------
+
+The examples shows how the value of a numeric variable can be tested with
+**itest**.
+
+::
+
+    => a=1; if itest $a == 0; then echo true; else echo false; fi
+    false
+    => a=0; if itest $a == 0; then echo true; else echo false; fi
+    true
+
+In the following example we try to load an EFI binary via TFTP. If loading
+succeeds, the binary is executed.
+
+::
+
+    if tftp $kernel_addr_r shellriscv64.efi; then bootefi $kernel_addr_r; fi
+
+Return value
+------------
+
+The value of $? is the return value of the last executed statement.
+
+::
+
+    => if true; then true; else true; fi; echo $?
+    0
+    => if false; then true; else true; fi; echo $?
+    0
+    => if false; then false; else false; fi; echo $?
+    1
+    => if true; then false; else false; fi; echo $?
+    1
+    => if false; then true; fi; echo $?
+    1
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index 0d174eefaa5..66d73e70cc4 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -71,6 +71,7 @@  Shell commands
    cmd/gpt
    cmd/history
    cmd/host
+   cmd/if
    cmd/imxtract
    cmd/load
    cmd/loadb