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