Problem in SDL_net docs

SDL Development
1

MikeGebirge at gmail.com=====

ok, so I see where the docs are wrong now…
It makes the explaination in the docs much more complicated :stuck_out_tongue_winking_eye:
but they do need to be corrected…I’ll see if I can do that and still
make them easily understandable :slight_smile:

if anyone wants to try and rewrite that paragraph about the return codes,
be my guest!

This is in response to

Re: Problem in SDL_net docs + proposal for new functions
Jonathan Atkins <jcatki jcatki.no-ip.org>
2002-07-01 19:30:28 GMT

as found on http://comments.gmane.org/gmane.comp.lib.sdl/353
I know that I’m responding to an issue nearly 11 years ago.
(post.gmane.org doesn’t allow any other order)

This issue doesn’t seem to be resolved yet, and since he
( http://jcatki.no-ip.org:8080/SDL_net/SDL_net.html#SEC24 )
hosts the very same in-my-eyes-wrong documention as libsdl does
( http://www.libsdl.org/projects/SDL_net/docs/SDL_net_24.html#SEC24 ),
I would like to “be your guest”, and suggest copy/pasting
the documentation from SDLNet.h
(SDL 1.2, as found in the Debian stable repository):

Receive up to ‘maxlen’ bytes of data over the non-server socket ‘sock’,
and store them in the buffer pointed to by ‘data’.
This function returns the actual amount of data received. If the return
value is less than or equal to zero, then either the remote connection was
closed, or an unknown socket error occurred.

To replace this old documentation, still in place since over 11 years:

Receive data of exactly length maxlen bytes from the socket sock,
into the memory pointed to by data.
This routine is not used for server sockets.
Unless there is an error, or the connection is closed, the buffer will
read maxlen bytes. If you read more than is sent from the other end,
then it will wait until the full requested length is sent, or until the
connection is closed from the other end.
You may have to read 1 byte at a time for some applications, for instance,
text applications where blocks of text are sent, but you want to read line
by line. In that case you may want to find the newline characters yourself
to break the lines up, instead of reading some inordinate amount of text
which may contain many lines, or not even a full line of text.
(Taken from http://www.libsdl.org/projects/SDL_net/docs/SDL_net_24.html#SEC24 )

There are two important differences between "old-documented behaviour"
and “actual behaviour”:

  • If there was no data when the function was entered, it returns after
    reading the first TCP packet the client has sent:
    This breaks the “of exactly length maxlen” part.
  • If the function works this way, then reading byte-by-byte may be a
    bad idea (performance), so this example should be removed from the
    documentation. It should be at least pointed out that it is not necessary
    to read byte-by-byte.

The reason I’m writing this: I stumbled across this documentation (same as
above: http://www.libsdl.org/projects/SDL_net/docs/SDL_net_24.html#SEC24 ),
and wrote code depending on this exact behaviour
… and was surprised that it broke due to wrong documentation :frowning:

I want to prevent others from making the same mistake – also,
a wrong documentation is worse than none at all.

Mike Gebirge
(sorry for the fake name)