Also document termkey_advisereadable()

3 files changed, 33 insertions, 1 deletions

diff --git a/termkey_advisereadable.3 b/termkey_advisereadable.3
new file mode 100644
index 0000000..da40eea
--- /dev/null
+++ b/termkey_advisereadable.3
@@ -0,0 +1,30 @@
+.TH TERMKEY_ADVISEREADABLE 3
+.SH NAME
+termkey_advisereadable \- read more bytes from the underlying terminal
+.SH SYNOPSIS
+.nf
+.B #include <termkey.h>
+.sp
+.BI "termkey_result termkey_advisereadable(termkey_t *" tk );
+.fi
+.sp
+Link with \fI-ltermkey\fP.
+.SH DESCRIPTION
+\fBtermkey_advisereadable\fP informs the instance that new input may be available on the underlying file descriptor and so it should call \fBread\fP(2) to obtain it. If at least one more byte was read it will return \fBTERMKEY_RES_AGAIN\fP to indicate it may be useful to call \fBtermkey_getkey\fP(3) again. If no more input was read then \fBTERMKEY_RES_NONE\fP is returned.
+.PP
+This function, along with \fBtermkey_getkey\fP(3) make it possible to use the termkey instance in an asynchronous program.
+.PP
+For synchronous usage, \fBtermkey_waitkey\fP(3) performs the input blocking task.
+.SH "RETURN VALUE"
+\fBtermkey_advisereadable\fP() returns one of the following constants:
+.TP
+.B TERMKEY_RES_AGAIN
+At least one byte was read.
+.TP
+.B TERMKEY_RES_NONE
+No nore bytes were read.
+.SH "SEE ALSO"
+.BR termkey_new (3),
+.BR termkey_getkey (3),
+.BR termkey_waitkey (3),
+.BR termkey_setwaittime (3)
diff --git a/termkey_getkey.3 b/termkey_getkey.3
index 064dda7..f77caa0 100644
--- a/termkey_getkey.3
+++ b/termkey_getkey.3
@@ -16,7 +16,7 @@ Link with \fI-ltermkey\fP.
 .PP
 \fBtermkey_getkey_force\fP is similar to \fBtermkey_getkey\fP but will not return \fBTERMKEY_RES_AGAIN\fP if a partial match is found. Instead, it will force an interpretation of the bytes, even if this means interpreting the start of an Escape-prefixed multi-byte sequence as a literal "Escape" key followed by normal letters.
 .PP
-Neither of these functions will block or perform any IO operations on the underlying filehandle. For a blocking wait, see \fBtermkey_waitkey\fP.
+Neither of these functions will block or perform any IO operations on the underlying filehandle. To use the instance in an asynchronous program, see \fBtermkey_advisereadable\fP(3). For a blocking call suitable for use in a synchronous program, use \fBtermkey_waitkey\fP(3) instead of \fBtermkey_getkey\fP().
 .PP
 The \fItermkey_key\fP structure is defined as follows:
 .PP
@@ -67,6 +67,7 @@ No key events are ready and the terminal has been closed, so no more will arrive
 No key event is ready yet, but a partial one has been found. This is only returned by \fBtermkey_getkey\fP(). To obtain the partial result even if it never completes, use \fBtermkey_getkey_force\fP().
 .SH "SEE ALSO"
 .BR termkey_new (3),
+.BR termkey_advisereadable (3),
 .BR termkey_waitkey (3),
 .BR termkey_setwaittime (3),
 .BR termkey_get_keyname (3),
diff --git a/termkey_new.3 b/termkey_new.3
index 549be14..7aaed18 100644
--- a/termkey_new.3
+++ b/termkey_new.3
@@ -40,4 +40,5 @@ device, do not call the \fBtcsetattr\fP() \fBtermios\fP function on it to set it
 If successful, \fBtermkey_new\fP() returns a pointer to the new instance. On failure, \fBNULL\fP is returned. \fBtermkey_free\fP() returns no value.
 .SH "SEE ALSO"
 .BR termkey_waitkey (3),
+.BR termkey_advisereadable (3),
 .BR termkey_getkey (3)