Documentation + return -1 screen when not specified

Signed-off-by: Mattias Andrée <maandree@kth.se>

18 files changed, 318 insertions, 24 deletions

diff --git a/LIBAXL_DECNET_OBJECT_MAX.3 b/LIBAXL_DECNET_OBJECT_MAX.3
new file mode 120000
index 0000000..cd85f24
--- /dev/null
+++ b/LIBAXL_DECNET_OBJECT_MAX.3
@@ -0,0 +1 @@
+libaxl_get_decnet_object.3
\ No newline at end of file
diff --git a/LIBAXL_REQUEST_CIRCULATE_WINDOW.3 b/LIBAXL_REQUEST_CIRCULATE_WINDOW.3
index 6e3a575..11eab27 100644
--- a/LIBAXL_REQUEST_CIRCULATE_WINDOW.3
+++ b/LIBAXL_REQUEST_CIRCULATE_WINDOW.3
@@ -33,7 +33,8 @@ If another client is listening for [TODO SubstructureRedirect]
 events on the specified window, a [TODO CirculateRequest]
 request is sent to the client instead, and no further
 processing is performed. If however, no such client, other
-than the sender, exists, a [TODO CirculateNotify]
+than the sender, exists, a
+.I LIBAXL_EVENT_CIRCULATE_NOTIFY
 event is generated if the window is actually restacked.
 .PP
 Normal exposure processing on formerly
diff --git a/LIBAXL_REQUEST_DELETE_PROPERTY.3 b/LIBAXL_REQUEST_DELETE_PROPERTY.3
index 09819e0..13468df 100644
--- a/LIBAXL_REQUEST_DELETE_PROPERTY.3
+++ b/LIBAXL_REQUEST_DELETE_PROPERTY.3
@@ -21,7 +21,8 @@ specified in the
 field from the window whose ID is specified in
 the
 .I window
-field, and generate a [TODO PropertyNotify]
+field, and generate a
+.I LIBAXL_EVENT_PROPERTY_NOTIFY
 event on the window.
 .PP
 This request has no effect if the property
diff --git a/LIBAXL_REQUEST_FREE_COLORMAP.3 b/LIBAXL_REQUEST_FREE_COLORMAP.3
index 9f1467b..04534ba 100644
--- a/LIBAXL_REQUEST_FREE_COLORMAP.3
+++ b/LIBAXL_REQUEST_FREE_COLORMAP.3
@@ -26,10 +26,12 @@ will be uninstalled.
 If the colormap is defined as the colormap for a
 window, the colormap for the window is changed to
 .BR LIBAXL_NONE ,
-and a [TODO ColormapNotify] event
-is generated. (The protocol does not define colors
-displayed for a window with LIBAXL_NONE as the
-colormap).
+and a
+.I LIBAXL_EVENT_COLORMAP_NOTIFY
+event is generated. (The protocol does not define
+colors displayed for a window with
+.I LIBAXL_NONE
+as the colormap).
 .PP
 When no resource references the colormap, it will
 be deallocated.
diff --git a/LIBAXL_REQUEST_MAP_WINDOW.3 b/LIBAXL_REQUEST_MAP_WINDOW.3
index a7a4462..86d4bcd 100644
--- a/LIBAXL_REQUEST_MAP_WINDOW.3
+++ b/LIBAXL_REQUEST_MAP_WINDOW.3
@@ -24,10 +24,12 @@ event. However, if the
 attribute of the window is false and another
 client is listening on [TODO SubstructureRedirect]
 events on the parent of the window, the window remains
-unmapped but a [TODO MapRequest] event
-is sent to that client. Otherwise, the window is
-mapped and a [TODO MapNotify] event
-is generated.
+unmapped but a
+.I LIBAXL_EVENT_MAP_REQUEST
+event is sent to that client. Otherwise, the
+window is mapped and a
+.I LIBAXL_EVENT_MAP_NOTIFY
+event is generated.
 .PP
 Exposure processing is performed on the window.
 .PP
diff --git a/Makefile b/Makefile
index b894be7..4f1114e 100644
--- a/Makefile
+++ b/Makefile
@@ -133,6 +133,7 @@ MAN3 =\
 	LIBAXL_ATOM_WM_TRANSIENT_FOR.3\
 	LIBAXL_ATOM_WM_ZOOM_HINTS.3\
 	LIBAXL_ATOM_X_HEIGHT.3\
