From 6d6afe788c3ec1f320e12449eee230fb366228c5 Mon Sep 17 00:00:00 2001 From: Paul LeoNerd Evans Date: Wed, 18 Jan 2012 14:03:39 +0000 Subject: Allow passing fd = -1 to constructor to make an instance not associated with an fd; must use push_bytes to provide it input --- man/termkey_advisereadable.3 | 2 +- man/termkey_get_fd.3 | 2 +- man/termkey_new.3 | 4 +++- man/termkey_waitkey.3.sh | 2 +- 4 files changed, 6 insertions(+), 4 deletions(-) (limited to 'man') diff --git a/man/termkey_advisereadable.3 b/man/termkey_advisereadable.3 index 3c63fdd..2d7ca4a 100644 --- a/man/termkey_advisereadable.3 +++ b/man/termkey_advisereadable.3 @@ -10,7 +10,7 @@ termkey_advisereadable \- read more bytes from the underlying terminal .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. If there was no buffer space remaining, then \fBTERMKEY_RES_ERROR\fP is returned with \fIerrno\fP set to \fBENOMEM\fP. +\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. If no filehandle is associated with this instance, \fBTERMKEY_RES_ERROR\fP is returned with \fIerrno\fP set to \fBEBADF\fP. .PP 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 diff --git a/man/termkey_get_fd.3 b/man/termkey_get_fd.3 index 733f820..d94de5f 100644 --- a/man/termkey_get_fd.3 +++ b/man/termkey_get_fd.3 @@ -12,7 +12,7 @@ Link with \fI-ltermkey\fP. .SH DESCRIPTION \fBtermkey_get_fd\fP() returns the file descriptor that was passed as the \fIfd\fP argument to \fBtermkey_new\fP(3). .SH "RETURN VALUE" -\fBtermkey_get_fd\fP() returns the current file descriptor. +\fBtermkey_get_fd\fP() returns the current file descriptor, or -1 if no file descriptor is associated with this instance. .SH "SEE ALSO" .BR termkey_new (3), .BR termkey_get_flags (3) diff --git a/man/termkey_new.3 b/man/termkey_new.3 index e4a3a37..b9ded7b 100644 --- a/man/termkey_new.3 +++ b/man/termkey_new.3 @@ -12,10 +12,12 @@ termkey_new, termkey_destroy \- create or destroy new termkey instance .sp Link with \fI\-ltermkey\fP. .SH DESCRIPTION -\fBtermkey_new\fP() creates a new termkey instance connected to the file handle opened by \fIfd\fP using the \fIflags\fP. The \fITermKey\fP structure should be considered opaque; its contents are not intended for use outside of the library. +\fBtermkey_new\fP() creates a new termkey instance connected to the file handle opened by \fIfd\fP using the \fIflags\fP. The \fITermKey\fP structure should be considered opaque; its contents are not intended for use outside of the library. If \fIfd\fP is given the value -1, then no file handle will be associated. .PP \fBtermkey_destroy\fP() destroys the given instance and releases any resources controlled by it. It will not close the underlying filehandle given as the \fIfd\fP argument to \fBtermkey_new\fP(). .PP +A termkey instance contains a buffer of bytes representing keypresses yet to be returned to the application. This buffer may be fed bytes directly by calling \fBtermkey_push_bytes\fP(3), or by calling \fBtermkey_advisereadable\fP(3) which itself will \fBread\fP(3) them from the filehandle given by \fIfd\fP. Once in the buffer, these bytes can be returned as key press events by calling \fBtermkey_getkey\fP(3). The read and get operations are combined in a single function \fBtermkey_waitkey\fP(3), which may be more convenient to use in the standard case of blocking reads from the \fIstdin\fP filehandle. +.PP The following values may be given as the \fIflags\fP bitmask: .TP .B TERMKEY_FLAG_NOINTERPRET diff --git a/man/termkey_waitkey.3.sh b/man/termkey_waitkey.3.sh index 754ac21..9155656 100644 --- a/man/termkey_waitkey.3.sh +++ b/man/termkey_waitkey.3.sh @@ -12,7 +12,7 @@ termkey_waitkey \- wait for and retrieve the next key event .sp Link with \fI-ltermkey\fP. .SH DESCRIPTION -\fBtermkey_waitkey\fP(3) attempts to retrieve a single keypress event from the buffer, and put it in the structure referred to by \fIkey\fP. If successful it will return \fBTERMKEY_RES_KEY\fP to indicate that the structure now contains a new keypress event. If nothing is in the buffer it will block until one is available. If no events are ready and the input stream is now closed, will return \fBTERMKEY_RES_EOF\fP. +\fBtermkey_waitkey\fP(3) attempts to retrieve a single keypress event from the buffer, and put it in the structure referred to by \fIkey\fP. If successful it will return \fBTERMKEY_RES_KEY\fP to indicate that the structure now contains a new keypress event. If nothing is in the buffer it will block until one is available. If no events are ready and the input stream is now closed, will return \fBTERMKEY_RES_EOF\fP. If no filehandle is associated with this instance, \fBTERMKEY_RES_ERROR\fP is returned with \fIerrno\fP set to \fBEBADF\fP. .PP Before returning, this function canonicalises the \fIkey\fP structure according to the rules given for \fBtermkey_canonicalise\fP(3). .PP -- cgit v1.2.3-70-g09d2