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

Also document termkey_advisereadable()

This commit is contained in:
Paul LeoNerd Evans 2008-11-06 00:56:01 +00:00
parent 388782b89b
commit c2496a38be
3 changed files with 33 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
termkey_advisereadable.3 Normal file
View File

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

3
termkey_getkey.3
View File

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

1
termkey_new.3
View File

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