diff options
| -rw-r--r-- | LICENSE | 2 | ||||
| -rw-r--r-- | Makefile | 12 | ||||
| -rw-r--r-- | libaxl.h | 28 | ||||
| -rw-r--r-- | libaxl/low-level.h | 46 | ||||
| -rw-r--r-- | libaxl/replies.h | 4 | ||||
| -rw-r--r-- | linux.mk | 2 | ||||
| -rw-r--r-- | macos.mk | 4 | ||||
| -rw-r--r-- | man3/LIBAXL_REQUEST_GET_POINTER_CONTROL.3 | 62 | ||||
| -rw-r--r-- | man3/libaxl_parse_display.3 | 3 | ||||
| -rw-r--r-- | man3/libaxl_receive_handshake.3 | 3 | ||||
| -rw-r--r-- | man3/libaxl_send_handshake.3 | 3 |
11 files changed, 135 insertions, 34 deletions
@@ -1,6 +1,6 @@ ISC License -© 2019, 2020 Mattias Andrée <maandree@kth.se> +© 2019, 2020, 2021, 2022 Mattias Andrée <maandree@kth.se> Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above @@ -478,8 +478,6 @@ MAN3 =\ man3/struct_libaxl_request_warp_pointer.3\ man3/union_libaxl_error.3 -MAN = $(MAN0) $(MAN3) $(MAN7) - LOBJ = $(OBJ:.o=.lo) all: libaxl.a libaxl.$(LIBEXT) $(LIB_SUBHDR_GEN) @@ -508,8 +506,9 @@ libaxl/requests-structs.h: libaxl/requests.h sed -n 's/^struct libaxl_request_\([^ \t]*\).*$$/\tstruct libaxl_request_\1 \1;/p' < libaxl/requests.h > $@ libaxl.a: $(OBJ) - $(AR) rc $@ $? - $(AR) s $@ + @rm -f -- $@ + $(AR) rc $@ $(OBJ) + $(AR) ts $@ > /dev/null libaxl.$(LIBEXT): $(LOBJ) $(CC) $(LIBFLAGS) -o $@ $(LOBJ) $(LDFLAGS) @@ -524,6 +523,7 @@ install: libaxl.a libaxl.$(LIBEXT) cp -- $(LIB_SUBHDR) "$(DESTDIR)$(PREFIX)/include/libaxl" cp -- libaxl.a "$(DESTDIR)$(PREFIX)/lib" cp -- libaxl.$(LIBEXT) "$(DESTDIR)$(PREFIX)/lib/libaxl.$(LIBMINOREXT)" + $(FIX_INSTALL_NAME) "$(DESTDIR)$(PREFIX)/lib/libaxl.$(LIBMINOREXT)" ln -sf -- libaxl.$(LIBMINOREXT) "$(DESTDIR)$(PREFIX)/lib/libaxl.$(LIBMAJOREXT)" ln -sf -- libaxl.$(LIBMINOREXT) "$(DESTDIR)$(PREFIX)/lib/libaxl.$(LIBEXT)" # cp -P -- $(MAN0) "$(DESTDIR)$(MANPREFIX)/man0" @@ -537,7 +537,9 @@ uninstall: -rm -f -- "$(DESTDIR)$(PREFIX)/lib/libaxl.$(LIBMINOREXT)" -rm -f -- "$(DESTDIR)$(PREFIX)/lib/libaxl.$(LIBMAJOREXT)" -rm -f -- "$(DESTDIR)$(PREFIX)/lib/libaxl.$(LIBEXT)" -# -cd -- "$(DESTDIR)$(MANPREFIX)/" && rm -f -- $(MAN) +# -cd -- "$(DESTDIR)$(MANPREFIX)/" && rm -f -- $(MAN0) +# -cd -- "$(DESTDIR)$(MANPREFIX)/" && rm -f -- $(MAN3) +# -cd -- "$(DESTDIR)$(MANPREFIX)/" && rm -f -- $(MAN7) clean: -rm -f -- *.o *.lo *.a *.su *.$(LIBEXT) libaxl/*-structs.h @@ -53,7 +53,7 @@ typedef struct libaxl_context LIBAXL_CONTEXT; /* TODO man */ #define LIBAXL_ERROR_USER_DOES_NOT_EXIST -15 #define LIBAXL_ERROR_USER_DOES_NOT_HAVE_A_HOME -16 -union libaxl_input { /* TODO doc, man (also LIBAXL_SYNTHETIC_EVENT_BIT) */ +union libaxl_input { /* TODO doc, man(makefile) (also LIBAXL_SYNTHETIC_EVENT_BIT(~makefile)) */ uint8_t type; union libaxl_error error; /* if .type = LIBAXL_ERROR */ union libaxl_reply reply; /* if .type = LIBAXL_REPLY */ @@ -66,8 +66,18 @@ union libaxl_input { /* TODO doc, man (also LIBAXL_SYNTHETIC_EVENT_BIT) */ */ #define LIBAXL_SYNTHETIC_EVENT_BIT 0x80U +/** + * Connect to a display server and preform the connection handshake + * + * @param display The display name string, $DISPLAY will be used if `NULL` or empty; see the + * documentation for the libaxl_parse_display() for more details + * @param reasonp Output parameter for the reason the handshake or authorisation failed; + * The contents of the reason string are specific to the used authorisation + * protocol. Will be set to `NULL` if not applicable. + * @return the connection object, will be set to `NULL` on error + */ _LIBAXL_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__))) -LIBAXL_CONNECTION *libaxl_connect(const char *restrict, char **restrict); /* TODO man doc */ +LIBAXL_CONNECTION *libaxl_connect(const char *restrict, char **restrict); /* TODO man(makefile) */ /** * Deallocation and close a connection @@ -108,7 +118,7 @@ int libaxl_fileno(LIBAXL_CONNECTION *); * is always LIBAXL_ERROR_SYSTEM */ _LIBAXL_GCC_ONLY(__attribute__((__nonnull__, __warn_unused_result__, __const__))) -const struct libaxl_display_info *libaxl_info(LIBAXL_CONNECTION *, int); /* TODO man */ +const struct libaxl_display_info *libaxl_info(LIBAXL_CONNECTION *, int); /* TODO man(makefile) */ /** * Get the next element in a `struct libaxl_depth *` @@ -131,7 +141,7 @@ const struct libaxl_display_info *libaxl_info(LIBAXL_CONNECTION *, int); /* TODO */ _LIBAXL_GCC_ONLY(__attribute__((__warn_unused_result__, __pure__, __nonnull__, __returns_nonnull__))) inline const struct libaxl_depth * -libaxl_next_depth(const struct libaxl_depth *depth) /* TODO man */ +libaxl_next_depth(const struct libaxl_depth *depth) /* TODO man(makefile) */ { return (const struct libaxl_depth *)(uintptr_t)&depth->visuals[depth->number_of_visuals]; } @@ -156,7 +166,7 @@ libaxl_next_depth(const struct libaxl_depth *depth) /* TODO man */ */ _LIBAXL_GCC_ONLY(__attribute__((__warn_unused_result__, __pure__, __nonnull__, __returns_nonnull__))) inline const struct libaxl_screen * -libaxl_next_screen(const struct libaxl_screen *screen) /* TODO man */ +libaxl_next_screen(const struct libaxl_screen *screen) /* TODO man(makefile) */ { uint8_t n = screen->number_of_allowed_depths; const struct libaxl_depth *depth = screen->allowed_depths; @@ -170,7 +180,7 @@ libaxl_next_screen(const struct libaxl_screen *screen) /* TODO man */ * the display server * * @param conn The connection to the display server - * @return The context, NULL on failure (can only be out of memory) + * @return The context, `NULL` on failure (can only be out of memory) */ _LIBAXL_GCC_ONLY(__attribute__((__nonnull__, __malloc__, __warn_unused_result__))) LIBAXL_CONTEXT *libaxl_context_create(LIBAXL_CONNECTION *); @@ -230,7 +240,7 @@ int libaxl_deallocate_id(LIBAXL_CONTEXT *, libaxl_id_t); * thread. */ _LIBAXL_GCC_ONLY(__attribute__((__nonnull__(1)))) -int libaxl_send_request(LIBAXL_CONTEXT *restrict, union libaxl_request_const_ptr, int, uint16_t *restrict); /* TODO man */ +int libaxl_send_request(LIBAXL_CONTEXT *restrict, union libaxl_request_const_ptr, int, uint16_t *restrict); /* TODO man(makefile) */ /** * Send any pending messages to the display server @@ -246,7 +256,7 @@ int libaxl_send_request(LIBAXL_CONTEXT *restrict, union libaxl_request_const_ptr * is nothing more to flush. */ _LIBAXL_GCC_ONLY(__attribute__((__nonnull__))) -int libaxl_flush(LIBAXL_CONNECTION *restrict, int); /* TODO man */ +int libaxl_flush(LIBAXL_CONNECTION *restrict, int); /* TODO man(makefile) */ /** * Receive the next pending message from the display server @@ -272,7 +282,7 @@ int libaxl_flush(LIBAXL_CONNECTION *restrict, int); /* TODO man */ * is used */ _LIBAXL_GCC_ONLY(__attribute__((__nonnull__))) -int libaxl_receive(LIBAXL_CONTEXT *restrict, union libaxl_input *restrict, int); /* TODO man */ +int libaxl_receive(LIBAXL_CONTEXT *restrict, union libaxl_input *restrict, int); /* TODO man(makefile) */ #undef LIBAXL_H #define LIBAXL_H 1 diff --git a/libaxl/low-level.h b/libaxl/low-level.h index 70b87a7..36449a2 100644 --- a/libaxl/low-level.h +++ b/libaxl/low-level.h @@ -4,9 +4,9 @@ # error Do not include <libaxl/low-level.h> directly, include <libaxl.h> instead. #endif -#define LIBAXL_HANDSHAKE_FAILED 0 -#define LIBAXL_HANDSHAKE_SUCCESS 1 -#define LIBAXL_HANDSHAKE_AUTHENTICATE 2 +#define LIBAXL_HANDSHAKE_FAILED 0 /* Handshake failed */ +#define LIBAXL_HANDSHAKE_SUCCESS 1 /* Handshake succeeded */ +#define LIBAXL_HANDSHAKE_AUTHENTICATE 2 /* Further authnetication is required */ /* * The largest possible return of the libaxl_get_decnet_object() @@ -27,8 +27,27 @@ _LIBAXL_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__))) LIBAXL_CONNECTION *libaxl_create(int); +/** + * Connect to a display server, but do not initiate the handshake + * + * The libaxl_send_handshake() function can be used to initiate + * the handshake + * + * @param host The host of or (if the protocol is "unix") path to the display + * @param protocol The network protocol used to access the display + * @param display The display's index (0 if the protocol is "unix") + * @param screen The screen's index (-1 of not specified) + * @return The connection object, `NULL` on error + * + * The parameters host, protocol, display, and screen can be + * parsed from e.g. the DISPLAY environment variable using + * the libaxl_parse_display() function + * + * On failure, no error is returned, but the error + * is always LIBAXL_ERROR_SYSTEM + */ _LIBAXL_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__))) -LIBAXL_CONNECTION *libaxl_connect_without_handshake(const char *host, const char *protocol, int display, int screen); /* TODO man doc */ +LIBAXL_CONNECTION *libaxl_connect_without_handshake(const char *host, const char *protocol, int display, int screen); /* TODO man(makefile; ref libaxl_parse_display, libaxl_send_handshake, libaxl_connect) */ /** * Parse a display name string @@ -41,7 +60,7 @@ LIBAXL_CONNECTION *libaxl_connect_without_handshake(const char *host, const char * * <path>[.<screen>] * - * @param name The display name string, $DISPLAY will be used if NULL or empty + * @param name The display name string, $DISPLAY will be used if `NULL` or empty * @param hostp Output parameter for the host of or (if the protocol is "unix") path * to the display, remember to free after successful completion * @param protocolp Output parameter for the network protocol used to access the display, @@ -71,7 +90,7 @@ inline uint16_t libaxl_get_tcp_port(int display) * @param buf Buffer that the object name shall be written to, it is recommended * 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 + * of this function (for the same last argument but with `NULL` and 0 * as the first two arguments) plus 1 * @param size The size of the buffer in the `buf` argument * @param display The display's number @@ -96,9 +115,9 @@ int libaxl_get_decnet_object(char *, size_t, int); * @param ctx The thread's context for the connection to the display to send the handshake over * @param auth_name The protocol name of the authorisation the client expects the server to use; * valid authorisation mechanisms are not part of the core X protocol - * @param auth_name_len The length of `auth_name`, 0 if `auth_name` is NULL + * @param auth_name_len The length of `auth_name`, 0 if `auth_name` is `NULL` * @param auth_data The authorisation data, which is specific to the choosen authorisation mechanism - * @param auth_data_len The length of `auth_data`, 0 if `auth_data` is NULL + * @param auth_data_len The length of `auth_data`, 0 if `auth_data` is `NULL` * @param flags Flags to use for the 4th parameter when calling send(3) * @return 0 on success, a negative libaxl error code on failure * @@ -107,7 +126,7 @@ int libaxl_get_decnet_object(char *, size_t, int); * sent) and pending to be sent by calling libaxl_flush(). */ _LIBAXL_GCC_ONLY(__attribute__((__nonnull__(1)))) -int libaxl_send_handshake(LIBAXL_CONTEXT *restrict, const char *, size_t, const char *, size_t, int); /* TODO man */ +int libaxl_send_handshake(LIBAXL_CONTEXT *restrict, const char *, size_t, const char *, size_t, int); /** * Receive the server's part of the handshake, this function @@ -128,18 +147,19 @@ int libaxl_send_handshake(LIBAXL_CONTEXT *restrict, const char *, size_t, const * be set if the function returns LIBAXL_HANDSHAKE_FAILED or * LIBAXL_HANDSHAKE_SUCCESS. * @param reasonp Output parameter for the reason the handshake or authorisation - * failed. Will be set to NULL unless the function returns + * failed; the contents are specific to the authorisation protocol + * in use Will be set to `NULL` unless the function returns * LIBAXL_HANDSHAKE_FAILED or LIBAXL_HANDSHAKE_AUTHENTICATE. * Remember to free after successful completion (non-negative return) * @param flags Flags to use for the 4th parameter when calling recv(3) * @return LIBAXL_HANDSHAKE_SUCCESS (NB! this value is not 0) on * success, LIBAXL_HANDSHAKE_FAILED on handshake failure, - * LIBAXL_HANDSHAKE_AUTHENTICATE 2, or a negative libaxl error - * code on failure + * LIBAXL_HANDSHAKE_AUTHENTICATE if further authentication is + * required, or a negative libaxl error code on failure * * Behaviour is unspecified if SO_PEEK_OFF is active on the * connection to the display server or if the MSG_PEEK flag * is used */ _LIBAXL_GCC_ONLY(__attribute__((__nonnull__(1)))) -int libaxl_receive_handshake(LIBAXL_CONTEXT *restrict, int *restrict, int *restrict, char **restrict, int); /* TODO man */ +int libaxl_receive_handshake(LIBAXL_CONTEXT *restrict, int *restrict, int *restrict, char **restrict, int); diff --git a/libaxl/replies.h b/libaxl/replies.h index d3865d7..8a2e163 100644 --- a/libaxl/replies.h +++ b/libaxl/replies.h @@ -4,7 +4,7 @@ # error Do not include <libaxl/replies.h> directly, include <libaxl.h> instead. #endif -#define LIBAXL_REPLY 1 /* TODO man */ +#define LIBAXL_REPLY 1 /* TODO man(makefile) */ struct libaxl_reply_get_window_attributes { uint8_t __one; @@ -483,7 +483,7 @@ struct libaxl_reply_get_modifier_mapping { libaxl_keycode_t *keycodes; }; -union libaxl_reply { +union libaxl_reply { /* TODO man(makefile) */ struct { uint8_t __one; uint8_t __data; @@ -3,3 +3,5 @@ LIBFLAGS = -shared -Wl,-soname,libaxl.$(LIBEXT).$(LIB_MAJOR) LIBMAJOREXT = $(LIBEXT).$(LIB_MAJOR) LIBMINOREXT = $(LIBEXT).$(LIB_VERSION) + +FIX_INSTALL_NAME = : @@ -1,5 +1,7 @@ LIBEXT = dylib -LIBFLAGS = -dynamiclib +LIBFLAGS = -dynamiclib -Wl,-compatibility_version,$(LIB_MAJOR) -Wl,-current_version,$(LIB_VERSION) LIBMAJOREXT = $(LIB_MAJOR).$(LIBEXT) LIBMINOREXT = $(LIB_VERSION).$(LIBEXT) + +FIX_INSTALL_NAME = install_name_tool -id "$(PREFIX)/lib/libaxl.$(LIBMAJOREXT)" diff --git a/man3/LIBAXL_REQUEST_GET_POINTER_CONTROL.3 b/man3/LIBAXL_REQUEST_GET_POINTER_CONTROL.3 new file mode 100644 index 0000000..9cc6f37 --- /dev/null +++ b/man3/LIBAXL_REQUEST_GET_POINTER_CONTROL.3 @@ -0,0 +1,62 @@ +.TH LIBAXL_REQUEST_GET_POINTER_CONTROL 3 libaxl +.SH NAME +LIBAXL_REQUEST_GET_POINTER_CONTROL - Get current acceleration and threshold for the pointer +.SH SYNOPSIS +.nf +#include <libaxl.h> + +#define LIBAXL_REQUEST_GET_POINTER_CONTROL 106 +struct libaxl_request_get_pointer_control { + uint8_t \fIopcode\fP; + uint8_t \fI__pad\fP; + uint16_t \fI_request_length\fP; +}; +.fi +.SH DESCRIPTION +The display server shall return the current +acceleration and threshold for the pointer. +.PP +The value of the +.I opcode +field shall be +.I LIBAXL_REQUEST_GET_POINTER_CONTROL +to signify that the request is of the +request described in this document. +.PP +Other fields are filled in automatically by the +.BR libaxl_send_request (3) +function. +.SH ERRORS +None. +.SH REPLIES +.nf +struct libaxl_reply_get_pointer_control { + uint8_t \fI__one\fP; + uint8_t \fI__pad\fP; + uint16_t \fIsequence_number\fP; + uint32_t \fI_reply_length\fP; + uint16_t \fIacceleration_numerator\fP; + uint16_t \fIacceleration_denominator\fP; + uint16_t \fIthreshold\fP; + uint8_t \fI__unused\fP[18]; +}; +.fi +.PP +.PP +The display server shall, unless it returns an +error, return one +.B "struct libaxl_reply_get_pointer_control" +with the +.I acceleration_numerator +and +.I acceleration_denominator +fields set such that +.I ((double)acceleration_numerator/acceleration_denominator) +is the value of the current acceleration for the pointer, +and the +.I threshold +field set to the current threshold for the pointer. +.SH +.BR libaxl_send_request (3), +.BR libaxl_receive (3), +.BR LIBAXL_REQUEST_CHANGE_POINTER_CONTROL (3) diff --git a/man3/libaxl_parse_display.3 b/man3/libaxl_parse_display.3 index f60a7dc..82f1a67 100644 --- a/man3/libaxl_parse_display.3 +++ b/man3/libaxl_parse_display.3 @@ -104,4 +104,5 @@ are .SH SEE ALSO .BR libaxl_create (3), .BR libaxl_get_tcp_port (3), -.BR libaxl_get_decnet_object (3) +.BR libaxl_get_decnet_object (3), +.BR libaxl_connect_without_handshake (3) diff --git a/man3/libaxl_receive_handshake.3 b/man3/libaxl_receive_handshake.3 index e0e2e0a..855cdb7 100644 --- a/man3/libaxl_receive_handshake.3 +++ b/man3/libaxl_receive_handshake.3 @@ -64,4 +64,5 @@ flag is used. .SH SEE ALSO .BR libaxl_connect (3), .BR libaxl_send_handshake (3), -.BR libaxl_send (3) +.BR libaxl_send (3), +.BR libaxl_connect_without_handshake (3) diff --git a/man3/libaxl_send_handshake.3 b/man3/libaxl_send_handshake.3 index c4b91ab..71f58fd 100644 --- a/man3/libaxl_send_handshake.3 +++ b/man3/libaxl_send_handshake.3 @@ -81,4 +81,5 @@ the core X protocol. .BR libaxl_connect (3), .BR libaxl_create (3), .BR libaxl_parse_display (3), -.BR libaxl_receive_handshake (3) +.BR libaxl_receive_handshake (3), +.BR libaxl_connect_without_handshake (3) |