Clarify qpdf's exit statuses in the documentation

Jay Berkenbilt
1 parent 8f1db4dc
Showing 3 changed files with 37 additions and 3 deletions
TODO
manual/qpdf-manual.xml
qpdf/qpdf.cc
@@ -3,14 +3,13 @@ Candidates for upcoming release
  
 * Trivial fixes:
   * Remove travisci
-  * Update manual to clearly state qpdf's exit codes including mention
-    of not exiting with code 1.
  
 * Quick issues:
   * #438: things written to stdout instead of stderr; --no-warn issues
   * #454: integer overflow
   * #451: BufferInputSource performance enhancement
   * #432: WindowsCryptProvider fixes
+  * Add --warning-exit-0 option. Search for --no-warn in the docs.
  
 * Easy build/test
   * #429: cygwin build and openssl version (see #455)
@@ -594,6 +594,40 @@ make
     Most options require an output file, but some testing or
     inspection commands do not.  These are specifically noted.
    </para>
+   <sect2 id="ref.exit-status">
+    <title>Exit Status</title>
+    <para>
+     The exit status of <command>qpdf</command> may be interpreted as
+     follows:
+     <itemizedlist>
+      <listitem>
+       <para>
+        <literal>0</literal>: no errors or warnings were found. The
+        file may still have problems qpdf can't detect.
+       </para>
+      </listitem>
+      <listitem>
+       <para>
+        <literal>2</literal>: errors were found. qpdf was not able to
+        fully process the file.
+       </para>
+      </listitem>
+      <listitem>
+       <para>
+        <literal>3</literal>: qpdf encountered problems that it was
+        able to recover from. In some cases, the resulting file may
+        still be damaged. Note that qpdf still exits with status
+        <literal>3</literal> if it finds warnings even when
+        <option>--no-warn</option> is specified.
+       </para>
+      </listitem>
+     </itemizedlist>
+     Note that <command>qpdf</command> never exists with status
+     <literal>1</literal>. If you get an exit status of
+     <literal>1</literal>, it was something else, like the shell not
+     being able to find or execute <command>qpdf</command>.
+    </para>
+   </sect2>
   </sect1>
   <sect1 id="ref.shell-completion">
    <title>Shell Completion</title>
@@ -1621,7 +1621,8 @@ ArgParser::argHelp()
         << "Ordinarily, qpdf exits with a status of 0 on success or a status of 2\n"
         << "if any errors occurred.  If there were warnings but not errors, qpdf\n"
         << "exits with a status of 3. If warnings would have been issued but --no-warn\n"
-        << "was given, an exit status of 3 is still used.\n";
+        << "was given, an exit status of 3 is still used. qpdf does not use exit\n"
+        << "status 1, since that is used by the shell if it can't execute qpdf.\n";
 }
  
 void