[Copyright status: this file is in the public domain.]

It is possible to associate arbitrary-data pointers with each LX_CONN.
There are two ways to do this.

The first way is simpler: there is one user-data pointer, a void *,
associated with each LX_CONN; it is set to nil when the LX_CONN is
created and there are calls to set and get it:

void lx_set_udata(LX_CONN *conn, void *d)
void *lx_get_udata(LX_CONN *conn)

The downside of this is that there is only one such pointer per
connection, so it is useful only for the application; it is of no value
for another library built to run with liblx, unless it is certain
neither the application nor any other such library will want to use it.
Its advantage is that it is very simple in both concept and
implementation.

The other way is connection private pointers.  These are data pointers
named by non-negative ints.  There is a (program-global) registry of
these ints; each LX_CONN conceptually has an array of these pointers,
one for each possible non-negative int value, initially all nil.  There
are calls to get a new index into the array (one of the "ints" above)
and to get and set a given index's pointer for a given LX_CONN.  For
brevity, below, these pointers are called "connpriv" pointers, and the
integer subscripts into that array are called "index" values.  (This
facility is modeled loosely after the device-privates mechanisms in the
MIT sample X server.)

The API promises that an index can fit into an int and is never
negative.  It does not promise anything else; for example, there is no
promise that they are _small_ integers.  They also are not portable
between runs; even for the exact same binary running the exact same
sequence of calls, there is no guarantee that the index values from one
run bear any relation to the index values from another.

The API represents connpriv pointers as void *.

lx_new_conn_private
-------------------

int lx_new_conn_private(void)

Allocates and returns a new index; all LX_CONNs' connpriv pointers for
this index are initially nil.

lx_get_private
--------------

void *lx_get_private(LX_CONN *xc, int x)

Returns xc's connpriv pointer for index x.

lx_set_private
--------------

void *lx_set_private(LX_CONN *xc, int x, void *v)

Sets xc's connpriv pointer for index x to v, returning the previous
value of that connpriv pointer.

It is possible for lx_set_private to run out of memory.  This is
reflected as an LX_LE_NOMEM error on the LX_CONN.

It is a catastrophic application error to call lx_get_private or
lx_set_private with an index not previously returned by
lx_new_conn_private during the same run.  The library's reaction to
such calls is undefined.

Closing an LX_CONN does not do anything in particular with its user
data pointer, nor any connpriv pointers it may have.