[gnutls-dev] API comments

[Simon Josefsson]

On Sun, 2 Dec 2001, Nikos Mavroyanopoulos wrote:

> On Sun, 02 Dec 2001 01:09:47 +0100 Simon Josefsson <jas at extundo.com> wrote:
>
> > gnutls_read() and gnutls_write() does not seem to work as read() and
> > write() as the API documentation on the web page says, especially the
> > error codes differ.
> It says that "Returns the number of bytes sent, or a negative error code.",
> but it may still not be clear. What do you propose?

The complete documentation also say:  The function has the same semantics
as read() has.  This simply isn't true, it returns
GNUTLS_E_{INTERRUPTED,EAGAIN} which read() doesn't do.  Those error codes
aren't mentioned in the read() documentation either.

My suggestion would be to not mess with the return values for read() and
write(), it would be simpler to replce TCP read()/write() with TLS if it
was this way, and the TLS libraries I've used worked this way /as far as I
can remember anyway).

> > I think it would be nice if they did work as
> > read() and write(), I believe both Open SSL and Mozilla NSS do that.
> I'm trying not to tight gnutls to berkeley style sockets, or even TCP/IP.

Good. The type name "SOCKET" always bothered me.

> > It was unclear to me if gnutls_bye() did anything to the socket or not
> > (like, e.g., calling shutdown()).  I want to be able to use the socket
> > after disabling TLS, sending unencrypted packets.  Possible?
> gnutls_bye() and any other gnutls function (except of gnutls_read()/write()),
> do not call any external function such as shutdown.
> Thus in your case if the return value is zero you may continue using the
> connection.

Perhaps the documentation could be clearer, and say that it is the "TLS
connection" that is terminated, instead of "the connection".

>
> > Documentation in info-format would be nice. :-)
> Documentation in gnutls is in latex format. This can be
> converted to several other formats. (and possibly info format but
> I'm not sure)

It was the info format I was after. :-)  Perhaps it is easier to write the
documentation in texinfo format, I don't know.  Or DocBook, it seems
popular, but I don't know anything about it.