#README for libsocket
##LICENSE
It's recommended to compile libsocket statically into your program (by placing the .c and .h files in your source tree). You don't have to mind legal issues because libsocket is licensed by a slightly modified 2-clause BSD license which permits any use, as long as you include the license text in your product (so it's clear that libsocket is licensed by this License) and the notice that we wrote libsocket (as described in the license) It's friendly to mention libsocket in your product's Readme or advertisements anyway, of course :)
##USE
libsocket is built for little programs whose author(s) are too lazy to build own algorithms and functions for socket (UNIX and Internet Domain (TCP/UDP)) communication.
As you should know as experienced C programmer, it's quite easy to use this library. Simply add the line into the source files where the library is used:
# include "path/to/lib{inet,unix}socket.h"
and call the compiler (eventually in a makefile) with the name of the C file:
$ gcc lib{inet,unix}socket.c ownfile1.c ownfile2.c
# or
$ gcc -c libsocket.c
$ gcc ownfile1.c ownfile2.c libsocket.o
# etc. pp.
##FEATURES AND ADVANTAGES
The libsocket library supports following things and protocols:
- IPv4 (client, server)
- IPv6 (client, server; if your machine supports it)
- TCP (client, server)
- UDP (client, server)
- UNIX Domain Sockets (DGRAM&STREAM server/client)
- Intelligent algorithms to get the best connection and no errors
- Easy use (one function call to get a socket up and running, one another to close it)
- Proper error processing (using errno, gai_strerror() etc.).
One of the main advantages of libsocket is that you don't have to write the complex and error-prone procedures for connecting a socket, check it on errors etc. yourself.
But libsocket does not support every use of sockets. For example, there is no such function like sendto() because the developer
thinks that connected UDP sockets are easier to handle and equal. The combination of connected DGRAM (DGRAM, UDP) sockets and the function
reconnect_isocket() resp. reconnect_usocket() provides an interface which is also quite easy. On the other side, some functions support
the use of 'raw' flags which are passed to the underlying Sockets API functions (e.g. create_isocket() which accepts flags like SOCK_NONBLOCK).
I also had the design goal that the library should use the real sockets accepted by read()/write() syscalls etc and not structures (like FILE
pointers used by libc) so you may control sockets nevertheless with setsockopt().
If you want to have more control over the sockets you're using, this library is not the right tool for you. It's intended for the easy use of sockets.
For detailed documentation read DOCUMENTATION.md resp. DOCUMENTATION.html
##LIMITS It is important to say that the UNIX DGRAM socket implementation is not quite good. It may be enough for a simple server/client model, but even answering on connected DGRAM sockets is a quite creepy thing :|
But this is not really bad because UNIX sockets are very easy to handle, also without libsocket. And UNIX DGRAM sockets are anyway hard to handle, I think...
##EXAMPLES
You may test libsocket and make some experiences by playing with the examples provided in the standard libsocket distribution in examples/. The collection of examples contain:
- http.c: A simple http client
- echo_reconnect.c, echo_srv.c: Less echo server than simple transmit of text using INET UDP sockets, but also showing the use of
reconnect_isocket() - unix_stream_client.c, unix_stream_server.c: Demonstrating UNIX STREAM sockets as echo server/client
- unix_dgram_client.c, unix_dgram_server.c: Demonstrating UNIX DGRAM sockets as simple 5E4D server/client transmitting text.
You should have a look at the length of the code; while http.c is complete with 24 sloc (source lines of code) - the quite similar client
simple-http (https://github.com/dermesser/Simple-HTTP-client) uses almost 70 lines of code.
##PLATFORMS
libsocket is developed on Linux 3.x with gcc, but every file was successfully tested with clang (from llvm 3.0) and works with it. Since revision 396d05, libinetsocket.c works on OpenBSD 5.0. I'm working on porting libunixsocket to OpenBSD which is much harder (I guess so at the moment).