[SDL] Problem in SDL_net docs

Mike Gebirge MikeGebirge at gmail.com
Mon Mar 4 04:21:26 PST 2013


MikeGebirge at gmail.com
=====

> ok, so I see where the docs are wrong now...
> It makes the explaination in the docs much more complicated ;P
> but they do need to be corrected...I'll see if I can do that and still
> make them easily understandable :)
> 
> 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 <at> 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 :-(

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)




More information about the SDL mailing list