Added termkey_push_bytes(), a new API for providing input bytes

4 files changed, 28 insertions, 3 deletions

diff --git a/man/termkey_advisereadable.3 b/man/termkey_advisereadable.3
index 06e0467..3c63fdd 100644
--- a/man/termkey_advisereadable.3
+++ b/man/termkey_advisereadable.3
@@ -12,7 +12,7 @@ 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. If there was no buffer space remaining, then \fBTERMKEY_RES_ERROR\fP is returned with \fIerrno\fP set to \fBENOMEM\fP.
 .PP
-This function, along with \fBtermkey_getkey\fP(3) make it possible to use the termkey instance in an asynchronous program.
+This function, along with \fBtermkey_getkey\fP(3) make it possible to use the termkey instance in an asynchronous program. To provide bytes without using a readable file handle, use \fBtermkey_push_bytes\fP(3).
 .PP
 For synchronous usage, \fBtermkey_waitkey\fP(3) performs the input blocking task.
 .SH "RETURN VALUE"
diff --git a/man/termkey_get_buffer_remaining.3 b/man/termkey_get_buffer_remaining.3
index a7f7885..6f85f99 100644
--- a/man/termkey_get_buffer_remaining.3
+++ b/man/termkey_get_buffer_remaining.3
@@ -10,11 +10,12 @@ termkey_get_buffer_remaining \- returns the free buffer space
 .sp
 Link with \fI-ltermkey\fP.
 .SH DESCRIPTION
-A termkey instance contains a buffer of pending bytes that have been read by \fBtermkey_advisereadable\fP(3) but not yet consumed by \fBtermkey_getkey\fP(3). \fBtermkey_get_buffer_remaining\fP() returns the number of bytes of buffer space currently free in the termkey instance.
+A termkey instance contains a buffer of pending bytes that have been read by \fBtermkey_advisereadable\fP(3) or provided by \fBtermkey_push_bytes\fP(3) but not yet consumed by \fBtermkey_getkey\fP(3). \fBtermkey_get_buffer_remaining\fP() returns the number of bytes of buffer space currently free in the termkey instance.
 .PP
 .SH "RETURN VALUE"
 \fBtermkey_get_buffer_remaining\fP() returns a size in bytes.
 .SH "SEE ALSO"
 .BR termkey_new (3),
+.BR termkey_push_bytes (3),
 .BR termkey_advisereadable (3),
 .BR termkey_getkey (3)
diff --git a/man/termkey_getkey.3.sh b/man/termkey_getkey.3.sh
index 022f209..6f210c1 100644
--- a/man/termkey_getkey.3.sh
+++ b/man/termkey_getkey.3.sh
@@ -30,7 +30,7 @@ no bytes are waiting in the buffer.
 .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. 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().
+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(). For providing input without a readable filehandle, use \fBtermkey_push_bytes\fP(3).
 .PP
 Before returning, this function canonicalises the \fIkey\fP structure according to the rules given for \fBtermkey_canonicalise\fP(3).
 .PP
@@ -86,6 +86,7 @@ cat <<EOF
 .SH "SEE ALSO"
 .BR termkey_new (3),
 .BR termkey_advisereadable (3),
+.BR termkey_push_bytes (3),
 .BR termkey_waitkey (3),
 .BR termkey_set_waittime (3),
 .BR termkey_get_keyname (3),
diff --git a/man/termkey_push_bytes.3 b/man/termkey_push_bytes.3
new file mode 100644
index 0000000..c7dc999
--- /dev/null
+++ b/man/termkey_push_bytes.3
@@ -0,0 +1,23 @@
+.TH TERMKEY_PUSH_BYTES 3
+.SH NAME
+termkey_push_bytes \- supply more bytes to the input buffer
+.SH SYNOPSIS
+.nf
+.B #include <termkey.h>
+.sp
+.BI "size_t termkey_push_bytes(TermKey *" tk ", const char *" bytes ", size_t " len ");
+.fi
+.sp
+Link with \fI-ltermkey\fP.
+.SH DESCRIPTION
+\fBtermkey_push_bytes\fP() allows more bytes of input to be supplied directly into the input buffer of the termkey instance. If there was no buffer space remaining, then -1 is returned with \fIerrno\fP set to \fBENOMEM\fP.
+.PP
+This function, along with \fBtermkey_getkey\fP(3) make it possible to use the termkey instance in an asynchronous program, or with a source of bytes other than from reading a filehandle.
+.PP
+For synchronous usage, \fBtermkey_waitkey\fP(3) performs the input blocking task. For use against a regular stream filehandle that supports \fBread\fP(2), see \fBtermkey_advisereadable\fP(3).
+.SH "RETURN VALUE"
+\fBtermkey_push_bytes\fP() the number of bytes consumed from the input (which may be smaller than the length provided, if the buffer runs out of space) or -1 cast to \fBsize_t\fP if an error occurs.
+.SH "SEE ALSO"
+.BR termkey_new (3),
+.BR termkey_getkey (3),
+.BR termkey_advise_readable (3)