From 4be77dd403ec2439a7616fb63c1fe5b4f4df2c8c Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Fri, 22 Apr 2022 21:48:36 +0200 Subject: Documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mattias Andrée --- libaxl/low-level.h | 4 +-- man3/LIBAXL_PROTOCOL_VERSION.3 | 1 + man3/LIBAXL_PROTOCOL_VERSION_MAJOR.3 | 1 + man3/LIBAXL_PROTOCOL_VERSION_MINOR.3 | 1 + man3/libaxl_attach.3 | 1 + man3/libaxl_create.3 | 1 + man3/libaxl_detach.3 | 1 + man3/libaxl_get_decnet_object.3 | 1 + man3/libaxl_get_tcp_port.3 | 1 + man3/libaxl_parse_display.3 | 1 + man3/libaxl_protocol_version.3 | 1 + man3/libaxl_protocol_version_major.3 | 1 + man3/libaxl_protocol_version_minor.3 | 1 + man3/libaxl_receive_handshake.3 | 66 ++++++++++++++++++++++++++++++++++-- man3/libaxl_send_handshake.3 | 1 + 15 files changed, 79 insertions(+), 4 deletions(-) diff --git a/libaxl/low-level.h b/libaxl/low-level.h index 36449a2..30e13cc 100644 --- a/libaxl/low-level.h +++ b/libaxl/low-level.h @@ -47,7 +47,7 @@ LIBAXL_CONNECTION *libaxl_create(int); * 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(makefile; ref libaxl_parse_display, libaxl_send_handshake, libaxl_connect) */ +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; (ADVANCED)) */ /** * Parse a display name string @@ -148,7 +148,7 @@ int libaxl_send_handshake(LIBAXL_CONTEXT *restrict, const char *, size_t, const * LIBAXL_HANDSHAKE_SUCCESS. * @param reasonp Output parameter for the reason the handshake or authorisation * failed; the contents are specific to the authorisation protocol - * in use Will be set to `NULL` unless the function returns + * 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) diff --git a/man3/LIBAXL_PROTOCOL_VERSION.3 b/man3/LIBAXL_PROTOCOL_VERSION.3 index cdc2c94..b2bd11b 100644 --- a/man3/LIBAXL_PROTOCOL_VERSION.3 +++ b/man3/LIBAXL_PROTOCOL_VERSION.3 @@ -1,6 +1,7 @@ .TH LIBAXL_PROTOCOL_VERSION 3 libaxl .SH NAME LIBAXL_PROTOCOL_VERSION - X protocol version +.B (ADVANCED) .SH SYNOPSIS .nf #include diff --git a/man3/LIBAXL_PROTOCOL_VERSION_MAJOR.3 b/man3/LIBAXL_PROTOCOL_VERSION_MAJOR.3 index d8a0500..e6e74bc 100644 --- a/man3/LIBAXL_PROTOCOL_VERSION_MAJOR.3 +++ b/man3/LIBAXL_PROTOCOL_VERSION_MAJOR.3 @@ -1,6 +1,7 @@ .TH LIBAXL_PROTOCOL_VERSION_MAJOR 3 libaxl .SH NAME LIBAXL_PROTOCOL_VERSION_MAJOR - X protocol version, major number +.B (ADVANCED) .SH SYNOPSIS .nf #include diff --git a/man3/LIBAXL_PROTOCOL_VERSION_MINOR.3 b/man3/LIBAXL_PROTOCOL_VERSION_MINOR.3 index 5a2b975..76405e1 100644 --- a/man3/LIBAXL_PROTOCOL_VERSION_MINOR.3 +++ b/man3/LIBAXL_PROTOCOL_VERSION_MINOR.3 @@ -1,6 +1,7 @@ .TH LIBAXL_PROTOCOL_VERSION_MINOR 3 libaxl .SH NAME LIBAXL_PROTOCOL_VERSION_MINOR - X protocol version, minor number +.B (ADVANCED) .SH SYNOPSIS .nf #include diff --git a/man3/libaxl_attach.3 b/man3/libaxl_attach.3 index 0ec4f8f..d4c3c07 100644 --- a/man3/libaxl_attach.3 +++ b/man3/libaxl_attach.3 @@ -1,6 +1,7 @@ .TH libaxl_attach 3 libaxl .SH NAME libaxl_attach - Change file descriptor of a connection +.B (ADVANCED) .SH SYNOPSIS .nf #include diff --git a/man3/libaxl_create.3 b/man3/libaxl_create.3 index d29c32e..f1f7a97 100644 --- a/man3/libaxl_create.3 +++ b/man3/libaxl_create.3 @@ -1,6 +1,7 @@ .TH libaxl_create 3 libaxl .SH NAME libaxl_create - Create connection record +.B (ADVANCED) .SH SYNOPSIS .nf #include diff --git a/man3/libaxl_detach.3 b/man3/libaxl_detach.3 index 39dfefb..4fbf46b 100644 --- a/man3/libaxl_detach.3 +++ b/man3/libaxl_detach.3 @@ -1,6 +1,7 @@ .TH libaxl_detach 3 libaxl .SH NAME libaxl_detach - Deallocate but do not close connection +.B (ADVANCED) .SH SYNOPSIS .nf #include diff --git a/man3/libaxl_get_decnet_object.3 b/man3/libaxl_get_decnet_object.3 index 325b44c..1bade12 100644 --- a/man3/libaxl_get_decnet_object.3 +++ b/man3/libaxl_get_decnet_object.3 @@ -1,6 +1,7 @@ .TH libaxl_get_decnet_object 3 libaxl .SH NAME libaxl_get_decnet_object - Get DECnet object name for a display +.B (ADVANCED) .SH SYNOPSIS .nf #include diff --git a/man3/libaxl_get_tcp_port.3 b/man3/libaxl_get_tcp_port.3 index 8041f78..6d39f0d 100644 --- a/man3/libaxl_get_tcp_port.3 +++ b/man3/libaxl_get_tcp_port.3 @@ -1,6 +1,7 @@ .TH libaxl_get_tcp_port 3 libaxl .SH NAME libaxl_get_tcp_port - Get TCP port number for a display +.B (ADVANCED) .SH SYNOPSIS .nf #include diff --git a/man3/libaxl_parse_display.3 b/man3/libaxl_parse_display.3 index 82f1a67..47b034a 100644 --- a/man3/libaxl_parse_display.3 +++ b/man3/libaxl_parse_display.3 @@ -1,6 +1,7 @@ .TH libaxl_parse_display 3 libaxl .SH NAME libaxl_parse_display - Parse a display name string +.B (ADVANCED) .SH SYNOPSIS .nf #include diff --git a/man3/libaxl_protocol_version.3 b/man3/libaxl_protocol_version.3 index 38f5871..cdfa0fd 100644 --- a/man3/libaxl_protocol_version.3 +++ b/man3/libaxl_protocol_version.3 @@ -1,6 +1,7 @@ .TH libaxl_protocol_version 3 libaxl .SH NAME libaxl_protocol_version - X protocol version +.B (ADVANCED) .SH SYNOPSIS .nf #include diff --git a/man3/libaxl_protocol_version_major.3 b/man3/libaxl_protocol_version_major.3 index d16aa9d..892f122 100644 --- a/man3/libaxl_protocol_version_major.3 +++ b/man3/libaxl_protocol_version_major.3 @@ -1,6 +1,7 @@ .TH libaxl_protocol_version_major 3 libaxl .SH NAME libaxl_protocol_version_major - X protocol version, major number +.B (ADVANCED) .SH SYNOPSIS .nf #include diff --git a/man3/libaxl_protocol_version_minor.3 b/man3/libaxl_protocol_version_minor.3 index 8610c15..f0ba2bd 100644 --- a/man3/libaxl_protocol_version_minor.3 +++ b/man3/libaxl_protocol_version_minor.3 @@ -1,6 +1,7 @@ .TH libaxl_protocol_version_minor 3 libaxl .SH NAME libaxl_protocol_version_minor - X protocol version, minor number +.B (ADVANCED) .SH SYNOPSIS .nf #include diff --git a/man3/libaxl_receive_handshake.3 b/man3/libaxl_receive_handshake.3 index 855cdb7..a64167f 100644 --- a/man3/libaxl_receive_handshake.3 +++ b/man3/libaxl_receive_handshake.3 @@ -1,6 +1,7 @@ .TH libaxl_receive_handshake 3 libaxl .SH NAME libaxl_receive_handshake - Finish connection handshake +.B (ADVANCED) .SH SYNOPSIS .nf #include @@ -25,7 +26,68 @@ The value of the parameter shall be the thread's state for the connection to the display server. .PP -TODO majorp, minorp, reasonp +If the +.I majorp +parameter is set to a +.RI non- NULL +pointer and the +.BR libaxl_receive_handshake () +function returns +.B LIBAXL_HANDSHAKE_SUCCESS +or +.BR LIBAXL_HANDSHAKE_FAILED , +.I *majorp +will be set to the major version number for a +version of the X protocol that the display server +supports, which is not necessarily the version +that the library uses. +.PP +If the +.I minorp +parameter is set to a +.RI non- NULL +pointer and the +.BR libaxl_receive_handshake () +function returns +.B LIBAXL_HANDSHAKE_SUCCESS +or +.BR LIBAXL_HANDSHAKE_FAILED , +.I *minorp +will be set to the minor version number for the +verison for which the major version number was +returned in +.I *majorp +(or if +.I majorp +is +.IR NULL : +would have been returned). +.PP +If the +.I reasonp +parameter is set to a +.RI non- NULL +pointer and the +.BR libaxl_receive_handshake () +function returns +.B LIBAXL_HANDSHAKE_FAILED +or +.BR LIBAXL_HANDSHAKE_AUTHENTICATE , +.I *reasonp +will be set to a dynamically allocated string +(which the caller must deallocate with the +.BR free (3) +function) providing an authorisation +protocol-specific reason which the handshake +failed. If The +.BR libaxl_receive_handshake () +function returns any other value, and the +.I reasonp +paramater is set to a +.RI non- NULL , +.I *reasonp +will be set to +.IR NULL . .PP Flags to used in the fourth argument when the .BR libaxl_receive_handshake () @@ -40,7 +102,7 @@ The function return .B LIBAXL_HANDSHAKE_SUCCESS upon successful completion with successful handshake -(beaware, this value is not 0), +(beware, this value is not 0!), .B LIBAXL_HANDSHAKE_FAILURE upon successful completion with handshake failure, .B LIBAXL_HANDSHAKE_AUTHENTICATE diff --git a/man3/libaxl_send_handshake.3 b/man3/libaxl_send_handshake.3 index 71f58fd..6068a0f 100644 --- a/man3/libaxl_send_handshake.3 +++ b/man3/libaxl_send_handshake.3 @@ -1,6 +1,7 @@ .TH libaxl_send_handshake 3 libaxl .SH NAME libaxl_send_handshake - Initiate connection handshake +.B (ADVANCED) .SH SYNOPSIS .nf #include -- cgit v1.2.3-70-g09d2