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 programming in a blocking way is much simpler, but can lead to
  10 near infinite blocking. rocksock addresses this by providing
  11 timeouts so the app doesn't get into a completely blocked
  12 state and can react properly on any exceptional condition.
  13 making the app fit for SSL only requires enabling one flag, and
  14 SOCKS/HTTP proxy support is built-in as well.
  15
  16 - easy to use
  17 - supports timeout
  18 - supports SSL (optional, currently using openssl or cyassl backend)
  19 - supports chaining of socks4/4a/5 proxies a la proxychains.
  20   the maximum number of proxies can be configured at compiletime.
  21   using a single proxy works as well, of course.
  22 - no global state (except for ssl init routines)
  23 - error reporting mechanism, showing the exact type
  24 - supports DNS resolving (can be turned off for smaller size)
  25 - does not use malloc, and in the DNS-less profile, does not use
  26   any libc functions that could call it.
  27   (malloc typically adds at least 20KB to the binary size if
  28   statically linked).
  29   of course once you build it with ssl support, ssl will definitely
  30   make use of malloc().
  31   you need to add NO_DNS_SUPPORT to your CFLAGS
  32   so nothing that can call malloc gets pulled in, if you want a
  33   minimal static binary (in that case you have to pass ipv4
  34   addresses in dotted notation).
  35 - optionally uses [libulz](https://github.com/rofl0r/libulz),
  36   a lightweight C library, featuring things like
  37   a snprintf replacement which doesnt include code for float
  38   handling.
  39   this can make a statically linked binary a couple dozen KB
  40   smaller if no particularly bloated libc internals are being
  41   used in other parts of linked-in code.
  42   so if you use any SSL implementation, you won't gain anything
  43   by using libulz.
  44
  45 build:
  46
  47   for a "default" build, for example for a distribution, just
  48   use ./configure && make as usual.
  49
  50 advanced/customized build using RcB:
  51
  52   write your app, include the rocksock header using
  53   a relative pathname, and then use the build tool
  54   [rcb](https://github.com/rofl0r/rcb) on your main
  55   C file, supplying all config options as CFLAGS. rcb will then
  56   automatically find all required translation units and throw them
  57   at once at the compiler, giving perfect opportunities for link-time
  58   optimization.
  59
  60 typical tree structure:
  61 ```
  62 myapp/
  63 rocksock/
  64 lib/ (libulz)
  65 ```
  66
  67 myapp/main.c:
  68 ```c
  69 /* tiny program to see if a specific port on a specific host
  70    is open for usage in shellscripts or similar. */
  71 #include "../rocksock/rocksock.h"
  72 #include <stdio.h>
  73 #include <stdlib.h>
  74
  75 static void usage(void) {
  76         dprintf(2, "usage: prog ip port\n");
  77         exit(1);
  78 }
  79
  80 int main(int argc, char** argv) {
  81         if(argc != 3) usage();
  82         rocksock s;
  83         rocksock_init(&s);
  84         rocksock_set_timeout(&s, 5000);
  85         int ret = rocksock_connect(&s, argv[1], atoi(argv[2]), 0);
  86         rocksock_clear(&s);
  87         return ret;
  88 }
  89 ```
  90
  91 ```sh
  92 $ cd myapp
  93 $ CFLAGS="-DUSE_SSL -flto -O3 -s -static" rcb main.c
  94 ```
  95