nixosTest: Add xclip as example of stdout blocker

1 files changed, 5 insertions, 2 deletions

diff --git a/nixos/doc/manual/development/writing-nixos-tests.section.md b/nixos/doc/manual/development/writing-nixos-tests.section.md
index a8c54aa6676..d9749d37da7 100644
--- a/nixos/doc/manual/development/writing-nixos-tests.section.md
+++ b/nixos/doc/manual/development/writing-nixos-tests.section.md
@@ -162,7 +162,9 @@ The following methods are available on machine objects:
     If the command detaches, it must close stdout, as `execute` will wait
     for this to consume all output reliably. This can be achieved by
     redirecting stdout to stderr `>&2`, to `/dev/console`, `/dev/null` or
-    a file.
+    a file. Examples of detaching commands are `sleep 365d &`, where the
+    shell forks a new process that can write to stdout and `xclip -i`, where
+    the `xclip` command itself forks without closing stdout.
     Takes an optional parameter `check_return` that defaults to `True`.
     Setting this parameter to `False` will not check for the return code
     and return -1 instead. This can be used for commands that shut down
@@ -183,7 +185,8 @@ The following methods are available on machine objects:
 
     -   Dereferencing unset variables fail the command.
 
-    -   It will wait for stdout to be closed. See `execute`.
+    -   It will wait for stdout to be closed. See `execute` for the
+        implications.
 
 `fail`