commit 76e4960aa9b9badbd9caa376e303f9360ebb7ccd
parent a46c6ca31cfd61d25fb3579807e3405764bcec72
Author: Laurent Bercot <ska-skaware@skarnet.org>
Date: Thu, 18 Dec 2014 23:30:55 +0000
Documentation fixes
Diffstat:
8 files changed, 54 insertions(+), 14 deletions(-)
diff --git a/doc/crosscompile.html b/doc/crosscompile.html
@@ -76,8 +76,10 @@ architecture</strong>, via the --with-sysdeps option to configure.
<p>
The easiest way to get the correct sysdeps for a target achitecture is
-to natively compile skalibs on that target, and steal the produced sysdeps
-files. It can be easily done with a virtual machine, qemu for instance.
+to natively run skalibs' <tt>./configure</tt> script on that target,
+and steal the produced sysdeps files, which are normally written to the
+<tt>./sysdeps.cfg</tt> directory.
+Doing this is easy with a virtual machine, qemu for instance.
You could also (politely) ask for precompiled sysdeps on the
skaware mailing-list, if you cannot find them anywhere on the Internet.
</p>
diff --git a/doc/flags.html b/doc/flags.html
@@ -43,6 +43,10 @@ symbolic link to point to <tt>skalibs-$v</tt> </li>
to the installed skalibs shared libraries. </li>
</ul>
+<p>
+ If this option is not given, no slashpackage support will be provided.
+</p>
+
<a name="replace-libc"><h3> --enable-libc-replacements </h3></a>
<p>
@@ -260,8 +264,8 @@ support.
<p>
If you don't set this option, then skalibs will include IPv6 support in the
-relevant networking functions, if the target architecture supports it.
-The safe option is to let this flag clear.
+relevant networking functions if and only if the target architecture supports it.
+This is the default, and it is safe.
</p>
<a name="forcedevr"><h3> --enable-force-devr </h3></a>
@@ -275,9 +279,9 @@ its autodetection.
<p>
Otherwise, <tt>/dev/random</tt> will be autodetected
and tested; if entropy generation is low on the host, the compilation
-process might hang for several minutes. It is safe to let this flag
+process might hang for several minutes. It is safe to leave this flag
clear; it should only be set to speed up the compilation process in a
-known environment and for testing purposes.
+known environment or for testing purposes.
</p>
<p>
diff --git a/doc/libskarnet.html b/doc/libskarnet.html
@@ -60,14 +60,14 @@ to run <tt>ldconfig</tt> if needed. </li>
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>-l$sysdeps/socket.lib</tt>. If you are using
+will also need to link with <tt>-l`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>-l$sysdeps/tainnow.lib</tt>. </li>
+<tt>-l`cat $sysdeps/tainnow.lib`</tt>. </li>
</ul>
<p>
- The <em>skarnet</em> library as a whole is big (833k for libskarnet.a and
-257k for libskarnet.so.2.0.0.0 on x86_64), but the utmost care has been
+ The <em>skarnet</em> library as a whole is big (826k for libskarnet.a and
+233k for libskarnet.so.2.0.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
diff --git a/doc/libstddjb/djbunix.html b/doc/libstddjb/djbunix.html
@@ -465,7 +465,7 @@ The parent's end of the pipe will be stored in *<em>fd</em>.
</p>
<p>
-<code> pid_t child_spawn1_socket (char const *file, char const *const *argv, char const *const *envp, int *fd)
+<code> pid_t child_spawn1_socket (char const *file, char const *const *argv, char const *const *envp, int *fd) </code> <br />
Like <tt>child_spawn0</tt>, except that a socket is created between the parent
and the child. Both the child's stdin and stdout point to the socket; the parent has
its end of the socket available in *<em>fd</em>.
diff --git a/doc/libstddjb/genwrite.html b/doc/libstddjb/genwrite.html
@@ -46,7 +46,7 @@ stuff to the target without flushing it
(which can be <tt>genwrite_put_stralloc</tt>, <tt>genwrite_put_buffer</tt>,
<tt>genwrite_put_bufalloc</tt> or any
compatible user-defined function) in <tt>.put</tt>, a pointer to a function
-that flushes the target (which can be <tt>genwrite_flush_stralloc</tt>,
+that flushes the target (which can be <tt>genwrite_flush_stralloc</tt>,
<tt>genwrite_flush_buffer</tt>, <tt>genwrite_flush_bufalloc</tt> or any
compatible user-defined function) in <tt>.flush</tt>, and a pointer to
the target writing structure in <tt>.target</tt>.
diff --git a/doc/libstddjb/iopause.html b/doc/libstddjb/iopause.html
@@ -188,7 +188,7 @@ if it is available; but if it is not, then <tt>iopause_poll</tt> defaults to
which has a more comfortable API than
<a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/select.html">select()</a>,
but a maximum precision of 1 millisecond which might not be enough for some applications; whereas
-<tt>iopause_select<tt> defaults to select(), which incurs some CPU overhead for the
+<tt>iopause_select</tt> defaults to select(), which incurs some CPU overhead for the
API conversion, but has a 1 microsecond precision.
</p>
diff --git a/doc/libstddjb/safewrappers.html b/doc/libstddjb/safewrappers.html
@@ -70,7 +70,7 @@ signal is caught. And that means SA_RESTART should not be used.
</p>
<p>
- Which means that other system calls performed when the signal handler has
+ Which also means that other system calls performed when the signal handler has
been installed, for instance in the body of the loop, will <em>not</em> be
protected, and can return -1 EINTR if a signal is caught at the wrong time.
</p>
diff --git a/doc/libunixonacid/skaclient.html b/doc/libunixonacid/skaclient.html
@@ -27,6 +27,40 @@ and implemented in the <tt>libskarnet.a</tt> or <tt>libskarnet.so</tt> library.
<h2> General information </h2>
<p>
+ <tt>skaclient</tt> is a client-server initiation protocol framework, allowing a process
+(the "client") to either connect to another process (the "server") via a Unix domain socket,
+or spawn such a "server" process itself. The client and the server then communicate
+via <em>two</em> sockets, one for synchronous data, the other for asynchronous
+data; they exchange <a href="unixmessage.html">unixmessages</a>.
+</p>
+
+<p>
+ The <tt>skaclient</tt> framework is used in several places in skarnet.org software,
+whenever a server can send asynchronous data to its client. For instance:
+</p>
+
+<ul>
+ <li> Communication between notification subscribers such as
+<a href="http://skarnet.org/software/s6/s6-ftrig-wait.html">s6-ftrig-wait</a>
+and their own <a href="http://skarnet.org/software/s6/s6-ftrigrd.html">s6-ftrigrd</a>
+daemon </li>
+ <li> Communication between clients of the
+<a href="http://skarnet.org/software/s6/libs6lock/">s6lock library</a> and a
+<a href="http://skarnet.org/software/s6/libs6lock/s6lockd.html">s6lockd
+server</a> </li>
+ <li> Communication between a client such as
+<a href="http://skarnet.org/software/s6-dns/s6-dnsip4-filter.html">s6-dnsip4-filter</a>,
+in need of asynchronous DNS service, and its own
+<a href="http://skarnet.org/software/s6-dns/skadns/skadnsd.html">skadnsd</a>
+daemon </li>
+ <li> The <a href="http://skarnet.org/software/skabus/">skabus</a> Unix bus
+infrastructure is entirely based on the skaclient framework to transmit
+unixmessages across processes. </li>
+</ul>
+
+<h2> Programming </h2>
+
+<p>
FIXME: to be completed.
</p>
