34 lines
2.1 KiB
Groff
34 lines
2.1 KiB
Groff
.TH TERMKEY_NEW 3
|
|
.SH NAME
|
|
termkey_new, termkey_destroy \- create or destroy new termkey instance
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <termkey.h>
|
|
.sp
|
|
.BI "TERMKEY_CHECK_VERSION;"
|
|
.BI "TermKey *termkey_new(int " fd ", int " flags );
|
|
.BI "void termkey_destroy(TermKey *" tk );
|
|
.fi
|
|
.sp
|
|
Link with \fI\-ltermkey\fP.
|
|
.SH DESCRIPTION
|
|
\fBtermkey_new\fP() creates a new \fBtermkey\fP(7) 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
|
|
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
|
|
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.
|
|
.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.
|
|
.SH "RETURN VALUE"
|
|
If successful, \fBtermkey_new\fP() returns a pointer to the new instance. On failure, \fBNULL\fP is returned. \fBtermkey_destroy\fP() returns no value.
|
|
.SH "SEE ALSO"
|
|
.BR termkey_waitkey (3),
|
|
.BR termkey_advisereadable (3),
|
|
.BR termkey_getkey (3),
|
|
.BR termkey_get_flags (3),
|
|
.BR termkey_get_fd (3),
|
|
.BR termkey_get_buffer_remaining (3),
|
|
.BR termkey (7)
|