+	LIBAXL_DECNET_OBJECT_MAX.3\
 	LIBAXL_ERROR.3\
 	LIBAXL_ERROR_ACCESS.3\
 	LIBAXL_ERROR_ALLOC.3\
@@ -277,12 +278,17 @@ MAN3 =\
 	LIBAXL_REQUEST_UNMAP_SUBWINDOWS.3\
 	LIBAXL_REQUEST_UNMAP_WINDOW.3\
 	LIBAXL_REQUEST_WARP_POINTER.3\
+	libaxl_attach.3\
 	libaxl_context_create.3\
 	libaxl_context_free.3\
+	libaxl_create.3\
 	libaxl_deallocate_id.3\
+	libaxl_detach.3\
 	libaxl_fileno.3\
 	libaxl_generate_id.3\
+	libaxl_get_decnet_object.3\
 	libaxl_get_tcp_port.3\
+	libaxl_parse_display.3\
 	libaxl_protocol_version.3\
 	libaxl_protocol_version_major.3\
 	libaxl_protocol_version_minor.3\
diff --git a/TODO b/TODO
index 14536aa..bf1008c 100644
--- a/TODO
+++ b/TODO
@@ -1,3 +1,5 @@
 Man pages: check italic–bold consistency
 Man pages: check values of constants
 Add libaxl_connect
+Add libaxl_marshal
+Add libaxl_unmarshal
diff --git a/common.h b/common.h
index aee5172..e57fd78 100644
--- a/common.h
+++ b/common.h
@@ -55,7 +55,7 @@ DEFINE_CHECKED(ssize_t, __checked_ssize_t)
 
 #define X_TCP_PORT 6000
 
-struct libaxl_connection { /* TODO add serialisation functions */
+struct libaxl_connection {
 	int                         fd;
 	uint16_t                    last_seqnum;
 	LIBAXL_CONNECTION_RWLOCK;
diff --git a/libaxl/advanced.h b/libaxl/advanced.h
index b2ccdac..3164a36 100644
--- a/libaxl/advanced.h
+++ b/libaxl/advanced.h
@@ -73,7 +73,7 @@ int libaxl_protocol_version(void);
  * @return        The file descriptor of the connection
  */
 _LIBAXL_GCC_ONLY(__attribute__((__nonnull__, __warn_unused_result__)))
-int libaxl_detach(LIBAXL_CONNECTION *); /* TODO man */
+int libaxl_detach(LIBAXL_CONNECTION *);
 
 /**
  * Change the file descriptor of a connection
@@ -82,4 +82,4 @@ int libaxl_detach(LIBAXL_CONNECTION *); /* TODO man */
  * @param  fd    The new file descriptor
  */
 _LIBAXL_GCC_ONLY(__attribute__((__nonnull__)))
-void libaxl_attach(LIBAXL_CONNECTION *, int); /* TODO man */
+void libaxl_attach(LIBAXL_CONNECTION *, int);
diff --git a/libaxl/low-level.h b/libaxl/low-level.h
index d817a7d..d7413b8 100644
--- a/libaxl/low-level.h
+++ b/libaxl/low-level.h
@@ -12,7 +12,7 @@
  * The largest possible return of the libaxl_get_decnet_object()
  * function, plus 1 for the terminal NUL byte
  */
-#define LIBAXL_DECNET_OBJECT_MAX (5 + 3 * sizeof(int) - sizeof(int) / 2) /* TODO man */
+#define LIBAXL_DECNET_OBJECT_MAX (5 + 3 * sizeof(int) - sizeof(int) / 2)
 
 /**
  * Create a connection object for a socket
@@ -25,7 +25,7 @@
  * is always LIBAXL_ERROR_SYSTEM
  */
 _LIBAXL_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__)))
-LIBAXL_CONNECTION *libaxl_create(int); /* TODO man */
+LIBAXL_CONNECTION *libaxl_create(int);
 
 /**
  * Parse a display name string
@@ -44,11 +44,11 @@ LIBAXL_CONNECTION *libaxl_create(int); /* TODO man */
  * @param   protocolp  Output parameter for the network protocol used to access the display,
  *                     remember to free after successful completion
  * @param   displayp   Output parameter for the display's index (0 if the protocol is "unix")
