Changeset 08b821a in mod_gnutls

Timestamp:

Dec 6, 2016, 5:46:44 PM (23 months ago)

Author:

Thomas Klute <thomas2.klute@…>

Branches:

debian/master, debian/stretch-backports, master, upstream

Children:

251edfe

Parents:

e0e0b0f

Message:

gnutls_io.c: API documentation

File:

• src/gnutls_io.c (modified) (5 diffs)

src/gnutls_io.c

@@ -47 +47 @@
 
 /**
- * Convert APR_EINTR or APR_EAGAIN to the match raw error code. Needed
- * to pass the status on to GnuTLS from the pull function.
+ * Convert `APR_EINTR` or `APR_EAGAIN` to the matching errno. Needed
+ * to pass the status on to GnuTLS from the pull and push functions.
  */
 #define EAI_APR_TO_RAW(s) (APR_STATUS_IS_EAGAIN(s) ? EAGAIN : EINTR)
@@ -487 +487 @@
  * Close the TLS session associated with the given connection
  * structure and free its resources
+ *
+ * @param ctxt the mod_gnutls session context
+ *
+ * @return a GnuTLS status code, hopefully `GNUTLS_E_SUCCESS`
  */
 static int mgs_bye(mgs_handle_t* ctxt)
@@ -629 +633 @@
 }
 
+/**
+ * Try to flush the output bucket brigade.
+ *
+ * @param ctxt the mod_gnutls session context
+ *
+ * @return `1` on success, `-1` on failure.
+ */
 static ssize_t write_flush(mgs_handle_t * ctxt) {
     apr_bucket *e;
@@ -772 +783 @@
  * Pull function for GnuTLS
  *
- * Generic errnos used for gnutls_transport_set_errno:
- * EIO: Unknown I/O error
- * ECONNABORTED: Input BB does not exist (NULL)
- *
- * The reason we are not using APR_TO_OS_ERROR to map apr_status_t to
- * errnos is this warning in the APR documentation: "If the statcode
- * was not created by apr_get_os_error or APR_FROM_OS_ERROR, the
- * results are undefined." We cannot know if this applies to any error
- * we might encounter.
+ * Generic errnos used for `gnutls_transport_set_errno()`:
+ * * `EAGAIN`: no data available at the moment, try again (maybe later)
+ * * `EINTR`: read was interrupted, try again
+ * * `EIO`: Unknown I/O error
+ * * `ECONNABORTED`: Input BB does not exist (`NULL`)
+ *
+ * The reason we are not using `APR_TO_OS_ERROR` to map `apr_status_t`
+ * to errnos is this warning [in the APR documentation][apr-warn]:
+ *
+ * > If the statcode was not created by apr_get_os_error or
+ * > APR_FROM_OS_ERROR, the results are undefined.
+ *
+ * We cannot know if this applies to any error we might encounter.
+ *
+ * @param ptr GnuTLS session data pointer (the mod_gnutls context
+ * structure)
+ *
+ * @param buffer buffer for the read data
+ *
+ * @param len maximum number of bytes to read (must fit into the
+ * buffer)
+ *
+ * @return The number of bytes read (may be zero on EOF), or `-1` on
+ * error. Note that some errors may warrant another try (see above).
+ *
+ * [apr-warn]: https://apr.apache.org/docs/apr/1.4/group__apr__errno.html#ga2385cae04b04afbdcb65f1a45c4d8506 "Apache Portable Runtime: Error Codes"
  */
 ssize_t mgs_transport_read(gnutls_transport_ptr_t ptr,
@@ -877 +905 @@
  * Push function for GnuTLS
  *
- * In case of unexpected errors gnutls_transport_set_errno is called
- * with EIO.  The reason we are not using APR_TO_OS_ERROR to map
- * apr_status_t to errnos is this warning in the APR documentation:
- * "If the statcode was not created by apr_get_os_error or
- * APR_FROM_OS_ERROR, the results are undefined." We cannot know if
- * this applies to any error we might encounter.
+ * `gnutls_transport_set_errno()` will be called with `EAGAIN` or
+ * `EINTR` on recoverable errors, or `EIO` in case of unexpected
+ * errors. See the description of mgs_transport_read() for details on
+ * possible error codes.
+ *
+ * @param ptr GnuTLS session data pointer (the mod_gnutls context
+ * structure)
+ *
+ * @param buffer buffer containing the data to send
+ *
+ * @param len length of the data
+ * buffer)
+ *
+ * @return The number of written bytes, or `-1` on error. Note that
+ * some errors may warrant another try (see above).
  */
 ssize_t mgs_transport_write(gnutls_transport_ptr_t ptr,