]> Savannah Git Hosting - gnulib.git/commitdiff
af_alg: Add documentation.
authorBruno Haible <bruno@clisp.org>
Sat, 5 May 2018 15:50:51 +0000 (17:50 +0200)
committerBruno Haible <bruno@clisp.org>
Sat, 5 May 2018 15:50:51 +0000 (17:50 +0200)
* lib/af_alg.h: Add comments.

ChangeLog
lib/af_alg.h

index 122f8daba1404d5d3b57d70b39cdaf67ac9b03f4..098ffe2ea82d3763e4d275d1346964b92905a6dd 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2018-05-05  Bruno Haible  <bruno@clisp.org>
+
+       af_alg: Add documentation.
+       * lib/af_alg.h: Add comments.
+
 2018-05-05  Bruno Haible  <bruno@clisp.org>
 
        sha512: Add tests.
index 978e21d3690607dcb8f21ccde9503e199a2b030e..e9580d4359b49617cbab4bb1785b8de2515756f2 100644 (file)
    You should have received a copy of the GNU General Public License
    along with this program; if not, see <https://www.gnu.org/licenses/>.  */
 
-/* Written by Matteo Croce <mcroce@redhat.com>, 2018. */
+/* Written by Matteo Croce <mcroce@redhat.com>, 2018.
+   Documentation by Bruno Haible <bruno@clisp.org>, 2018.  */
+
+/* This file declares specific functions for computing message digests
+   using the Linux kernel crypto API, if available.  This kernel API gives
+   access to specialized crypto instructions (that would also be available
+   in user space) or to crypto devices (not directly available in user space).
+
+   For a more complete set of facilities that use the Linux kernel crypto API,
+   look at libkcapi.  */
 
 #ifndef AF_ALG_H
 # define AF_ALG_H 1
@@ -29,13 +38,32 @@ extern "C" {
 
 # ifdef HAVE_LINUX_IF_ALG_H
 
+/* Computes a message digest of the contents of a file.
+   STREAM is an open file stream.  Regular files are handled more efficiently
+   than other types of files.
+   ALG is the message digest algorithm.  The supported algorithms are listed in
+   the file /proc/crypto.
+   RESBLOCK points to a block of HASHLEN bytes, for the result. HASHLEN must be
+   the length of the message digest, in bytes, in particular:
+
+      alg    | hashlen
+      -------+--------
+      md5    | 16
+      sha1   | 20
+      sha224 | 28
+      sha256 | 32
+      sha384 | 48
+      sha512 | 64
+
+   If successful, this function fills RESBLOCK and returns 0.
+   Upon failure, it returns a negated error code.  */
 int
-afalg_stream (FILE * stream, void *resblock, const char *alg, ssize_t hashlen);
+afalg_stream (FILE *stream, void *resblock, const char *alg, ssize_t hashlen);
 
 # else
 
 static int
-afalg_stream (FILE * stream, void *resblock, const char *alg, ssize_t hashlen)
+afalg_stream (FILE *stream, void *resblock, const char *alg, ssize_t hashlen)
 {
   return -EAFNOSUPPORT;
 }
@@ -46,4 +74,4 @@ afalg_stream (FILE * stream, void *resblock, const char *alg, ssize_t hashlen)
 }
 # endif
 
-#endif
+#endif /* AF_ALG_H */