Add a tickit_term_teardown() API function for reliable terminal stop

3 files changed, 6 insertions, 1 deletions

diff --git a/man/also b/man/also
index 92f36fe..f85550c 100644
--- a/man/also
+++ b/man/also
@@ -19,6 +19,7 @@ tickit_term_emit_mouse.3 = tickit_term_emit_key.3
 tickit_term_lookup_ctl.3 = tickit_term_ctlname.3
 tickit_term_ctltype.3 = tickit_term_ctlname.3
 tickit_term_resume.3 = tickit_term_pause.3
+tickit_term_teardown.3 = tickit_term_pause.3
 
 tickit_pen_new_attrs.3 = tickit_pen_new.3
 tickit_pen_clone.3 = tickit_pen_new.3
diff --git a/man/tickit_term.7 b/man/tickit_term.7
index 761a66f..c19e5d9 100644
--- a/man/tickit_term.7
+++ b/man/tickit_term.7
@@ -15,7 +15,7 @@ A new \fBTickitTerm\fP instance is created using the \fBtickit_term_build\fP(3).
 .PP
 The \fBtickit_term_open_stdio\fP(3) function offers a convenient shortcut to creating a new instance set up to represent the standard input and output streams of the process.
 .PP
-Once built the terminal startup actions are performed, and the \fBtickit_term_await_started_msec\fP(3) function can be used to wait until this is complete. A running instance can be paused using \fBtickit_term_pause\fP(3) and resumed using \fBtickit_term_resume\fP(3).
+Once built the terminal startup actions are performed, and the \fBtickit_term_await_started_msec\fP(3) function can be used to wait until this is complete. A running instance can be paused using \fBtickit_term_pause\fP(3) and resumed using \fBtickit_term_resume\fP(3). It can be stopped entirely ahead of application termination by \fBtickit_term_teardown\fP(3).
 .PP
 It supports
 .SM UTF-8
diff --git a/man/tickit_term_pause.3 b/man/tickit_term_pause.3
index dad3a3e..a9ad95a 100644
--- a/man/tickit_term_pause.3
+++ b/man/tickit_term_pause.3
@@ -7,6 +7,8 @@ tickit_term_pause, tickit_term_resume \- pause and resume a terminal instance
 .sp
 .BI "void tickit_term_pause(TickitTerm *" tt );
 .BI "void tickit_term_resume(TickitTerm *" tt );
+.sp
+.BI "void tickit_term_teardown(TickitTerm *" tt );
 .EE
 .sp
 Link with \fI\-ltickit\fP.
@@ -16,6 +18,8 @@ Link with \fI\-ltickit\fP.
 \fBtickit_term_resume\fP() returns the terminal back to the state it was operating in before \fBtickit_term_pause\fP() was called, allowing the program to continue as normal.
 .PP
 It is intended these functions be used to create a program-wide suspend feature, where the terminal can be handed back over to the invoking shell while the process backgrounds itself. Typically this is done by the process sending itself a \fBSIGSTOP\fP signal via \fBraise\fP(3). After calling \fBtickit_term_pause\fP(), no other terminal-related functions should be called, nor other IO operations attempted, until after a subsequent \fBtickit_term_resume\fP(3).
+.PP
+\fBtickit_term_teardown\fP() is similar to \fBtickit_term_stop\fP() except that it is intended to be used for final shutdown before the application itself terminates. This ensures that the terminal is restored to its original state, ahead of the application outputting any final exit message for the user to read. After this function has returned, no other functions on the terminal instance may be called.
 .SH "SEE ALSO"
 .BR tickit_term_build (3),
 .BR tickit_term_setctl_int (3),