- * @param   screenp    Output parameter for the screen's index
+ * @param   screenp    Output parameter for the screen's index (-1 of not specified)
  * @return             0 on success, a negative libaxl error code on failure
  */
 _LIBAXL_GCC_ONLY(__attribute__((__nonnull__(2, 3, 4, 5))))
-int libaxl_parse_display(const char *, char **, char **, int *, int *); /* TODO man */
+int libaxl_parse_display(const char *, char **, char **, int *, int *);
 
 /**
  * Get the TCP port that is used for a display
@@ -66,7 +66,7 @@ inline uint16_t libaxl_get_tcp_port(int display)
  * Get the DECnet object name that is used for a display
  * 
  * @param   buf      Buffer that the object name shall be written to, it is recommended
- *                   that is size, if static, is LIBAXL_DECNET_OBJECT_MAX (which is
+ *                   that its size, if static, is LIBAXL_DECNET_OBJECT_MAX (which is
  *                   always sufficient), otherwise it should be at least the return value
  *                   of this function (for the same last argument but with NULL and 0
  *                   as the first two arguments) plus 1
@@ -75,10 +75,10 @@ inline uint16_t libaxl_get_tcp_port(int display)
  * @return           The length of the object name, will not exceed LIBAXL_DECNET_OBJECT_MAX
  *                   less 1; an additional uncounted NUL byte will be written to the buffer
  *                   if it is large enough; or -1 on failure (specifically snprintf(3), which
- *                   the function calls, by fail with EOVERFLOW if the `size` argument is
+ *                   the function calls, will fail with EOVERFLOW if the `size` argument is
  *                   greater than {INT_MAX})
  */
