diff options
| -rw-r--r-- | Makefile | 4 | ||||
| -rw-r--r-- | interactive-test.c | 6 | ||||
| -rw-r--r-- | libterminput.7 | 17 | ||||
| -rw-r--r-- | libterminput.h | 40 | ||||
| l--------- | libterminput_destroy.3 | 1 | ||||
| -rw-r--r-- | libterminput_destroy.c | 9 | ||||
| -rw-r--r-- | libterminput_init.3 | 110 | ||||
| -rw-r--r-- | libterminput_init.c | 14 | ||||
| -rw-r--r-- | libterminput_read.3 | 7 | ||||
| -rw-r--r-- | libterminput_set_flags.3 | 2 |
10 files changed, 205 insertions, 5 deletions
@@ -23,7 +23,9 @@ MAN3 =\ libterminput_marshal_input.3\ libterminput_marshal_state.3\ libterminput_unmarshal_input.3\ - libterminput_unmarshal_state.3 + libterminput_unmarshal_state.3\ + libterminput_init.3\ + libterminput_destroy.3 OBJ =\ $(MAN3:.3=.o)\ diff --git a/interactive-test.c b/interactive-test.c index 687e391..00b5776 100644 --- a/interactive-test.c +++ b/interactive-test.c @@ -32,6 +32,10 @@ main(void) struct sigaction sa; memset(&ctx, 0, sizeof(ctx)); + if (libterminput_init(&ctx, STDIN_FILENO)) { + perror("libterminput_init STDIN_FILENO"); + return 1; + } memset(&sa, 0, sizeof(sa)); /* importantly, SA_RESTART is cleared from sa.sa_flags */ sa.sa_handler = &sigint_handler; @@ -243,5 +247,7 @@ again: if (!(flags & O_NONBLOCK)) fcntl(STDIN_FILENO, F_SETFL, flags); tcsetattr(STDERR_FILENO, TCSAFLUSH, &saved_stty); + + libterminput_destroy(&ctx); return -r && !interrupted; } diff --git a/libterminput.7 b/libterminput.7 index d56a6d3..287b71b 100644 --- a/libterminput.7 +++ b/libterminput.7 @@ -10,6 +10,12 @@ does not use terminfo, but recognises common sequences. .PP libterminput provides the following functions: .TP +.BR libterminput_init (3) +Configure library for terminal quirks. +.TP +.BR libterminput_destroy (3) +Deallocate library configuration resources. +.TP .BR libterminput_read (3) Read and parse input from the terminal. .TP @@ -21,8 +27,17 @@ Add input parsing flags. .TP .BR libterminput_clear_flags (3) Remove input parsing flags. +.TP +.BR libterminput_marshal_state "(3), " libterminput_marshal_input (3) +Marshal library state. +.TP +.BR libterminput_unmarshal_state "(3), " libterminput_unmarshal_input (3) +Unmarshal library state. .SH SEE ALSO +.BR libterminput_init (3), .BR libterminput_is_ready (3), +.BR libterminput_marshal_state (3), .BR libterminput_read (3), -.BR libterminput_set_flags (3) +.BR libterminput_set_flags (3), +.BR libterminput_unmarshal_state (3) diff --git a/libterminput.h b/libterminput.h index ce82ad0..5cd634d 100644 --- a/libterminput.h +++ b/libterminput.h @@ -692,6 +692,46 @@ struct libterminput_unmarshaller { /** + * Initialises the parser + * + * Calling this function is optional + * + * Before calling this function, it is important to call + * `memset(ctx, 0, sizeof(*ctx))` so that `ctx` is properly + * marked as fully uninitialised (this is needed because + * the execution of the function is resumed by calling it + * again after EINTR or EAGAIN failure) + * + * In the current version, this function doesn't do anything, + * however future versions (or other implementations) may + * read to and write from the terminal, read the process's + * environment variables, or read from the filesystem in + * order to detect the particular quirks of the terminal + * + * @param ctx Parser state + * @param fd The file descriptor to the terminal + * @return 0 on success, -1 on failure + * + * It is unspecified which errors will cause this function + * to fail, however it should avoid failing for any other + * reason than EINTR and EAGAIN + * + * @since 1.1 + */ +int libterminput_init(struct libterminput_state *ctx, int fd); + +/** + * Deallocate any resources allocated by `libterminput_init` + * + * `ctx` is no longer usable after this function returns + * + * @param ctx Parser state + * + * @since 1.1 + */ +void libterminput_destroy(struct libterminput_state *ctx); + +/** * Get input from the terminal * * @param fd The file descriptor to the terminal diff --git a/libterminput_destroy.3 b/libterminput_destroy.3 new file mode 120000 index 0000000..81850ed --- /dev/null +++ b/libterminput_destroy.3 @@ -0,0 +1 @@ +libterminput_init.3
\ No newline at end of file diff --git a/libterminput_destroy.c b/libterminput_destroy.c new file mode 100644 index 0000000..628032f --- /dev/null +++ b/libterminput_destroy.c @@ -0,0 +1,9 @@ +/* See LICENSE file for copyright and license details. */ +#include "common.h" + + +void +libterminput_destroy(struct libterminput_state *ctx) +{ + (void) ctx; +} diff --git a/libterminput_init.3 b/libterminput_init.3 new file mode 100644 index 0000000..fa739a0 --- /dev/null +++ b/libterminput_init.3 @@ -0,0 +1,110 @@ +.TH LIBTERMINPUT_INIT 3 LIBTERMINPUT +.SH NAME +libterminput_init \- Configure library for terminal quirks +.br +libterminput_destory \- Deallocate library configuration resources + +.SH SYNOPSIS +.nf +#include <libterminput.h> + +int libterminput_init(struct libterminput_state *\fIctx\fP, int \fIfd\fP); +void libterminput_destroy(struct libterminput_state *\fIctx\fP); +.fi +.PP +Link with +.IR \-lterminput . + +.SH DESCRIPTION +The current version of the +.BR libterminput_init () +function doesn't do anything. However, future versions +may communicate with the terminal, inspect the process's +environment variables, and read the filesystem to determine +the quirks of the terminal. +.PP +Before calling this, +.I *ctx +must be initialised by running +.IR "memset(ctx, 0, sizeof(*ctx))" . +.PP +.I fd +shall be a file descriptor to the terminal with both +read and write access. +.PP +Calling the +.BR libterminput_init () +function will always be optional. However, if the +function has failed the function must be called again +(until successful completion), or +.I *ctx +must be destroyed using +.BR libterminput_destroy () +and reset with +.BR memset (3). +.PP +The +.BR libterminput_destroy () +function deallocates resources in +.I *ctx +allocated by the +.BR libterminput_init () +function. + +.SH RETURN VALUE +The +.BR libterminput_init () +function returns 0 upon successful completion. +On failure, it returns +.B -1 +and sets +.I errno +to indicate the error. +.PP +The +.BR libterminput_destroy () +function does not have a return value. + +.SH ERRORS +The +.BR libterminput_init () +function may fail for any reason, although it should +avoid failing for any reason other than: +.TP +.B EINTR +Default. +.TP +.B AGAIN +Default. +.PP +The +.BR libterminput_destroy () +function cannot fail. + +.SH EXAMPLES +None. + +.SH APPLICATION USAGE +None. + +.SH RATIONALE +None. + +.SH FUTURE DIRECTIONS +None. + +.SH HISTORY +The +.BR libterminput_init () +and +.BR libterminput_destroy () +functions were added in version 1.1 of libterminput. + +.SH NOTES +None. + +.SH BUGS +None. + +.SH SEE ALSO +.BR libterminput_read (3) diff --git a/libterminput_init.c b/libterminput_init.c new file mode 100644 index 0000000..0e65d40 --- /dev/null +++ b/libterminput_init.c @@ -0,0 +1,14 @@ +/* See LICENSE file for copyright and license details. */ +#include "common.h" + + +#if defined(__GNUC__) +__attribute__((__const__)) +#endif +int +libterminput_init(struct libterminput_state *ctx, int fd) +{ + (void) ctx; + (void) fd; + return -1; +} diff --git a/libterminput_read.3 b/libterminput_read.3 index 742c95a..7a30072 100644 --- a/libterminput_read.3 +++ b/libterminput_read.3 @@ -158,7 +158,9 @@ returns the result in the .I ctx must have been zero-initialised, e.g. with .BR memset (3) -function. +function, and optionally with +.BR libterminput_init (3) +afterwards. .PP .I input shall be the same pointer every time the @@ -439,7 +441,7 @@ function returns .B -1 and set .I errno -it indicate the error. +to indicate the error. .SH ERRORS The @@ -467,6 +469,7 @@ None. None. .SH SEE ALSO +.BR libterminput_init (3), .BR libterminput_is_ready (3), .BR libterminput_set_flags (3), .BR libterminput_marshal_state (3) diff --git a/libterminput_set_flags.3 b/libterminput_set_flags.3 index 30301bc..fd1df68 100644 --- a/libterminput_set_flags.3 +++ b/libterminput_set_flags.3 @@ -117,7 +117,7 @@ functions return .B -1 and set .I errno -it indicate the error. +to indicate the error. .SH ERRORS Current versions of the |