Added documentation for termkey_{start,stop}, termkey_is_started

This commit is contained in:
Paul LeoNerd Evans 2012-03-08 21:58:27 +00:00
parent 24fd4f668d
commit 775806d32b
5 changed files with 33 additions and 3 deletions

View File

@ -5,3 +5,5 @@ termkey_get_canonflags.3 = termkey_set_canonflags.3
termkey_get_buffer_size.3 = termkey_set_buffer_size.3 termkey_get_buffer_size.3 = termkey_set_buffer_size.3
termkey_get_waittime.3 = termkey_set_waittime.3 termkey_get_waittime.3 = termkey_set_waittime.3
termkey_getkey_force.3 = termkey_getkey.3 termkey_getkey_force.3 = termkey_getkey.3
termkey_stop.3 = termkey_start.3
termkey_is_started.3 = termkey_start.3

View File

@ -27,6 +27,9 @@ no bytes are waiting in the buffer.
.TP .TP
.B TERMKEY_RES_EOF .B TERMKEY_RES_EOF
no bytes are ready and the input stream is now closed. no bytes are ready and the input stream is now closed.
.TP
.B TERMKEY_RES_ERROR
called with terminal IO stopped, due to \fBtermkey_stop\fP(3). In this case \fIerrno\fP will be set to \fBEINVAL\fP.
.PP .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. \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 .PP
@ -34,7 +37,7 @@ Neither of these functions will block or perform any IO operations on the underl
.PP .PP
Before returning, this function canonicalises the \fIkey\fP structure according to the rules given for \fBtermkey_canonicalise\fP(3). Before returning, this function canonicalises the \fIkey\fP structure according to the rules given for \fBtermkey_canonicalise\fP(3).
.SH "RETURN VALUE" .SH "RETURN VALUE"
\fBtermkey_getkey\fP() returns an enumeration of one of \fBTERMKEY_RES_KEY\fP, \fBTEMRKEY_RES_AGAIN\fP, \fBTERMKEY_RES_NONE\fP or \fBTERMKEY_RES_EOF\fP. \fBtermkey_getkey_force\fP() returns one of the above, except for \fBTERMKEY_RES_AGAIN\fP. \fBtermkey_getkey\fP() returns an enumeration of one of \fBTERMKEY_RES_KEY\fP, \fBTEMRKEY_RES_AGAIN\fP, \fBTERMKEY_RES_NONE\fP, \fBTERMKEY_RES_EOF\fP or \fBTERMKEY_RES_ERROR\fP. \fBtermkey_getkey_force\fP() returns one of the above, except for \fBTERMKEY_RES_AGAIN\fP.
.SH EXAMPLE .SH EXAMPLE
The following example program prints details of every keypress until the user presses "Ctrl-C". It demonstrates how to use the \fBtermkey\fP instance in a typical \fBpoll\fP(2)-driven asynchronous program, which may include mixed IO with other file handles. The following example program prints details of every keypress until the user presses "Ctrl-C". It demonstrates how to use the \fBtermkey\fP instance in a typical \fBpoll\fP(2)-driven asynchronous program, which may include mixed IO with other file handles.
.PP .PP

View File

