make setup in travis.yml a bit more verbose

[apt.git] / apt-pkg / contrib / gpgv.h

diff --git a/apt-pkg/contrib/gpgv.h b/apt-pkg/contrib/gpgv.h
index 8cbe553bcfabec041f2798f3e563cc01f5f1fb74..45f06905831bd86e9494a7e90e77323272f66e90 100644 (file)
--- a/apt-pkg/contrib/gpgv.h
+++ b/apt-pkg/contrib/gpgv.h
@@ -23,9 +23,18 @@
 /** \brief generates and run the command to verify a file with gpgv
  *
  * If File and FileSig specify the same file it is assumed that we
- * deal with a clear-signed message. In that case the file will be
- * rewritten to be in a good-known format without uneeded whitespaces
- * and additional messages (unsigned or signed).
+ * deal with a clear-signed message. Note that the method will accept
+ * and validate files which include additional (unsigned) messages
+ * without complaining. Do NOT open files accepted by this method
+ * for reading. Use #OpenMaybeClearSignedFile to access the message
+ * instead to ensure you are only reading signed data.
+ *
+ * The method does not return, but has some noteable exit-codes:
+ * 111 signals an internal error like the inability to execute gpgv,
+ * 112 indicates a clear-signed file which doesn't include a message,
+ *  which can happen if APT is run while on a network requiring
+ *  authentication before usage (e.g. in hotels)
+ * All other exit-codes are passed-through from gpgv.
  *
  * @param File is the message (unsigned or clear-signed)
  * @param FileSig is the signature (detached or clear-signed)
@@ -48,11 +57,8 @@ inline void ExecGPGV(std::string const &File, std::string const &FileSig,
  *  whitespaces are discarded. The resulting files are suitable to
  *  be checked with gpgv.
  *
- *  If one or all Fds are -1 they will not be used and the content
- *  which would have been written to them is discarded.
- *
- *  The code doesn't support dash-encoded lines as these are not
- *  expected to be present in files we have to deal with.
+ *  If a FileFd pointers is NULL it will not be used and the content
+ *  which would have been written to it is silently discarded.
  *
  *  The content of the split files is undefined if the splitting was
  *  unsuccessful.
@@ -61,13 +67,13 @@ inline void ExecGPGV(std::string const &File, std::string const &FileSig,
  *  not generate an error message.
  *
  *  @param InFile is the clear-signed file
- *  @param ContentFile is the Fd the message will be written to
+ *  @param ContentFile is the FileFd the message will be written to
  *  @param ContentHeader is a list of all required Amored Headers for the message
- *  @param SignatureFile is the Fd all signatures will be written to
+ *  @param SignatureFile is the FileFd all signatures will be written to
  *  @return true if the splitting was successful, false otherwise
  */
-bool SplitClearSignedFile(std::string const &InFile, int const ContentFile,
-      std::vector<std::string> * const ContentHeader, int const SignatureFile);
+bool SplitClearSignedFile(std::string const &InFile, FileFd * const ContentFile,
+      std::vector<std::string> * const ContentHeader, FileFd * const SignatureFile);
 
 /** \brief open a file which might be clear-signed
  *