README.md

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