An LX_CONN is created with lx_open, closed gracefully with lx_close,
and closed ungracefully with lx_drop.

lx_open
-------

void lx_open(
	const char *disp,
	void (*err)(const LX_LIB_ERR *e, void *arg),
	void (*succ)(LX_CONN *c, void *arg),
	AIO_LOOP *l,
	void *arg,
	unsigned int flags	)

This opens a new connection.  It is the only way to create a new
LX_CONN.  The arguments are:

disp	The string naming the display.  If this is nil, lx_open will
	use getenv("DISPLAY"); if that returns nil as well, the open
	fails.  This string is expected to be of the form
		lhs:rhs
	where lhs is one of
		hostname
		numeric-IPv4-address
		[address-literal]
		the four-character string "unix"
		the zero-length string
	and rhs is one of
		D
		D.S
	where D and S are decimal integers.  (If any connection
	protocols other than IPv4, IPv6, and AF_LOCAL sockets are
	implemented, the lhs possibilities will expand.)

err	A function which gets called on error.  The LX_LIB_ERR type is
	described in errors.txt; the second arg is the next-to-last
	argument to lx_open().  As described in errors.txt, the
	pointed-to LX_LIB_ERR goes invalid at some indeterminate point
	after (*err)() returns.

	err may be nil, in which case the library uses an internal
	function which prints a message to stderr, and calls exit(1).

succ	A function which is called on success.  It LX_CONN pointer is
	the newly-opened connection; the second argument is the
	next-to-last argument to lx_open().  succ must not be nil.

l	The AIO_LOOP to use (see the libaio documentation).  This may
	be nil, in which case the global loop is used (this is what you
	want for simple cases).

arg	A callback arg passed to err or succ, whichever one gets
	called.  It is not otherwise used by liblx.

flags	A flags bitmask.  It can include:

	LX_OPENF_NO_PREAMBLE
		By default, the library automatically does some initial
		protocol exchanges (such as querying and, if supported,
		enabling BIG_REQUESTS) as part of the connection open.
		Specifying this suppresses these; the only protocol
		done as part of open is then just the strict minimum.
		(At this writing, no startup exchanges are actually
		done, so this flag does not actually do anything.  This
		is likely to change.)

	LX_OPENF_DEBUG
		Turns on internal debugging code.  What there is and
		what it does is not documented here; it is there to
		help debug the library, so UTSL.

Note that err and done may be called from within lx_open(); it is a bug
to assume that they will not be called until later.

lx_open is one of the few calls in liblx that can block.  If a hostname
is specified in the display string, liblx calls getaddrinfo() to look
up that name; this call which can block.  I intend to write a
libaio-based non-blocking analog to getaddrinfo(), in which case I will
update liblx to use it.

lx_close
--------

void lx_close(LX_CONN *c)

Closes the LX_CONN down gracefully.  This implies lx_op_abort() on all
pending LX_OPs for it (see pending-operations.txt for more).

lx_drop
-------

void lx_drop(LX_CONN *c)

This ungracefully drops everything related to c.  This is suitable for,
for example, use in a newly-forked child.  Everything is simply freed;
no callbacks are called.  Any file descriptors are closed
unceremoniously.