Move the growing collection of manpages into their own man/ subdirectory

17 files changed, 584 insertions, 0 deletions

diff --git a/man/termkey_advisereadable.3 b/man/termkey_advisereadable.3
new file mode 100644
index 0000000..06e0467
--- /dev/null
+++ b/man/termkey_advisereadable.3
@@ -0,0 +1,33 @@
+.TH TERMKEY_ADVISEREADABLE 3
+.SH NAME
+termkey_advisereadable \- read more bytes from the underlying terminal
+.SH SYNOPSIS
+.nf
+.B #include <termkey.h>
+.sp
+.BI "TermKeyResult termkey_advisereadable(TermKey *" 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. 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.
+.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.
+.TP
+.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.
+.SH "SEE ALSO"
+.BR termkey_new (3),
+.BR termkey_getkey (3),
+.BR termkey_waitkey (3),
+.BR termkey_set_waittime (3)
diff --git a/man/termkey_canonicalise.3 b/man/termkey_canonicalise.3
new file mode 100644
index 0000000..980e400
--- /dev/null
+++ b/man/termkey_canonicalise.3
@@ -0,0 +1,27 @@
+.TH TERMKEY_CANONICALISE 3
+.SH NAME
+termkey_canonicalise \- canonicalise a key event
+.SH SYNOPSIS
+.nf
+.B #include <termkey.h>
+.sp
+.BI "void termkey_canonicalise(TermKey *" tk ", TermKeyKey *" key );
+.fi
+.sp
+Link with \fI-ltermkey\fP.
+.SH DESCRIPTION
+\fBtermkey_canonicalise\fP(3) modifies the key event structure given by \fIkey\fP according to the canonicalisation flags set on the given \fItk\fP instance. This operation is performed implicitly by \fBtermkey_getkey\fP(3), \fBtermkey_waitkey\fP(3) and \fBtermkey_strpkey\fP(3), and is also provided explicitly by this function.
+.PP
+The canonicalisation operation is affected by the following flags:
+.TP
+.B TERMKEY_CANON_SPACESYMBOL
+If this flag is set then a Unicode space character is represented using the \fBTERMKEY_SYM_SPACE\fP symbol. If this flag is not set, it is represented by the U+0020 Unicode codepoint.
+.TP
+.B TERMKEY_CANON_DELBS
+If this flag is set then an ASCII DEL character is represented by the \fBTERMKEY_SYM_BACKSPACE\fP symbol. If not, it is represented by \fBTERMKEY_SYM_DEL\fP. An ASCII BS character is always represented by \fBTERMKEY_SYM_BACKSPACE\fP, regardless of this flag.
+.SH "RETURN VALUE"
+\fBtermkey_canonicalise\fP() returns no value.
+.SH "SEE ALSO"
+.BR termkey_set_canonflags (3),
+.BR termkey_waitkey (3),
+.BR termkey_strpkey (3)
diff --git a/man/termkey_get_buffer_remaining.3 b/man/termkey_get_buffer_remaining.3
new file mode 100644
index 0000000..a7f7885
--- /dev/null
+++ b/man/termkey_get_buffer_remaining.3
@@ -0,0 +1,20 @@
+.TH TERMKEY_GET_BUFFER_REMAINING 3
+.SH NAME
+termkey_get_buffer_remaining \- returns the free buffer space
+.SH SYNOPSIS
+.nf
+.B #include <termkey.h>
+.sp
+.BI "size_t termkey_get_buffer_remaining(TermKey *" tk ");
+.fi
+.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.
+.PP
+.SH "RETURN VALUE"
+\fBtermkey_get_buffer_remaining\fP() returns a size in bytes.
+.SH "SEE ALSO"
+.BR termkey_new (3),
+.BR termkey_advisereadable (3),
+.BR termkey_getkey (3)
diff --git a/man/termkey_get_fd.3 b/man/termkey_get_fd.3
new file mode 100644
index 0000000..733f820
--- /dev/null
+++ b/man/termkey_get_fd.3
@@ -0,0 +1,18 @@
+.TH TERMKEY_GET_FD 3
+.SH NAME
+termkey_get_fd \- obtain the file descriptor for the terminal
+.SH SYNOPSIS
+.nf
+.B #include <termkey.h>
+.sp
+.BI "int termkey_get_fd(TermKey *" tk );
+.fi
+.sp
+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.
+.SH "SEE ALSO"
+.BR termkey_new (3),
+.BR termkey_get_flags (3)
diff --git a/man/termkey_get_keyname.3 b/man/termkey_get_keyname.3
new file mode 100644
index 0000000..5f0119f
--- /dev/null
+++ b/man/termkey_get_keyname.3
@@ -0,0 +1,22 @@
+.TH TERMKEY_GET_KEYNAME 3
+.SH NAME
+termkey_get_keyname \- return a string name for a symbolic key
+.SH SYNOPSIS
+.nf
+.B #include <termkey.h>
+.sp
+.BI "const char *termkey_get_keyname(TermKey *" tk ", TermKeySym " sym );
+.fi
+.sp
+Link with \fI-ltermkey\fP.
+.SH DESCRIPTION
+\fBtermkey_get_keyname\fP() returns a human-readable string name for the symbolic key value given by \fBsym\fP. The returned string is owned by the termkey instance \fItk\fP so should not be modified or freed. The returned pointer is guaranteed to be valid until the termkey instance is released using \fBtermkey_destroy\fP(3). This function is the inverse of \fBtermkey_keyname2sym\fP(3).
+.SH "RETURN VALUE"
+\fBtermkey_get_key\fP() returns a pointer to a string.
+.SH "SEE ALSO"
+.BR termkey_new (3),
+.BR termkey_getkey (3),
+.BR termkey_waitkey (3),
+.BR termkey_lookup_keyname (3),
+.BR termkey_keyname2sym (3),
+.BR termkey_strfkey (3)
diff --git a/man/termkey_getkey.3.sh b/man/termkey_getkey.3.sh
new file mode 100644
index 0000000..022f209
--- /dev/null
+++ b/man/termkey_getkey.3.sh
@@ -0,0 +1,95 @@
+# vim:ft=nroff
+cat <<EOF
+.TH TERMKEY_GETKEY 3
+.SH NAME
+termkey_getkey, termkey_getkey_force \- retrieve the next key event
+.SH SYNOPSIS
+.nf
+.B #include <termkey.h>
+.sp
+.BI "TermKeyResult termkey_getkey(TermKey *" tk ", TermKeyKey *" key );
+.BI "TermKeyResult termkey_getkey_force(TermKey *" tk ", TermKeyKey *" key );
+.fi
+.sp
+Link with \fI-ltermkey\fP.
+.SH DESCRIPTION
+\fBtermkey_getkey\fP() attempts to retrieve a single keypress event from the buffer, and put it in the structure referred to by \fIkey\fP. It returns one of the following values:
+.in
+.TP
+.B TERMKEY_RES_KEY
+a complete keypress was removed from the buffer, and has been placed in the \fIkey\fP structure.
+.TP
+.B TERMKEY_RES_AGAIN
+a partial keypress event was found in the buffer, but it does not yet contain all the bytes required. An indication of what \fBtermkey_getkey_force\fP(3) would return has been placed in the \fIkey\fP structure.
+.TP
+.B TERMKEY_RES_NONE
+no bytes are waiting in the buffer.
+.TP
+.B TERMKEY_RES_EOF
+ no bytes are ready and the input stream is now closed.
+.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().
+.PP
+Before returning, this function canonicalises the \fIkey\fP structure according to the rules given for \fBtermkey_canonicalise\fP(3).
+.PP
+The \fITermKeyKey\fP structure is defined as follows:
+.PP
+.in +4n
+.nf
+typedef struct {
+    TermKeyType type;
+    union {
+        long       codepoint; /* TERMKEY_TYPE_UNICODE  */
+        int        number;    /* TERMKEY_TYPE_FUNCTION */
+        TermKeySym sym;       /* TERMKEY_TYPE_KEYSYM   */
+        char       mouse[4]   /* TERMKEY_TYPE_MOUSE    */
+    } code;
+    int modifiers;
+    char utf8[7];
+} TermKeyKey;
+.fi
+.in
+.PP
+The \fItype\fP field indicates the type of event, and determines which of the members of the \fIcode\fP union is valid. It will be one of the following constants:
+.TP
+.B TERMKEY_TYPE_UNICODE
+a Unicode codepoint. This value indicates that \fIcode.codepoint\fP is valid, and will contain the codepoint number of the keypress. In Unicode mode (if the \fBTERMKEY_FLAG_UTF8\fP bit is set) this will be its Unicode character number. In raw byte mode, this will contain a single 8-bit byte.
+.TP
+.B TERMKEY_TYPE_FUNCTION
+a numbered function key. This value indicates that \fIcode.number\fP is valid, and contains the number of the numbered function key.
+.TP
+.B TERMKEY_TYPE_KEYSYM
+a symbolic key. This value indicates that \fIcode.sym\fP is valid, and contains the symbolic key value. This is an opaque value which may be passed to \fBtermkey_get_keyname\fP(3).
+.TP
+.B TERMKEY_TYPE_MOUSE
+a mouse button press, release, or movement. The \fIcode.mouse\fP array should be considered opaque. Use \fBtermkey_interpret_mouse\fP(3) to interpret it.
+.PP
+The \fImodifiers\fP bitmask is composed of a bitwise-or of the constants \fBTERMKEY_KEYMOD_SHIFT\fP, \fBTERMKEY_KEYMOD_CTRL\fP and \fBTERMKEY_KEYMOD_ALT\fP.
+.PP
+The \fIutf8\fP field is only set on events whose \fItype\fP is \fBTERMKEY_TYPE_UNICODE\fP. It should not be read for other events.
+.PP
+To convert the \fIsym\fP to a symbolic name, see \fBtermkey_get_keyname\fP(3) function. It may instead be easier to convert the entire key event structure to a string, using \fBtermkey_strfkey\fP(3).
+.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.
+.SH EXAMPLE
+The following example program prints details of every keypress until the user presses "Ctrl-C". It demonstrates how to use the termkey instance in a typical \fBpoll\fP()-driven asynchronous program, which may include mixed IO with other file handles.
+.PP
+.in +4n
+.nf
+EOF
+sed "s/\\\\/\\\\\\\\/g" demo-async.c
+cat <<EOF
+.in
+.fi
+.SH "SEE ALSO"
+.BR termkey_new (3),
+.BR termkey_advisereadable (3),
+.BR termkey_waitkey (3),
+.BR termkey_set_waittime (3),
+.BR termkey_get_keyname (3),
+.BR termkey_interpret_mouse (3),
+.BR termkey_strfkey (3),
+.BR termkey_keycmp (3)
+EOF
diff --git a/man/termkey_interpret_mouse.3 b/man/termkey_interpret_mouse.3
new file mode 100644
index 0000000..6963054
--- /dev/null
+++ b/man/termkey_interpret_mouse.3
@@ -0,0 +1,43 @@
+.TH TERMKEY_INTERPRET_MOUSE 3
+.SH NAME
+termkey_interpret_mouse \- interpret opaque mouse event data
+.SH SYNOPSIS
+.nf
+.B #include <termkey.h>
+.sp
+.BI "TermKeyResult termkey_interpret_mouse(TermKey *" tk ", TermKeyKey *" key ", "
+.BI "    TermKeyMouseEvent *" ev ", int *" button ", int *" line ", int *" col );
+.fi
+.sp
+Link with \fI-ltermkey\fP.
+.SH DESCRIPTION
+\fBtermkey_interpret_mouse\fP() fills in variables in the passed pointers according to the mouse event found in \fIkey\fP. It should be called if \fBtermkey_getkey\fP(3) or similar have returned a key event with the type of \fBTERMKEY_TYPE_MOUSE\fP.
+.PP
+Any pointer may instead be given as \fBNULL\fP to not return that value.
+.PP
+The \fIev\fP variable will take one of the following values:
+.in
+.TP
+.B TERMKEY_MOUSE_UNKNOWN
+an unknown mouse event.
+.TP
+.B TERMKEY_MOUSE_PRESS
+a mouse button was pressed; \fIbutton\fP will contain its number.
+.TP
+.B TERMKEY_MOUSE_DRAG
+the mouse was moved while holding a button; \fIbutton\fP will contain its number.
+.TP
+.B TERMKEY_MOUSE_RELEASE
+a mouse button was released, or the mouse was moved while no button was pressed. If known, \fIbutton\fP will contain the number of the button released. Not all terminals can report this, so it may be 0 instead.
+.PP
+The \fIline\fP and \fIcol\fP variables will be filled in with the mouse position, indexed from 1.
+.PP
+After calling this function, it is possible that the \fImodifiers\fP field of the \fIkey\fP structure will have been set according to the modifiers reported by the terminal. This function will not otherwise alter either the \fIkey\fP or the containing \fItk\fP structure, and will be safe to call again on the same event if required.
+.SH "RETURN VALUE"
+If passed a \fIkey\fP event of the type \fBTERMKEY_TYPE_MOUSE\fP, this function will return \fBTERMKEY_RES_KEY\fP and will affect the variables whose pointers were passed in, as described above.
+.PP
+For other event types it will return \fBTERMKEY_RES_NONE\fP, and its effects on any variables whose pointers were passed in, are undefined.
+.SH "SEE ALSO"
+.BR termkey_new (3),
+.BR termkey_waitkey (3),
+.BR termkey_getkey (3),
diff --git a/man/termkey_keycmp.3 b/man/termkey_keycmp.3
new file mode 100644
index 0000000..3eed66c
--- /dev/null
+++ b/man/termkey_keycmp.3
@@ -0,0 +1,25 @@
+.TH TERMKEY_KEYCMP 3
+.SH NAME
+termkey_keycmp \- compare two key events
+.SH SYNOPSIS
+.nf
+.B #include <termkey.h>
+.sp
+.BI "int termkey_keycmp(TermKey *" tk ", const TermKeyKey *" key1 ",
+.BI "             const TermKeyKey *" key2 );
+.fi
+.sp
+Link with \fI-ltermkey\fP.
+.SH DESCRIPTION
+\fBtermkey_keycmp\fP() compares two key structures and applies a total ordering, returning a value that is positive, zero, or negative, to indicate if the given structures are increasing, identical, or decreasing. Before comparison, copies of both referenced structures are taken, and canonicalised according to the rules for \fBtermkey_canonicalise\fP(3).
+.PP
+Two structures of differing type are ordered \fBTERMKEY_TYPE_UNICODE\fP, \fBTERMKEY_TYPE_KEYSYM\fP, \fBTERMKEY_TYPE_FUNCTION\fP, \fBTERMKEY_TYPE_MOUSE\fP. Unicode structures are ordered by codepoint, keysym structures are ordered by keysym number, function structures are ordered by function key number, and mouse structures are ordered opaquely by an unspecified but consistent ordering. Within these values, keys different in modifier bits are ordered by the modifiers.
+.SH "RETURN VALUE"
+\fBtermkey_keycmp\fP() returns an integer greater than, equal to, or less than zero to indicate the relation between the two given key structures.
+.SH NOTES
+This function does not perform any canonicalisation of the key structures, and performs a simple comparison of the fields in the structures. In particular, it will not consider as equal \fBTERMKEY_TYPE_UNICODE\fP containing the Space codepoint (U+0020) vs. \fBTERMKEY_TYPE_KEYSYM\fP containing \fBTERMKEY_SYM_SPACE\fP. 
+.SH "SEE ALSO"
+.BR termkey_new (3),
+.BR termkey_getkey (3),
+.BR termkey_strpkey (3),
+.BR termkey_canonicalise (3)
diff --git a/man/termkey_keyname2sym.3 b/man/termkey_keyname2sym.3
new file mode 100644
index 0000000..095a465
--- /dev/null
+++ b/man/termkey_keyname2sym.3
@@ -0,0 +1,22 @@
+.TH TERMKEY_KEYNAME2SYM 3
+.SH NAME
+termkey_keyname2sym \- look up a symbolic key value for a string name
+.SH SYNOPSIS
+.nf
+.B #include <termkey.h>
+.sp
+.BI "TermKeySym termkey_keyname2sym(TermKey *" tk ", const char *" keyname );
+.fi
+.sp
+Link with \fI-ltermkey\fP.
+.SH DESCRIPTION
+\fBtermkey_keyname2sym\fP() looks up the symbolic key value represented by the given string name. This is a case-sensitive comparison. If the given name is not found, \fBTERMKEY_SYM_UNKNOWN\fP is returned instead. This function is the inverse of \fBtermkey_get_keyname\fP(3), and is a more specific form of \fBtermkey_lookup_keyname\fP(3) which only recognises names as complete strings.
+.PP
+Because the key names are stored in an array indexed by the symbol number, this function has to perform a linear search of the names. Use of this function should be restricted to converting key names into symbolic values during a program's initialisation, so that efficient comparisons can be done while it is running.
+.SH "RETURN VALUE"
+\fBtermkey_keyname2sym\fP() returns a symbolic key constant, or \fBTERMKEY_SYM_UNKNOWN\fP.
+.SH "SEE ALSO"
+.BR termkey_new (3),
+.BR termkey_get_keyname (3),
+.BR termkey_lookup_keyname (3),
+.BR termkey_strpkey (3)
diff --git a/man/termkey_lookup_keyname.3 b/man/termkey_lookup_keyname.3
new file mode 100644
index 0000000..bd44411
--- /dev/null
+++ b/man/termkey_lookup_keyname.3
@@ -0,0 +1,23 @@
+.TH TERMKEY_LOOKUP_KEYNAME 3
+.SH NAME
+termkey_lookup_keyname \- look up a symbolic key value for a string name
+.SH SYNOPSIS
+.nf
+.B #include <termkey.h>
+.sp
+.BI "char *termkey_lookup_keyname(TermKey *" tk ", const char *" keyname ",
+.BI "           TermKeySym *" sym ");
+.fi
+.sp
+Link with \fI-ltermkey\fP.
+.SH DESCRIPTION
+\fBtermkey_lookup_keyname\fP() looks up the symbolic key value represented by the given string name. This is a case-sensitive comparison. The symbolic value is written to the variable addressed by \fIsym\fP. This function is a more general form of \fBtermkey_keyname2sym\fP(3) because it can recognise a symbolic key name within a longer string, returning a pointer to the remainder of the input after the key name.
+.PP
+Because the key names are stored in an array indexed by the symbol number, this function has to perform a linear search of the names. Use of this function should be restricted to converting key names into symbolic values during a program's initialisation, so that efficient comparisons can be done while it is running.
+.SH "RETURN VALUE"
+\fBtermkey_lookup_keyname\fP() returns a pointer to the first character after a recognised name, or \fBNULL\fP if the string does not begin with the name of a recognised symbolic key.
+.SH "SEE ALSO"
+.BR termkey_new (3),
+.BR termkey_get_keyname (3),
+.BR termkey_keyname2sym (3),
+.BR termkey_strpkey (3)
diff --git a/man/termkey_new.3 b/man/termkey_new.3
new file mode 100644
index 0000000..e4a3a37
--- /dev/null
+++ b/man/termkey_new.3
@@ -0,0 +1,60 @@
+.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 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.
+.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 following values may be given as the \fIflags\fP bitmask:
+.TP
+.B TERMKEY_FLAG_NOINTERPRET
+Do not attempt to interpret \fBC0\fP codes into keysyms. Instead report them as plain "Ctrl-letter" events.
+.TP
+.B TERMKEY_FLAG_CONVERTKP
+Convert xterm's alternative keypad symbols into the plain
+.SM ASCII
+codes they would represent.
+.TP
+.B TERMKEY_FLAG_RAW
+Ignore locale settings; do not attempt to recombine UTF-8 sequences. Instead report only raw values.
+.TP
+.B TERMKEY_FLAG_UTF8
+Ignore locale settings; force UTF-8 recombining on. This flag overrides \fBTERMKEY_FLAG_RAW\fP.
+.TP
+.B TERMKEY_FLAG_NOTERMIOS
+Even if the terminal file descriptor \fIfd\fP represents a
+.SM TTY
+device, do not call the \fBtcsetattr\fP(3) \fBtermios\fP function on it to set it to canonical input mode.
+.TP
+.B TERMKEY_FLAG_SPACESYMBOL
+Report space as being a symbolic key rather than a Unicode codepoint.
+.TP
+.B TERMKEY_FLAG_CTRLC
+Disable the \fBSIGINT\fP behaviour of \fICtrl-C\fP. If this flag is provided, then \fICtrl-C\fP will be available as a normal keypress, rather than sending the process group a \fBSIGINT\fP. This flag only takes effect without \fBTERMKEY_FLAG_NOTERMIOS\fP; with it, none of the signal keys are disabled anyway.
+.TP
+.B TERMKEY_FLAG_EINTR
+Without this flag, IO operations are retried when interrupted by a signal (\fBEINTR\fP). With this flag the \fBTERMKEY_RES_ERROR\fP result is returned instead.
+.PP
+When the constructor is invoked, it 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).
+.SH VERSION CHECK MACRO
+Before calling any functions in the \fItermkey\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)
diff --git a/man/termkey_set_canonflags.3 b/man/termkey_set_canonflags.3
new file mode 100644
index 0000000..2bc125c
--- /dev/null
+++ b/man/termkey_set_canonflags.3
@@ -0,0 +1,21 @@
+.TH TERMKEY_SET_CANONFLAGS 3
+.SH NAME
+termkey_set_canonflags, termkey_get_canonflags \- control the canonicalisation flags
+.SH SYNOPSIS
+.nf
+.B #include <termkey.h>
+.sp
+.BI "void termkey_set_canonflags(TermKey *" tk ", int " newflags );
+.BI "int termkey_get_canonflags(TermKey *" tk );
+.fi
+.sp
+Link with \fI-ltermkey\fP.
+.SH DESCRIPTION
+\fBtermkey_set_canonflags\fP() changes the set of canonicalisation flags in the termkey instance to those given by \fInewflags\fP. For detail on the available flags and their meaning, see \fBtermkey_set_canonflags\fP(3).
+.PP
+\fBtermkey_get_canonflags\fP() returns the value set by the last call to \fBtermkey_canonicalise\fP().
+.SH "RETURN VALUE"
+\fBtermkey_set_flags\fP() returns no value. \fBtermkey_get_flags\fP() returns the current canonicalisation flags.
+.SH "SEE ALSO"
+.BR termkey_new (3),
+.BR termkey_canonicalise (3)
diff --git a/man/termkey_set_flags.3 b/man/termkey_set_flags.3
new file mode 100644
index 0000000..1d8f4e8
--- /dev/null
+++ b/man/termkey_set_flags.3
@@ -0,0 +1,22 @@
+.TH TERMKEY_SET_FLAGS 3
+.SH NAME
+termkey_set_flags, termkey_get_flags \- control the operational flags
+.SH SYNOPSIS
+.nf
+.B #include <termkey.h>
+.sp
+.BI "void termkey_set_flags(TermKey *" tk ", int " newflags );
+.BI "int termkey_get_flags(TermKey *" tk );
+.fi
+.sp
+Link with \fI-ltermkey\fP.
+.SH DESCRIPTION
+\fBtermkey_set_flags\fP() changes the set of operation flags in the termkey instance to those given by \fInewflags\fP.
+.PP
+\fBtermkey_get_flags\fP() returns the value set by the last call to \fBtermkey_set_flags\fP(), or the value given to the constructor.
+.PP
+When the constructor is invoked, it 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 returned by \fBtermkey_get_flags\fP().
+.SH "RETURN VALUE"
+\fBtermkey_set_flags\fP() returns no value. \fBtermkey_get_flags\fP() returns the current operational flags.
+.SH "SEE ALSO"
+.BR termkey_new (3)
diff --git a/man/termkey_set_waittime.3 b/man/termkey_set_waittime.3
new file mode 100644
index 0000000..0cc042f
--- /dev/null
+++ b/man/termkey_set_waittime.3
@@ -0,0 +1,22 @@
+.TH TERMKEY_SET_WAITTIME 3
+.SH NAME
+termkey_set_waittime, termkey_get_waittime \- control the wait time for multibyte sequences
+.SH SYNOPSIS
+.nf
+.B #include <termkey.h>
+.sp
+.BI "void termkey_set_waittime(TermKey *" tk ", int " msec );
+.BI "int termkey_get_waittime(TermKey *" tk );
+.fi
+.sp
+Link with \fI-ltermkey\fP.
+.SH DESCRIPTION
+\fBtermkey_set_waittime\fP() sets the number of miliseconds that \fBtermkey_waitkey\fP(3) will wait for the remaining bytes of a multibyte sequence if it detects the start of a partially-complete one.
+.PP
+\fBtermkey_get_waittime\fP() returns the value set by the last call to \fBtermkey_set_waittime\fP(), or the default value if a different has not been set.
+.SH "RETURN VALUE"
+\fBtermkey_set_waittime\fP() returns no value. \fBtermkey_get_waittime\fP() returns the current wait time in miliseconds.
+.SH "SEE ALSO"
+.BR termkey_new (3),
+.BR termkey_getkey (3),
+.BR termkey_waitkey (3)
diff --git a/man/termkey_strfkey.3 b/man/termkey_strfkey.3
new file mode 100644
index 0000000..7767952
--- /dev/null
+++ b/man/termkey_strfkey.3
@@ -0,0 +1,46 @@
+.TH TERMKEY_STRFKEY 3
+.SH NAME
+termkey_strfkey \- format a string representing a key event
+.SH SYNOPSIS
+.nf
+.B #include <termkey.h>
+.sp
+.BI "size_t termkey_strfkey(TermKey *" tk ", char *" buffer ", size_t " len ",
+.BI "            TermKeyKey *" key ", TermKeyFormat " format );
+.fi
+.sp
+Link with \fI-ltermkey\fP.
+.SH DESCRIPTION
+\fBtermkey_strfkey\fP() formats a string buffer to contain a human-readable representation of a key event. It fills the \fIbuffer\fP in a way analogous to the \fBsnprintf\fP(3) or \fBstrftime\fP(3) standard library functions. This function used to be called \fBtermkey_snprint_key\fP() but was renamed after version 0.6.
+.PP
+The \fIformat\fP argument specifies the format of the output, as a bitmask of the following constants:
+.TP
+.B TERMKEY_FORMAT_LONGMOD
+Print full modifier names e.g. "Shift-" instead of abbreviating to "S-".
+.TP
+.B TERMKEY_FORMAT_CARETCTRL
+If the only modifier is \fBTERMKEY_MOD_CTRL\fP on a plain letter, render it as "^X" rather than "Ctrl-X".
+.TP
+.B TERMKEY_FORMAT_ALTISMETA
+Use the name "Meta" or the letter "M" instead of "Alt" or "A".
+.TP
+.B TERMKEY_FORMAT_WRAPBRACKET
+If the key event is a special key instead of unmodified Unicode, wrap it in "<brackets>".
+.TP
+.B TERMKEY_FORMAT_MOUSE_POS
+If the event is a mouse event, include the position rendered as "@ (col,line)".
+.PP
+The following shortcuts are provided for common combinations of format bits:
+.TP
+.B TERMKEY_FORMAT_VIM
+Shortcut to set \fBALTISMETA\fP and \fBWRAPBRACKET\fP, to give an output close to the format the \fIvim\fP editor uses.
+.PP
+When formatting a \fBTERMKEY_TYPE_UNICODE\fP key structure, this function uses the \fIutf8\fP member. If this member contains an empty string (i.e. its first character is 0) then this member will be prefilled by the function from the \fIcode.number\fP member. This can be convenient when the key structure is being constructed programatically by user code.
+.SH "RETURN VALUE"
+\fBtermkey_strfkey\fP() returns the number of characters written to \fIbuffer\fP.
+.SH "SEE ALSO"
+.BR termkey_new (3),
+.BR termkey_getkey (3),
+.BR termkey_waitkey (3),
+.BR termkey_get_keyname (3),
+.BR termkey_strpkey (3)
diff --git a/man/termkey_strpkey.3 b/man/termkey_strpkey.3
new file mode 100644
index 0000000..f9de839
--- /dev/null
+++ b/man/termkey_strpkey.3
@@ -0,0 +1,35 @@
+.TH TERMKEY_STRPKEY 3
+.SH NAME
+termkey_strpkey \- parse a string representing a key event
+.SH SYNOPSIS
+.nf
+.B #include <termkey.h>
+.sp
+.BI "char *termkey_strpkey(TermKey *" tk ", const char *" str ",
+.BI "            TermKeyKey *" key ", TermKeyFormat " format );
+.fi
+.sp
+Link with \fI-ltermkey\fP.
+.SH DESCRIPTION
+\fBtermkey_strpkey\fP(3) parses a string buffer containing a human-readable representation of a key event. It fills the \fIkey\fP structure from the results of this parsing, similar to the \fBstrptime\fP(3) standard library function.
+.PP
+The \fIformat\fP argument specifies the format expected in the string, as a bitmask of the following constants:
+.TP
+.B TERMKEY_FORMAT_LONGMOD
+Expect full modifier names e.g. "Shift-" instead of abbreviating to "S-".
+.TP
+.B TERMKEY_FORMAT_CARETCTRL
+If the only modifier is \fBTERMKEY_MOD_CTRL\fP on a plain letter, accept it as "^X" rather than "Ctrl-X".
+.TP
+.B TERMKEY_FORMAT_ALTISMETA
+Use the name "Meta" or the letter "M" instead of "Alt" or "A".
+.PP
+Before returning, this function canonicalises the \fIkey\fP structure according to the rules given for \fBtermkey_canonicalise\fP(3).
+.PP
+The \fBTERMKEY_FORMAT_WRAPBRACKET\fP and \fBTERMKEY_FORMAT_MOUSE_POS\fP options are currently not supported by \fBtermkey_strpkey\fP(). When returning a \fBTERMKEY_TYPE_UNICODE\fP key structure, this function will fill in the \fIutf8\fP member.
+.SH "RETURN VALUE"
+After a successful parse, \fBtermkey_strpkey\fP() returns a pointer to the first character of the input it did not consume. If the input string contains more characters then this will point at the first character beyond. If the entire input string was consumed, then this will point at a null byte. If \fBtermkey_strpkey\fP() fails to parse, it returns \fBNULL\fP. After a failed parse, the \fIkey\fP structure may contain partial or invalid results. The structure will only be valid if the function returns a non-\fBNULL\fP result.
+.SH "SEE ALSO"
+.BR termkey_new (3),
+.BR termkey_strfkey (3),
+.BR termkey_keycmp (3)
diff --git a/man/termkey_waitkey.3.sh b/man/termkey_waitkey.3.sh
new file mode 100644
index 0000000..754ac21
--- /dev/null
+++ b/man/termkey_waitkey.3.sh
@@ -0,0 +1,50 @@
+# vim:ft=nroff
+cat <<EOF
+.TH TERMKEY_WAITKEY 3
+.SH NAME
+termkey_waitkey \- wait for and retrieve the next key event
+.SH SYNOPSIS
+.nf
+.B #include <termkey.h>
+.sp
+.BI "TermKeyResult termkey_waitkey(TermKey *" tk ", TermKeyKey *" key );
+.fi
+.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.
+.PP
+Before returning, this function canonicalises the \fIkey\fP structure according to the rules given for \fBtermkey_canonicalise\fP(3).
+.PP
+For details of the \fITermKeyKey\fP structure, see \fBtermkey_getkey\fP(3).
+.PP
+Some keypresses generate multiple bytes from the terminal. Because there may be network or other delays between the terminal and an application using termkey, \fBtermkey_waitkey\fP() will attempt to wait for the remaining bytes to arrive if it detects the start of a multibyte sequence. If no more bytes arrive within a certain time, then the bytes will be reported as they stand, even if this results in interpreting a partially-complete Escape sequence as a literal Escape key followed by some normal letters or other symbols. The amount of time to wait can be set by \fBtermkey_set_waittime\fP(3).
+.SH "RETURN VALUE"
+\fBtermkey_waitkey\fP() returns one of the following constants:
+.TP
+.B TERMKEY_RES_KEY
+A key event as been provided.
+.TP
+.B TERMKEY_RES_EOF
+No key events are ready and the terminal has been closed, so no more will arrive.
+.TP
+.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.
+.SH EXAMPLE
+The following example program prints details of every keypress until the user presses "Ctrl-C".
+.PP
+.in +4n
+.nf
+EOF
+sed "s/\\\\/\\\\\\\\/g" demo.c
+cat <<EOF
+.in
+.fi
+.SH "SEE ALSO"
+.BR termkey_new (3),
+.BR termkey_getkey (3),
+.BR termkey_set_waittime (3),
+.BR termkey_get_keyname (3),
+.BR termkey_strfkey (3),
+.BR termkey_keycmp (3)
+EOF