1 files changed, 187 insertions, 0 deletions
diff --git a/doc/xs.txt b/doc/xs.txt
new file mode 100644
index 0000000..635c7d5
--- /dev/null
+++ b/doc/xs.txt
@@ -0,0 +1,187 @@
+xs(7)
+=====
+
+
+NAME
+----
+xs - Crossroads, a lightweight messaging layer
+
+
+SYNOPSIS
+--------
+*#include <xs.h>*
+
+*cc* ['flags'] 'files' *-lxs* ['libraries']
+
+
+DESCRIPTION
+-----------
+Crossroads is a library which extends the standard
+socket interfaces with features traditionally provided by specialised
+_messaging middleware_ products. Crossroads sockets provide an abstraction of
+asynchronous  _message queues_, multiple _messaging patterns_, message
+filtering (_subscriptions_), seamless access to multiple _transport protocols_
+and more.
+
+This documentation presents an overview of Crossroads concepts, describes how
+Crossroads abstract standard sockets and provides a reference manual for the
+functions provided by the Crossroads library.
+
+
+Context
+~~~~~~~
+Before using any Crossroads library functions the caller must initialise a
+'context' using _xs_init()_. The following functions are provided to handle
+initialisation and termination of a 'context':
+
+Initialise Crossroads context::
+    linkxs:xs_init[3]
+
+Terminate Crossroads context::
+    linkxs:xs_term[3]
+
+
+Thread safety
+^^^^^^^^^^^^^
+A 'context' is thread safe and may be shared among as many application
+threads as necessary, without any additional locking required on the part of
+the caller.
+
+Individual Crossroads 'sockets' are _not_ thread safe except in the case where
+full memory barriers are issued when migrating a socket from one thread to
+another. In practice this means applications can create a socket in one thread
+with _xs_socket()_ and then pass it to a _newly created_ thread as part of
+thread initialization, for example via a structure passed as an argument to
+_pthread_create()_.
+
+
+Multiple contexts
+^^^^^^^^^^^^^^^^^
+Multiple 'contexts' may coexist within a single application. Thus, an
+application can use Crossroads directly and at the same time make use of any
+number of additional libraries or components which themselves make use of
+Crossroads as long as the above guidelines regarding thread safety are adhered
+to.
+
+
+Messages
+~~~~~~~~
+A Crossroads message is a discrete unit of data passed between applications or
+components of the same application. Crossroads messages have no internal
+structure and from the point of view of Crossroads themselves they are
+considered to be opaque binary data.
+
+The following functions are provided to work with messages:
+
+Initialise a message::
+    linkxs:xs_msg_init[3]
+    linkxs:xs_msg_init_size[3]
+    linkxs:xs_msg_init_data[3]
+
+Release a message::
+    linkxs:xs_msg_close[3]
+
+Access message content::
+    linkxs:xs_msg_data[3]
+    linkxs:xs_msg_size[3]
+
+Message manipulation::
+    linkxs:xs_msg_copy[3]
+    linkxs:xs_msg_move[3]
+
+
+Sockets
+~~~~~~~
+Crossroads sockets present an abstraction of a asynchronous _message queue_,
+with the exact queueing semantics depending on the socket type in use. See
+linkxs:xs_socket[3] for the socket types provided.
+
+The following functions are provided to work with sockets:
+
+Creating a socket::
+    linkxs:xs_socket[3]
+
+Closing a socket::
+    linkxs:xs_close[3]
+
+Manipulating socket options::
+    linkxs:xs_getsockopt[3]
+    linkxs:xs_setsockopt[3]
+
+Establishing a message flow::
+    linkxs:xs_bind[3]
+    linkxs:xs_connect[3]
+
+Sending and receiving messages::
+    linkxs:xs_send[3]
+    linkxs:xs_recv[3]
+
+.Input/output multiplexing
+Crossroads provide a mechanism for applications to multiplex input/output events
+over a set containing both Crossroads sockets and standard sockets. This
+mechanism mirrors the standard _poll()_ system call, and is described in detail
+in linkxs:xs_poll[3].
+
+
+Transports
+~~~~~~~~~~
+A Crossroads socket can use multiple different underlying transport mechanisms.
+Each transport mechanism is suited to a particular purpose and has its own
+advantages and drawbacks.
+
+The following transport mechanisms are provided:
+
+Unicast transport using TCP::
+    linkxs:xs_tcp[7]
+
+Reliable multicast transport using PGM::
+    linkxs:xs_pgm[7]
+
+Local inter-process communication transport::
+    linkxs:xs_ipc[7]
+
+Local in-process (inter-thread) communication transport::
+    linkxs:xs_inproc[7]
+
+ERROR HANDLING
+--------------
+The Crossroads library functions handle errors using the standard conventions
+found on POSIX systems. Generally, this means that upon failure a Crossroads
+library function shall return either a NULL value (if returning a pointer) or
+a negative value (if returning an integer), and the actual error code shall be
+stored in the 'errno' variable.
+
+On non-POSIX systems some users may experience issues with retrieving the
+correct value of the 'errno' variable. The _xs_errno()_ function is provided
+to assist in these cases; for details refer to linkxs:xs_errno[3].
+
+The _xs_strerror()_ function is provided to translate Crossroads-specific error
+codes into error message strings; for details refer to linkxs:xs_strerror[3].
+
+
+MISCELLANEOUS
+-------------
+The following miscellaneous functions are provided:
+
+Report Crossroads library version::
+    linkxs:xs_version[3]
+
+
+LANGUAGE BINDINGS
+-----------------
+The Crossroads library provides interfaces suitable for calling from programs in
+any language; this documentation documents those interfaces as they would be
+used by C programmers. The intent is that programmers using Crossroads from
+other languages shall refer to this documentation alongside any documentation
+provided by the vendor of their language binding.
+
+AUTHORS
+-------
+The Crossroads documentation was written by Martin Sustrik <sustrik@250bpm.com>
+and Martin Lucina <martin@lucina.net>.
+
+COPYING
+-------
+Free use of Crossroads library is granted under the terms of the GNU Lesser
+General Public License (LGPL). For details see the files `COPYING` and
+`COPYING.LESSER` included with the Crossroads distribution.