summaryrefslogtreecommitdiffstats
path: root/DOCS
diff options
context:
space:
mode:
authorGuido Cella <guido@guidocella.xyz>2022-02-18 18:30:31 +0100
committeravih <avih@users.noreply.github.com>2022-02-18 19:39:10 +0200
commitbeac97ba0740982ec82bf1081821295ef6ba5b3e (patch)
treebfe345ef1cbf7c63a6719e51e8653f1e080637ff /DOCS
parentb89ca0c552daa27e4846fade09ff87eb804f46ea (diff)
downloadmpv-beac97ba0740982ec82bf1081821295ef6ba5b3e.tar.bz2
mpv-beac97ba0740982ec82bf1081821295ef6ba5b3e.tar.xz
DOCS/input: document subprocess more clearly
- Make it clearer that playback_only affects subprocess' behavior when the playback of the current playlist entry terminates, rather than when mpv quits. - Explain when status is positive and when it is negative. - Replace "exited gracefully" in status' and error_string's documentation with "terminated normally" so it can't be misinterpreted as exiting successfully. - Reword the playback_only warning
Diffstat (limited to 'DOCS')
-rw-r--r--DOCS/man/input.rst42
1 files changed, 23 insertions, 19 deletions
diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst
index 508f5adcce..54b5ad11d1 100644
--- a/DOCS/man/input.rst
+++ b/DOCS/man/input.rst
@@ -551,9 +551,9 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_).
``playback_only`` (``MPV_FORMAT_FLAG``)
Boolean indicating whether the process should be killed when playback
- terminates (optional, default: true). If enabled, stopping playback
- will automatically kill the process, and you can't start it outside of
- playback.
+ of the current playlist entry terminates (optional, default: true). If
+ enabled, stopping playback will automatically kill the process, and you
+ can't start it outside of playback.
``capture_size`` (``MPV_FORMAT_INT64``)
Integer setting the maximum number of stdout plus stderr bytes that can
@@ -600,12 +600,14 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_).
The command returns the following result (as ``MPV_FORMAT_NODE_MAP``):
``status`` (``MPV_FORMAT_INT64``)
- The raw exit status of the process. It will be negative on error. The
- meaning of negative values is undefined, other than meaning error (and
- does not correspond to OS low level exit status values).
-
- On Windows, it can happen that a negative return value is returned
- even if the process exits gracefully, because the win32 ``UINT`` exit
+ Typically this is the process exit code (0 or positive) if the process
+ terminates normally, or negative for other errors (failed to start,
+ terminated by mpv, and others). The meaning of negative values is
+ undefined, other than meaning error (and does not correspond to OS low
+ level exit status values).
+
+ On Windows, it can happen that a negative return value is returned even
+ if the process terminates normally, because the win32 ``UINT`` exit
code is assigned to an ``int`` variable before being set as ``int64_t``
field in the result map. This might be fixed later.
@@ -616,9 +618,9 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_).
Same as ``stdout``, but for stderr.
``error_string`` (``MPV_FORMAT_STRING``)
- Empty string if the process exited gracefully. The string ``killed`` if
- the process was terminated in an unusual way. The string ``init`` if the
- process could not be started.
+ Empty string if the process terminated normally. The string ``killed``
+ if the process was terminated in an unusual way. The string ``init`` if
+ the process could not be started.
On Windows, ``killed`` is only returned when the process has been
killed by mpv as a result of ``playback_only`` being set to true.
@@ -633,17 +635,19 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_).
it was somehow killed or returned an error status has to be queried from
the result value.
- This command can be asynchronously aborted via API.
+ This command can be asynchronously aborted via API. Also see `Asynchronous
+ command details`_. Only the ``run`` command can start processes in a truly
+ detached way.
- In all cases, the subprocess will be terminated on player exit. Also see
- `Asynchronous command details`_. Only the ``run`` command can start
- processes in a truly detached way.
+ .. note:: The subprocess will always be terminated on player exit if it
+ wasn't started in detached mode, even if ``playback_only`` is
+ false.
.. admonition:: Warning
- Don't forget to set the ``playback_only`` field if you want the command
- run while the player is in idle mode, or if you don't want that end of
- playback kills the command.
+ Don't forget to set the ``playback_only`` field to false if you want
+ the command to run while the player is in idle mode, or if you don't
+ want the end of playback to kill the command.
.. admonition:: Example