diff options
author | Guido Cella <guido@guidocella.xyz> | 2022-02-18 18:30:31 +0100 |
---|---|---|
committer | avih <avih@users.noreply.github.com> | 2022-02-18 19:39:10 +0200 |
commit | beac97ba0740982ec82bf1081821295ef6ba5b3e (patch) | |
tree | bfe345ef1cbf7c63a6719e51e8653f1e080637ff /DOCS | |
parent | b89ca0c552daa27e4846fade09ff87eb804f46ea (diff) | |
download | mpv-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.rst | 42 |
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 |