libskarnet.html (4789B)
1 <html> 2 <head> 3 <meta name="viewport" content="width=device-width, initial-scale=1.0" /> 4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 5 <meta http-equiv="Content-Language" content="en" /> 6 <title>skalibs: the skarnet library interface</title> 7 <meta name="Description" content="skalibs: the skarnet library interface" /> 8 <meta name="Keywords" content="skalibs skarnet libskarnet library interface" /> 9 <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> 10 </head> 11 <body> 12 13 <p> 14 <a href="index.html">skalibs</a><br /> 15 <a href="//skarnet.org/software/">Software</a><br /> 16 <a href="//skarnet.org/">skarnet.org</a> 17 </p> 18 19 <h1> The <tt>skarnet</tt> library interface </h1> 20 21 <p> 22 <em>libskarnet</em> is the library exported by skalibs; both a static 23 library and a shared library (if they are supported on your system) are 24 available. Every skarnet.org binary needs this library. 25 </p> 26 27 <h2> Compiling </h2> 28 29 <ul> 30 <li> Make sure the place you installed the skalibs header files in is in 31 your header directory list; the default is <tt>/usr/include</tt>, 32 which is normally browsed by default by your C preprocessor. </li> 33 <li> Use <tt>#include <skalibs/<em>foobar.h</em>></tt> where 34 <em>foobar.h</em> is the header you need. 35 <ul> 36 <li> The <tt>skalibs/skalibs.h</tt> header is the general entry 37 point that will declare the near-entirety of the functions, variables 38 and constants in skalibs. Including this header 39 in your source files whenever you need a skalibs function will work; 40 however, it is rather heavy, and you might want to include lower-level 41 headers instead to reduce compilation time. </li> 42 </ul> 43 </li> 44 </ul> 45 46 <h2> Linking </h2> 47 48 <ul> 49 <li> For static linking: 50 add <tt>/usr/lib/skalibs</tt>, or wherever you installed 51 your .a files, to your library directory list. </li> 52 <li> For dynamic linking: 53 make sure the place you installed the libskarnet.so shared library in 54 is in your shared library directory list; the default is <tt>/lib</tt>, 55 which is normally browsed by default by your build-time and run-time linker. 56 If you are using another place than the default (for instance, if you are 57 using the slashpackage convention), make sure to 58 edit your <tt>ld.so.conf</tt> file so your linker can find this place, and 59 to run <tt>ldconfig</tt> if needed. </li> 60 <li> Take note of the place where your sysdeps directory has been 61 installed: by default, it's <tt>/usr/lib/skalibs/sysdeps</tt>. Let's call 62 it <tt>$sysdeps</tt>. </li> 63 <li> Link with <tt>-lskarnet</tt>. If you are using socket functions, you 64 will also need to link with <tt>`cat $sysdeps/socket.lib`</tt>. If you are using 65 time functions such as <tt>tain_now()</tt>, you will also need to link with 66 <tt>`cat $sysdeps/sysclock.lib`</tt>. Also 67 <tt>`cat $sysdeps/spawn.lib`</tt>` for <tt>posix_spawn()</tt> functions, 68 <tt>timer.lib</tt> for <tt>timer_create</tt> functions, and so on. This 69 is, unfortunately, the only way to work with all the idiosyncrasies and 70 whimsies of various libcs; only 71 <a href="https://www.musl-libc.org/">musl</a> does the sensible thing and 72 exports all its functions from <tt>libc.a</tt> and <tt>libc.so</tt>, 73 without requiring any additional linker command line flags. </li> 74 </ul> 75 76 <p> 77 The <em>skarnet</em> library as a whole is big (945k for libskarnet.a and 78 179k for libskarnet.so.2.4.0.0 on x86_64-linux), but the utmost care has been 79 given to separate functions so that linkers never pull in any more than they 80 need. Linking against the static version of libskarnet actually produces 81 very small executables, and if your libc is suited for that, since skalibs 82 only uses very basic libc interfaces, it is very possible to produce small 83 static binaries - in many cases, a static program written with skalibs APIs 84 will be an order of magnitude smaller than the equivalent program written 85 using libc's or other utility libraries' APIs. 86 </p> 87 88 <h2> Programming </h2> 89 90 <p> 91 The skalibs source code is divided into several subdirectories, each 92 containing a logical unit of code implementing independent functions. 93 </p> 94 95 <ul> 96 <li><a href="libposixplz/">libposixplz</a>: workarounds for some POSIX 97 deficiencies and for systems that don't quite implement POSIX </li> 98 <li><a href="libstddjb/">libstddjb</a>: basic C API for system programming </li> 99 <li><a href="libdatastruct/">libdatastruct</a>: efficient C implementation of 100 basic data structures like sets or trees</li> 101 <li><a href="libstdcrypto/">libstdcrypto</a>: a few crypto primitives </li> 102 <li><a href="librandom/">librandom</a>: cryptographically secure random or 103 pseudorandom number generation </li> 104 <li><a href="libunixonacid/">libunixonacid</a>: more advanced C/Unix APIs, 105 mainly for safe asynchronous interprocess communication </li> 106 </ul> 107 108 </body> 109 </html>