From 521dc5c5d00f7e26cdedcd2532fa5ec3c9736ce4 Mon Sep 17 00:00:00 2001 From: Fabian Boehm Date: Fri, 30 Sep 2022 18:32:27 +0200 Subject: [PATCH] docs: Explain SIGPIPE and how it relates to $pipestatus --- doc_src/language.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/doc_src/language.rst b/doc_src/language.rst index fa63dc207..20f9a48c9 100644 --- a/doc_src/language.rst +++ b/doc_src/language.rst @@ -1470,6 +1470,23 @@ Here ``$status`` reflects the status of ``grep``, which returns 0 if it found so So if both ``cat`` and ``grep`` succeeded, ``$status`` would be 1 because of the ``not``, and ``$pipestatus`` would be 0 and 0. +It's possible for the first command to fail while the second succeeds. One common example is when the second program quits early. + +For example, if you have a pipeline like:: + + cat file1 file2 | head -n 50 + +This will tell ``cat`` to print two files, "file1" and "file2", one after the other, and the ``head`` will then only print the first 50 lines. In this case you might often see this constellation:: + + > cat file1 file2 | head -n 50 + # 50 lines of output + > echo $pipestatus + 141 0 + +Here, the "141" signifies that ``cat`` was killed by signal number 13 (128 + 13 == 141) - a ``SIGPIPE``. You can also use :envvar:`fish_kill_signal` to see the signal number. This happens because it was still working, and then ``head`` closed the pipe, so ``cat`` received a signal that it didn't ignore and so it died. + +Whether ``cat`` here will see a SIGPIPE depends on how long the file is and how much it writes at once, so you might see a pipestatus of "0 0", depending on the implementation. This is a general unix issue and not specific to fish. Some shells feature a "pipefail" feature that will call a pipeline failed if one of the processes in it failed, and this is a big problem with it. + .. _variables-locale: Locale Variables