p/termo
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

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

Browse Source
This commit is contained in:
Paul LeoNerd Evans
2012-01-18 13:39:50 +00:00
parent 082b49f0f8
commit 82ad14175c
11 changed files with 158 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
man/termkey_advisereadable.3
View File

@@ -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"

3
man/termkey_get_buffer_remaining.3
View File

@@ -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)

3
man/termkey_getkey.3.sh
View File

@@ -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),

23
man/termkey_push_bytes.3 Normal file
View File

@@ -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)