-int libaxl_get_decnet_object(char *, size_t, int); /* TODO man */
+int libaxl_get_decnet_object(char *, size_t, int);
 
 /**
  * This function is to be called once and only once, excluding any
diff --git a/libaxl_attach.3 b/libaxl_attach.3
new file mode 100644
index 0000000..0ec4f8f
--- /dev/null
+++ b/libaxl_attach.3
@@ -0,0 +1,33 @@
+.TH libaxl_attach 3 libaxl
+.SH NAME
+libaxl_attach - Change file descriptor of a connection
+.SH SYNOPSIS
+.nf
+#include <libaxl.h>
+
+void libaxl_attach(LIBAXL_CONNECTION *\fIconn\fP, int \fIfd\fP);
+.fi
+.SH DESCRIPTION
+The
+.BR libaxl_attach ()
+function changes the file descript in the
+connection record specified in the
+.I conn
+parameter, which the function will assume is
+.RI non- NULL ,
+to the file descriptor specified in the
+.I fd
+parameter.
+.SH RETURN VALUE
+None.
+.SH ERRORS
+The
+.BR libaxl_attach ()
+function cannot fail.
+.SH NOTES
+None.
+.SH SEE ALSO
+.BR libaxl_unmarshal (3),
+.BR libaxl_create (3),
+.BR libaxl_fileno (3),
+.BR libaxl_detach (3)
diff --git a/libaxl_context_create.3 b/libaxl_context_create.3
index 5736645..05c9f20 100644
--- a/libaxl_context_create.3
+++ b/libaxl_context_create.3
@@ -23,7 +23,7 @@ returns the context on success completion, or
 on failure.
 .SH ERRORS
 The
-.BR libaxl_generate_id ()
+.BR libaxl_context_create ()
 function can only fail if enough memory
 cannot be allocates for the process,
 which is corresponds to the
@@ -34,4 +34,6 @@ libaxl error number.
 .SH NOTES
 None.
 .SH SEE ALSO
-.BR libaxl_context_free (3)
+.BR libaxl_context_free (3),
+.BR libaxl_connect (3),
+.BR libaxl_create (3)
diff --git a/libaxl_create.3 b/libaxl_create.3
new file mode 100644
index 0000000..00417dc
--- /dev/null
+++ b/libaxl_create.3
@@ -0,0 +1,46 @@
+.TH libaxl_create 3 libaxl
+.SH NAME
+libaxl_create - Create connection record
+.SH SYNOPSIS
+.nf
+#include <libaxl.h>
+
+LIBAXL_CONNECTION *libaxl_create(int \fIfd\fP);
+.fi
+.SH DESCRIPTION
+The
+.BR libaxl_create ()
+function creates a connection record context,
+for a connection to the display server. The
+connection does not have to be established
+yet, but they socket for the connection should
+have been created and should be specified in the
+.I fd
+parameter.
+.SH RETURN VALUE
+The
+.BR libaxl_create ()
+returns the connection record on success
+completion, or
+.I NULL
+on failure.
+.SH ERRORS
+The
+.BR libaxl_create ()
+function can only fail if enough memory
+cannot be allocates for the process,
+which is corresponds to the
+.I ENOMEM
+error number and the
+.I LIBAXL_ERROR_SYSTEM
+libaxl error number.
+.SH NOTES
+None.
+.SH SEE ALSO
+.BR libaxl_connect (3),
+.BR libaxl_parse_display (3),
+.BR libaxl_send_handshake (3),
+.BR libaxl_close (3),
+.BR libaxl_detach (3),
+.BR libaxl_attach (3),
+.BR libaxl_context_create (3)
diff --git a/libaxl_detach.3 b/libaxl_detach.3
new file mode 100644
index 0000000..8d1fb54
--- /dev/null
+++ b/libaxl_detach.3
@@ -0,0 +1,35 @@
+.TH libaxl_detach 3 libaxl
+.SH NAME
+libaxl_detach - Deallocate but do not close connection
+.SH SYNOPSIS
+.nf
+#include <libaxl.h>
+
+int libaxl_detach(LIBAXL_CONNECTION *\fIconn\fP);
+.fi
+.SH DESCRIPTION
+The
+.BR libaxl_detach ()
+function deallocates the connection record
+specified in the
+.I conn
+parameter, which the function will assume is
+.IR non- NULL ,
+but return the file descriptor of the connection
+instead of closing it.
+.SH RETURN VALUE
+The
+.BR libaxl_detach ()
+returns the file descriptor of the connection.
+.SH ERRORS
+The
+.BR libaxl_detach ()
+function cannot fail.
+.SH NOTES
+None.
+.SH SEE ALSO
+.BR libaxl_marshal (3),
+.BR libaxl_fileno (3),
+.BR libaxl_close (3),
+.BR libaxl_detach (3),
+.BR libaxl_attach (3)
diff --git a/libaxl_get_decnet_object.3 b/libaxl_get_decnet_object.3
new file mode 100644
index 0000000..325b44c
--- /dev/null
+++ b/libaxl_get_decnet_object.3
@@ -0,0 +1,56 @@
+.TH libaxl_get_decnet_object 3 libaxl
+.SH NAME
+libaxl_get_decnet_object - Get DECnet object name for a display
+.SH SYNOPSIS
+.nf
+#include <libaxl.h>
+
+#define LIBAXL_DECNET_OBJECT_MAX /* value omitted */
+
+int libaxl_get_decnet_object(char *\fIbuf\fP, size_t \fIsize\fP, int *\fIdisplay\fP);
+.fi
+.SH DESCRIPTION
+The
+.BR libaxl_get_decnet_object ()
+function stores, in the buffer specified
+in the
+.I buf
+parameter, the DECnet object name used
+for the display specified in the
+.I display
+parameter.
+.PP
+The value of the
+.I size
+parameter shall be the size of the buffer;
+.I LIBAXL_DECNET_OBJECT_MAX
+is recommended for static buffers, as
+this is always sufficient.
+If buffer is
+.IR NULL ,
+.I size
+must be 0.
+.SH RETURN VALUE
+The
+.BR libaxl_get_decnet_object ()
+function returns the number of bytes
+the DECnet object name consists of
+(this excludes the terminating NUL byte
+used in C strings, which is also written
+to the buffer if it fits), or -1 on
+failure.
+.SH ERRORS
+The
+.BR libaxl_get_decnet_object ()
+function may fail if
+.TP
+.I EOVERFLOW
+The value of the
+.I size
+argument is greater than {INT_MAX}.
+.BR libaxl_get_decnet_object ()
+function cannot fail.
+.SH NOTES
+None.
+.SH SEE ALSO
+.BR libaxl_get_tcp_port (3)
diff --git a/libaxl_get_tcp_port.3 b/libaxl_get_tcp_port.3
index 4162468..8041f78 100644
--- a/libaxl_get_tcp_port.3
+++ b/libaxl_get_tcp_port.3
@@ -1,6 +1,6 @@
 .TH libaxl_get_tcp_port 3 libaxl
 .SH NAME
