[gnutls-dev] Re: gnutls_record_send/recv documentation inconsistencies

[Simon Josefsson]

Tim Kosse <tim.kosse at filezilla-project.org> writes:

> Currently, the documentation for both gnutls_record_recv as well as
> gnutls_record_send contains this paragraph:
>
> " * If EINTR is returned by the internal push function (the default is
>   * @code{recv()}) then GNUTLS_E_INTERRUPTED will be returned. If
>   * GNUTLS_E_INTERRUPTED or GNUTLS_E_AGAIN is returned, you must call
>   * this function again, with the same parameters; alternatively you
>   * could provide a NULL pointer for data, and 0 for
>   * size. cf. @code{gnutls_record_get_direction()}."
>
> Actually, both the push and the pull functions can be invoked by a call
> to either of the two functions.

Really?  I thought gnutls_record_recv never sent anything, and vice
versa.

> In the case of gnutls_record_recv, calling this function with NULL data
> and/or 0 size, GNUTLS_E_INVALID_REQUEST is returned, even if it failed
> with GNUTLS_E_AGAIN before.
>
> Furthermore, the requirement to "call this function again, with the same
> parameters" does not hold for gnutls_record_recv either.

I've changed gnutls_record_recv's docstring to:

  * If EINTR is returned by the internal push function (the default is
  * @code{recv()}) then %GNUTLS_E_INTERRUPTED will be returned. If
  * %GNUTLS_E_INTERRUPTED or %GNUTLS_E_AGAIN is returned, you must
  * call this function again to get the data.  See also
  * @code{gnutls_record_get_direction()}.

Does this looks right to you?

Feel free to suggest specific modifications to improve the problem you
find.

I'm not sure exactly what we want to happen here, there seems to be
some buffering going on which is counter to calling the function again
with the same parameters.

/Simon