README.md

   1 rocksock socket library (C) rofl0r
   2 ==================================
   3
   4 rocksock is a powerful (mostly) blocking networking library
   5 written in C.
   6 it was designed for small size, robustness, simplicity,
   7 static linking and fine-grained error reporting and
   8 configurability.
   9
  10 - easy to use
  11 - supports timeout
  12 - supports SSL (optional, currently using openssl or cyassl backend)
  13 - supports chaining of socks4/4a/5 proxies a la proxychains.
  14   the maximum number of proxies can be configured at compiletime.
  15   using a single proxy works as well, of course.
  16 - no global state (except for ssl init routines)
  17 - error reporting mechanism, showing the exact type
  18 - supports DNS resolving (can be turned off for smaller size)
  19 - does not use malloc, and in the DNS-less profile, does not use
  20   any libc functions that could call it.
  21   (malloc typically adds at least 20KB to the binary size if
  22   statically linked).
  23   of course once you build it with ssl support, ssl will definitely
  24   make use of malloc().
  25 - uses [libulz](https://github.com/rofl0r/libulz), a lightweight
  26   C library, featuring things like
  27   a snprintf replacement which doesnt include code for float
  28   handling, giving a much smaller binary size.
  29   currently only 3 functions of libulz are used, so this dependency
  30   could be removed easily if desired.
  31
  32 due to its high configurability, it's not used like a typical lib,
  33 you typically write your app, include the rocksock header using
  34 a relative pathname, and then use the build tool
  35 [rcb](https://github.com/rofl0r/rcb) on your main
  36 C file, supplying all config options as CFLAGS. rcb will then
  37 automatically find all required translation units and throw them at
  38 once at the compiler, giving perfect opportunities for link-time
  39 optimization.
  40
  41 typical tree structure:
  42 ```
  43 myapp/
  44 rocksock/
  45 lib/ (libulz)
  46 ```
  47
  48 myapp/main.c:
  49 ```c
  50 /* tiny program to see if a specific port on a specific host
  51    is open for usage in shellscripts or similar. */
  52 #include "../rocksock/rocksock.h"
  53 #include <stdio.h>
  54 #include <stdlib.h>
  55
  56 static void usage(void) {
  57         dprintf(2, "usage: prog ip port\n");
  58         exit(1);
  59 }
  60
  61 int main(int argc, char** argv) {
  62         if(argc != 3) usage();
  63         rocksock s;
  64         rocksock_init(&s);
  65         rocksock_set_timeout(&s, 5000);
  66         int ret = rocksock_connect(&s, argv[1], atoi(argv[2]), 0);
  67         rocksock_clear(&s);
  68         return ret;
  69 }
  70 ```
  71
  72 ```sh
  73 $ cd myapp
  74 $ CFLAGS="-DUSE_SSL -flto -O3 -s -static" rcb main.c
  75 ```
  76