-libaxl_get_tcp_port - Get file descriptor of connection
+libaxl_get_tcp_port - Get TCP port number for a display
 .SH SYNOPSIS
 .nf
 #include <libaxl.h>
diff --git a/libaxl_parse_display.3 b/libaxl_parse_display.3
new file mode 100644
index 0000000..f60a7dc
--- /dev/null
+++ b/libaxl_parse_display.3
@@ -0,0 +1,107 @@
+.TH libaxl_parse_display 3 libaxl
+.SH NAME
+libaxl_parse_display - Parse a display name string
+.SH SYNOPSIS
+.nf
+#include <libaxl.h>
+
+int libaxl_parse_display(const char *\fIname\fP, char **\fIhostp\fP, char **\fIprotocolp\fP, int *\fIdisplayp\fP, int *\fIscreenp\fP);
+.fi
+.SH DESCRIPTION
+The
+.BR libaxl_parse_display ()
+function the display name string specified in the
+.I name
+parameter, or the
+.B DISPLAY
+environment variable if
+.I name
+is
+.I NULL
+or the empty string.
+.PP
+The host, or the empty string or
+.I NULL
+(represents localhost) if not specified,
+is stored in
+.IR *hostp ,
+or the path of the socket if the protocol is
+.BR unix .
+.PP
+The protocol name is stored in
+.IR *protocolp ,
+the empty string or
+.I NULL
+can is stored if no protocol is specified
+(and is not
+.BR unix ),
+in which case TCP should be assumes.
+.PP
+The displays number (0 if (but not only if)
+the protocol is
+.BR unix )
+is stored in
+.IR *displayp .
+.PP
+The specified screen, which should be assumes
+as the default screen, is stored in
+.IR *screenp .
+If no screen is specified, -1 is stored in
+.I *screenp
+instead, and 0 should be assumed the default screen.
+.PP
+Remember to call the
+.BR free (3)
+function for
+.I *hostp
+and
+.I *protocolp
+after succesful completion when they result
+is no longer needed.
+.SH RETURN VALUE
+The
+.BR libaxl_parse_display ()
+function returns 0 upon successful
+completion or a negative libaxl
+error number on failure.
+.SH ERRORS
+The
+.BR libaxl_parse_display ()
+function may fail if
+.TP
+.I LIBAXL_ERROR_NO_DISPLAY_SERVER_SPECIFIED
+Both
+.I name
+and the
+.B DISPLAY
+environment variable are
+.IR NULL ,
+unset or the empty string.
+.TP
+.I LIBAXL_ERROR_INVALID_DISPLAY_NAME_NO_DISPLAY_INDEX
+No display number is specified but
+required for the specified protocol.
+.TP
+.I LIBAXL_ERROR_INVALID_DISPLAY_NAME_DISPLAY_INDEX_OUT_OF_DOMAIN
+The display number is too large for
+the specified protocol.
+.TP
+.I LIBAXL_ERROR_INVALID_DISPLAY_NAME_INVALID_SCREEN_INDEX
+The specified screen number is invalid.
+.TP
+.I LIBAXL_ERROR_INVALID_DISPLAY_NAME_SCREEN_INDEX_OUT_OF_DOMAIN
+The specified screen number is too large.
+.TP
+.IR LIBAXL_ERROR_SYSTEM " with " ENOMEM
+Enough memory could not be allocated.
+.SH NOTES
+The
+.BR libaxl_parse_display ()
+function assumes that all arguments except
+.I name
+are
+.RI non- NULL .
+.SH SEE ALSO
+.BR libaxl_create (3),
+.BR libaxl_get_tcp_port (3),
+.BR libaxl_get_decnet_object (3)
diff --git a/libaxl_parse_display.c b/libaxl_parse_display.c
index 1b304e3..037f49b 100644
--- a/libaxl_parse_display.c
+++ b/libaxl_parse_display.c
@@ -14,7 +14,7 @@ libaxl_parse_display(const char *name, char **hostp, char **protocolp, int *disp
 	*hostp     = NULL;
 	*protocolp = NULL;
 	*displayp  = 0;
-	*screenp   = 0;
+	*screenp   = -1;
 
 	/* Get display server name string, if not specified */
 	if (!name || !*name) {