no explanation of return value of ffmpeg

[sgerwk]

Summary of the bug:
I cannot find a description of the return value of ffmpeg in the man pages ffmpeg.1 and ffmpeg-all.1. As far as I can see, this may be 0=everything fine, 1=error of some kind, 255=killed (SIGINT or SIGTERM). Maybe there are other possible return values.

How to reproduce:

% ffmpeg -i input output
% killall ffmpeg
ffmpeg version 4.1.git Copyright (c) 2000-2019 the FFmpeg developers
built with gcc 8.3.0 (GCC)
configuration: --enable-shared --enable-libdrm --enable-libopencore-amrnb --enable-version3 --enable-libvpx --enable-libcaca --enable-libvorbis --enable-gpl --enable-libxcb --enable-openssl --enable-nonfree --enable-libmp3lame --enable-libxml2
libavutil      56. 28.100 / 56. 22.100
libavcodec     58. 52.102 / 58. 35.100
libavformat    58. 27.103 / 58. 20.100
libavdevice    58.  7.100 / 58.  5.100
libavfilter     7. 55.100 /  7. 40.101
libswscale      5.  4.101 /  5.  3.100
libswresample   3.  4.100 /  3.  3.100
libpostproc    55.  4.100 / 55.  3.100

Patches should be submitted to the ffmpeg-devel mailing list and not this bug tracker.

[Balling]

Those things are (or should be as I just come after some problems about that) guranteed to be like that by Posix Standards and by linux kernel code. Do not think that should be documented.

[Cigaes]

The standard Unix convention is 0 for success, ≠0 for failure. FFmpeg does not ofcially try to distinguish between the kinds of failure through the return code.

[sgerwk]

I believe this very comment would be just fine for documenting the exit status.

Let me explain my point of view. I wrote a script using ffmpeg to get a file from the Internet. This may fail or not, and the obvious thing to check is the exit status of ffmpeg. I was I bit surprised to see that the exit status was not always the same, yet no explanation was given in the man pages. Even basic commands like ls(1) and find(1) have a short paragraph explaining the obvious like 0=ok otherwise=fail. Lacking that, I would have resorted to the current behaviour of ffmpeg, and I would have been wrong as you pointed out. That would have been avoided by a paragraph in ffmpeg-all(1):

EXIT STATUS

The exit status of ffmpeg is 0 if the command completed successfully and different from zero otherwise. Avoid relying on specific values in the latter case as they are subject to change.