@ -21,7 +21,7 @@ Link with \fI\-ltermkey\fP.
.PP .PP
The constructor attempts to detect if the current locale is UTF-8 aware or not, and sets either the \fBTERMKEY_FLAG_UTF8\fP or \fBTERMKEY_FLAG_RAW\fP flag. One of these two bits will always be in effect. The current flags in effect can be obtained by \fBtermkey_get_flags\fP(3). The constructor attempts to detect if the current locale is UTF-8 aware or not, and sets either the \fBTERMKEY_FLAG_UTF8\fP or \fBTERMKEY_FLAG_RAW\fP flag. One of these two bits will always be in effect. The current flags in effect can be obtained by \fBtermkey_get_flags\fP(3).
.PP .PP
If a file handle is provided, the terminfo driver may send a string to initialise or set the state of the terminal before \fBtermkey_new\fP() returns. This will not be done if no file handle is provided, or if the file handle is a pipe (\fBS_ISFIFO\fP()). In this case it will be the caller's responsibility to ensure the terminal is in the correct mode. If a file handle is provided, the terminfo driver may send a string to initialise or set the state of the terminal before \fBtermkey_new\fP() returns. This will not be done if no file handle is provided, or if the file handle is a pipe (\fBS_ISFIFO\fP()). In this case it will be the caller's responsibility to ensure the terminal is in the correct mode. Once initialised, the terminal can be stopped by \fBtermkey_stop\fP(3), and started again by \fBtermkey_start\fP(3).
.SH VERSION CHECK MACRO .SH VERSION CHECK MACRO
Before calling any functions in the \fBtermkey\fP library, an application should use the \fBTERMKEY_CHECK_VERSION\fP macro to check that the loaded version of the library is compatible with the version it was compiled against. This should be done early on, ideally just after entering its \fBmain\fP() function. Before calling any functions in the \fBtermkey\fP library, an application should use the \fBTERMKEY_CHECK_VERSION\fP macro to check that the loaded version of the library is compatible with the version it was compiled against. This should be done early on, ideally just after entering its \fBmain\fP() function.
.SH "RETURN VALUE" .SH "RETURN VALUE"

25
man/termkey_start.3 Normal file
View File

@ -0,0 +1,25 @@
.TH TERMKEY_START 3
.SH NAME
termkey_start, termkey_stop, termkey_is_started \- enable or disable terminal operations
.SH SYNOPSIS
.nf
.B #include <termkey.h>
.sp
.BI "int termkey_start(TermKey *" tk );
.BI "int termkey_stop(TermKey *" tk );
.sp
.BI "int termkey_is_started(TermKey *" tk );
.fi
.sp
Link with \fI\-ltermkey\fP.
.SH DESCRIPTION
\fBtermkey_start\fP() enables the terminal IO operations of the given \fBtermkey\fP(7) instance, including sending a terminal control sequence and setting the \fBtermios\fP(3) modes required.
.PP
\fBtermkey_stop\fP() disables terminal IO operations, by reversing the steps taken by \fPtermkey_start\fP(). A newly-constructed \fBtermkey\fP instance will have terminal IO enabled already.
.PP
\fBtermkey_is_started\fP() enquires whether terminal IO is currently enabled.
.SH "RETURN VALUE"
If successful, \fBtermkey_start\fP() and \fBtermkey_stop\fP() return a true value. On failure, zero is returned with \fIerrno\fP set to indicate the failure. \fBtermkey_is_started\fP() returns true or false to indicate whether terminal IO is currently enabled.
.SH "SEE ALSO"
.BR termkey_new (3),
.BR termkey (7)

View File

@ -27,7 +27,7 @@ A key event as been provided.
No key events are ready and the terminal has been closed, so no more will arrive. No key events are ready and the terminal has been closed, so no more will arrive.
.TP .TP
.B TERMKEY_RES_ERROR .B TERMKEY_RES_ERROR
An IO error occured. \fIerrno\fP will be preserved. If the error is \fBEINTR\fP then this will only be returned if \fBTERMKEY_FLAG_EINTR\fP flag is not set; if it is then the IO operation will be retried instead. An IO error occured. \fIerrno\fP will be preserved. If the error is \fBEINTR\fP then this will only be returned if \fBTERMKEY_FLAG_EINTR\fP flag is not set; if it is then the IO operation will be retried instead. If this is called with terminal IO stopped, due to \fBtermkey_stop\fP(3) then \fIerrno\fP will be set to \fBEINVAL\fP.
.SH EXAMPLE .SH EXAMPLE
The following example program prints details of every keypress until the user presses "Ctrl-C". The following example program prints details of every keypress until the user presses "Ctrl-C".
.PP .PP