#README for libsocket
libsocket is a library with separated C and C++ parts making sockets easy (and object-oriented, if you develop in C++).
Using the C part:
- Link against
libsocket.so
- Functions combining more than one operation on sockets (e.g. create and connect TCP socket)
- Main principle: "One function to connect a socket, one to close it."
Using the C++ part:
- Link against
libsocket++.so
- Classes representing the different socket types, e.g. TCP client sockets, UNIX DGRAM "server" sockets
- Complex (almost complicated...) class hierarchy (
doc/libsocket++/classes.svg
) providing the possibility of extensive and intensive code sharing. - C++ish implementation (features include overloaded stream (
<<
,>>
) operators, functions acceptingstd::string
objects and more-or-less STL use), so -> good integration in other applications or libraries.
##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), only for Linux
- 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 for errors etc. yourself. Your network programs get shorter and better readable.
libsocket supports almost every socket types. During there is no useful documentation, take a look at the header files in headers/. Most of the functions are self-explaining.
Almost every syscall is wrapped by libsocket, e.g.: - sendto - recvfrom - accept - socket/connect - one function - socket/bind - one function
If you're wondering about the UNIX DGRAM functions: Yes, create_unix_dgram_socket("path")
and create_unix_server_socket("path",DGRAM,...)
produces the same result. DGRAM sockets are alway server and client at the same time. The difference is good to distinguish
semantically between the sockets in your code.
If you want to have even 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
##PLATFORMS
libsocket is developed on Linux 3.x with gcc, but every file was successfully tested with clang (from llvm 3.0, 3.1) and works with it.
libsocket works, both statically and dynamically linked, on these platform combinations:
- GCC 4.7, GNU/Linux (tested on Debian and Fedora)
- GCC 4.6, GNU/Linux (tested on Debian)
- clang/clang++ 3.0, GNU/Linux (tested on Debian)
- clang/clang++ 3.1, GNU/Linux (tested on Debian)
- gcc version 4.2.1 20070831 patched, FreeBSD 9.0
- clang/clang++ 3.1 portbld, FreeBSD 9.0
libsocket does not work (AFAIK) on OpenBSD, because there are some source level incompatibilities.
The inet TCP server part and the recvfrom equivalent work on FreeBSD using deprecated gethostbyaddr calls because getnameinfo doesn't work. ##LICENSE and USE
###Static Linkage
It's possible to compile libsocket statically into your program (by placing the .c[pp] and .h[pp] 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 nice to mention libsocket in your product's Readme or advertisements anyway, of course :)
###Dynamic Linkage
The recommended method to use libsocket is to link your program against the libsocket SO. Using this method is quite easy; you have to compile the dynamic libraries (libsocket and libsocket++) using the Makefile (see section "BUILDING")
Linking your programs against the library is also easy; if $OBJECTS are your object files, then link them together using one of these commands:
$ gcc -o yourprog -lsocket $OBJECTS
$ g++ -o yourprog -lsocket++ $OBJECTS
You only need to link against one library, even when using C++, because libsocket++ contains all necessary functions.
If you distribute your program in binary form, it's possible to distribute library binaries along your program and install them along your program.
###Other stuff
You may use other compilers than the GNU Compilers (
##BUILDING
If you want to install both libsocket and libsocket++, simply use this command: # make install
This installs the SOs libsocket.so and libsocket++.so to /usr/lib/ and the header files to /usr/include/libsocket. If you want to change this path, use this command:
# LIBPATH=/path/to/lib/ HEADERPATH=/path/to/headers/libsocket make -e install
This command installs the libs to $LIBPATH and the header files to $HEADERPATH.
If you do not like libsocket anymore, remove it using
# make deinstall
If you specified non-default library or header paths, specify them again and use '-e'.
##EXAMPLES
You may test libsocket and make some experiences by playing with the examples provided in the standard libsocket distribution in examples/ and examples++. More detailed descriptions can be found in the source files. The collection of examples contain (among other):
(C)
http.c
: A simple http clientecho_reconnect.c
,echo_srv.c
: Less echo server than simple transmit of text using INET UDP sockets, but also showing the use ofreconnect_isocket()
unix_stream_client.c
,unix_stream_server.c
: Demonstrating UNIX STREAM sockets as echo server/clientunix_dgram_client.c
,unix_dgram_server.c
: Demonstrating UNIX DGRAM sockets as simple server/client transmitting text.
(C++)
http.cpp
, http_2.cpp: Two simple HTTP clients using slightly different approachesserver.cpp
,client.cpp
: TCP client and serverunix_client_dgram.cpp
: Writes a message to the syslog using UNIX DGRAM socketsecho_server.cpp, echo_client_conn.cpp, echo_client_sndto.cpp
: UDP client/server (two clients: One using sendto(), another using connected datagram sockets)unix_client_stream.cpp, unix_server_stream.cpp
: Client/Server using UNIX STREAM sockets.
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.