Lack of documentation is addressed by this patch.
2018-05-05 Bruno Haible <br...@clisp.org>
af_alg: Add documentation.
* lib/af_alg.h: Add comments.
diff --git a/lib/af_alg.h b/lib/af_alg.h
index 978e21d..e9580d4 100644
--- a/lib/af_alg.h
+++ b/lib/af_alg.h
@@ -15,7 +15,16 @@
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 <mcr...@redhat.com>, 2018. */
+/* Written by Matteo Croce <mcr...@redhat.com>, 2018.
+ Documentation by Bruno Haible <br...@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 */
