From 0e676861b71b8a17fdf0b968ef32751e2df30444 Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Sun, 10 May 2020 17:26:03 +0200 Subject: Documentation + return -1 screen when not specified MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mattias Andrée --- LIBAXL_DECNET_OBJECT_MAX.3 | 1 + LIBAXL_REQUEST_CIRCULATE_WINDOW.3 | 3 +- LIBAXL_REQUEST_DELETE_PROPERTY.3 | 3 +- LIBAXL_REQUEST_FREE_COLORMAP.3 | 10 ++-- LIBAXL_REQUEST_MAP_WINDOW.3 | 10 ++-- Makefile | 6 +++ TODO | 2 + common.h | 2 +- libaxl/advanced.h | 4 +- libaxl/low-level.h | 14 ++--- libaxl_attach.3 | 33 ++++++++++++ libaxl_context_create.3 | 6 ++- libaxl_create.3 | 46 ++++++++++++++++ libaxl_detach.3 | 35 +++++++++++++ libaxl_get_decnet_object.3 | 56 ++++++++++++++++++++ libaxl_get_tcp_port.3 | 2 +- libaxl_parse_display.3 | 107 ++++++++++++++++++++++++++++++++++++++ libaxl_parse_display.c | 2 +- 18 files changed, 318 insertions(+), 24 deletions(-) create mode 120000 LIBAXL_DECNET_OBJECT_MAX.3 create mode 100644 libaxl_attach.3 create mode 100644 libaxl_create.3 create mode 100644 libaxl_detach.3 create mode 100644 libaxl_get_decnet_object.3 create mode 100644 libaxl_parse_display.3 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 + +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_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 + +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 + +#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 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 + +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) { -- cgit v1.2.3-70-g09d2