Changeset 08b821a in mod_gnutls


Ignore:
Timestamp:
Dec 6, 2016, 5:46:44 PM (12 months ago)
Author:
Thomas Klute <thomas2.klute@…>
Branches:
master, debian, upstream
Children:
251edfe
Parents:
e0e0b0f
Message:

gnutls_io.c: API documentation

File:
1 edited

Legend:

Unmodified
Added
Removed
  • src/gnutls_io.c

    r104e881 r08b821a  
    4747
    4848/**
    49  * Convert APR_EINTR or APR_EAGAIN to the match raw error code. Needed
    50  * to pass the status on to GnuTLS from the pull function.
     49 * Convert `APR_EINTR` or `APR_EAGAIN` to the matching errno. Needed
     50 * to pass the status on to GnuTLS from the pull and push functions.
    5151 */
    5252#define EAI_APR_TO_RAW(s) (APR_STATUS_IS_EAGAIN(s) ? EAGAIN : EINTR)
     
    487487 * Close the TLS session associated with the given connection
    488488 * structure and free its resources
     489 *
     490 * @param ctxt the mod_gnutls session context
     491 *
     492 * @return a GnuTLS status code, hopefully `GNUTLS_E_SUCCESS`
    489493 */
    490494static int mgs_bye(mgs_handle_t* ctxt)
     
    629633}
    630634
     635/**
     636 * Try to flush the output bucket brigade.
     637 *
     638 * @param ctxt the mod_gnutls session context
     639 *
     640 * @return `1` on success, `-1` on failure.
     641 */
    631642static ssize_t write_flush(mgs_handle_t * ctxt) {
    632643    apr_bucket *e;
     
    772783 * Pull function for GnuTLS
    773784 *
    774  * Generic errnos used for gnutls_transport_set_errno:
    775  * EIO: Unknown I/O error
    776  * ECONNABORTED: Input BB does not exist (NULL)
    777  *
    778  * The reason we are not using APR_TO_OS_ERROR to map apr_status_t to
    779  * errnos is this warning in the APR documentation: "If the statcode
    780  * was not created by apr_get_os_error or APR_FROM_OS_ERROR, the
    781  * results are undefined." We cannot know if this applies to any error
    782  * we might encounter.
     785 * Generic errnos used for `gnutls_transport_set_errno()`:
     786 * * `EAGAIN`: no data available at the moment, try again (maybe later)
     787 * * `EINTR`: read was interrupted, try again
     788 * * `EIO`: Unknown I/O error
     789 * * `ECONNABORTED`: Input BB does not exist (`NULL`)
     790 *
     791 * The reason we are not using `APR_TO_OS_ERROR` to map `apr_status_t`
     792 * to errnos is this warning [in the APR documentation][apr-warn]:
     793 *
     794 * > If the statcode was not created by apr_get_os_error or
     795 * > APR_FROM_OS_ERROR, the results are undefined.
     796 *
     797 * We cannot know if this applies to any error we might encounter.
     798 *
     799 * @param ptr GnuTLS session data pointer (the mod_gnutls context
     800 * structure)
     801 *
     802 * @param buffer buffer for the read data
     803 *
     804 * @param len maximum number of bytes to read (must fit into the
     805 * buffer)
     806 *
     807 * @return The number of bytes read (may be zero on EOF), or `-1` on
     808 * error. Note that some errors may warrant another try (see above).
     809 *
     810 * [apr-warn]: https://apr.apache.org/docs/apr/1.4/group__apr__errno.html#ga2385cae04b04afbdcb65f1a45c4d8506 "Apache Portable Runtime: Error Codes"
    783811 */
    784812ssize_t mgs_transport_read(gnutls_transport_ptr_t ptr,
     
    877905 * Push function for GnuTLS
    878906 *
    879  * In case of unexpected errors gnutls_transport_set_errno is called
    880  * with EIO.  The reason we are not using APR_TO_OS_ERROR to map
    881  * apr_status_t to errnos is this warning in the APR documentation:
    882  * "If the statcode was not created by apr_get_os_error or
    883  * APR_FROM_OS_ERROR, the results are undefined." We cannot know if
    884  * this applies to any error we might encounter.
     907 * `gnutls_transport_set_errno()` will be called with `EAGAIN` or
     908 * `EINTR` on recoverable errors, or `EIO` in case of unexpected
     909 * errors. See the description of mgs_transport_read() for details on
     910 * possible error codes.
     911 *
     912 * @param ptr GnuTLS session data pointer (the mod_gnutls context
     913 * structure)
     914 *
     915 * @param buffer buffer containing the data to send
     916 *
     917 * @param len length of the data
     918 * buffer)
     919 *
     920 * @return The number of written bytes, or `-1` on error. Note that
     921 * some errors may warrant another try (see above).
    885922 */
    886923ssize_t mgs_transport_write(gnutls_transport_ptr_t ptr,
Note: See TracChangeset for help on using the changeset viewer.