SDL2_net misleading documentation

As far as I can see the ‘official’ home page for SDL_net 2.0 is here, but if you then follow the link to the documentation what you get is the documentation for SDL_net 1.2.7. Although much of this is probably relevant to 2.0 as well, it is significantly misleading.

For example in the documentation of SDLNet_TCP_Recv it states “Receive data of exactly length maxlen bytes… Unless there is an error, or the connection is closed, the buffer will read maxlen bytes”. This is wrong: the function may well read fewer than maxlen bytes.

The correct description can be found in the source code: “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”.

Please correct the documentation.

I’m in the process of seeing if we can get the satellite libraries onto the wiki, with their documentation bridged with their headers, the same way we do with SDL itself.

If this works out, we’ll probably see a dramatic improvement in documentation for these libraries pretty quickly. Stay tuned!


I’ve started to improve the SDL_net header documentation. This is as far as I got tonight, but there’s more to go:

Once this is done, I’ll bridge this to the wiki and have the original documentation redirect there. Shouldn’t be much longer.

1 Like

On the subject of SDL2_net, are there any plans to extend it to support secure connections (SSL)? In this security-conscious age, unencrypted communication over the internet is increasingly rare, and many sites cannot be connected to that way.

I appreciate that this would be non-trivial, and would probably entail a dependency on OpenSSL (not sure if that’s a problem on a cross-platform basis), but it would make SDL2_net far more useful.

I don’t have plans to do that (I think of SDL_net as completely superfluous in modern times, now that everything standardized on BSD Sockets), but there are several things that would be obvious good improvements…IPv6 support is another piece of low-hanging fruit.

It’s heavily used by my app, so is greatly appreciated. If there’s an alternative networking library that is equally platform-agnostic I would be interested to know.

There might still be some value in abstracting the differences between Winsock and the normal socket implementations (closesocket() vs close(), WSAEINTR vs EINTR, WSAGetLastError() vs errno, …)

True, but the differences are pretty small in modern times between WinSock and BSD Sockets. IMHO, not enough to warrant an extra dependency to hide them.

The real motivation, I think, was that BSD Sockets and WinSock were mostly similar and Mac OS Classic was completely different. But that’s not a going concern anymore.

SDL_net does add some features over BSD sockets, but I think it has some design mistakes that reflect our understanding of socket programming in the late 1990’s (and maybe reflect exactly what we needed for a specific game at Loki…? I’m not sure), and I think those limit its power significantly.

If I were inclined, I’d encourage an API break and do a new version with an improved API.

1 Like

The differences are small, but sometimes nasty - for example, if(socket(...) < 0) { handle error }; does not work because windows socket handles are unsigned (though maybe modern compilers would at least warn about that)…
But maybe something smaller just to unify the interfaces would be enough (years ago I started and never finished something like that: Half-finished crossplatform sockets (UNIX/BSD sockets vs Winsocks) abstraction · GitHub)

If I were to write new networking code (vs porting existing socket code to new platforms) I’d probably use a higher-level abstraction like enet (or probably a fork with IPv6 support) or one of Glenn Fiedler’s libs or even Cap’n Proto or something.

1 Like

I’m not against that - I’ve had to work around the peculiarities of SDL_net rather than finding them valuable in my particular application.

But SDL_net works and seems to be reliable, so personally I’d rather put any available effort into adding functionality that it doesn’t have than improving the API.

As I said earlier, from a purely practical viewpoint the lack of support for SSL is the one big limitation in my application, so I’m disappointed that this isn’t on the todo list.

You’re welcome to submit pull requests with any improvements you’d like.

No doubt, but writing cross-platform code is a specialism I don’t have! I might be able to write code for Windows and maybe even Linux, but when it comes to Android, iOS and other less familiar platforms I wouldn’t have a clue.

If that wasn’t hard enough, SDL2_net is one of the libraries that Emscripten has built-in support for (although quite why I’ve never been sure, since you can’t access conventional sockets from inside a browser). That’s even more foreign to me.

And then there are the dependencies that would be introduced. The other satellite libraries are moving away from external dependencies, which is great, but I’m pretty sure there’s no cross-platform SSL library which could be incorporated.

Really the only practical contribution I could make would be to offer a financial incentive for somebody else to write it, but I don’t know whether that would help or if it’s even acceptable within the SDL development community.

but when it comes to Android, iOS and other less familiar platforms I wouldn’t have a clue.

We don’t actually know what we’re doing either, we just fake it really well. :slight_smile:

Jokes aside, the SDL_net documentation is rewritten now and up on the wiki! If something in the docs can been improved, feedback is welcome, or just click the “edit” link at the bottom of any page to make changes, and they’ll automatically become GitHub pull requests for us to merge!

1 Like