What do ncurses_def_shell_mode() and ncurses_def_prog_mode() do exactly?

Question

Using php ncurses, I'm curious to understand exactly what ncurses_def_shell_mode() and ncurses_def_prog_mode() functions do specifically. They're not documented in the PHP manual and what little I did stumble upon in man ncurses didn't help.

If I call ncurses_def_shell_mode() and then reset with ncurses_reset_shell_mode() before calling ncurses_end(), which according to the extension's source should call endwin in ncurses, the terminal cursor is still somehow lost.

<?php
ncurses_init(); // start ncurses window
ncurses_def_shell_mode();

sleep(2); // print some stuff here

ncurses_reset_shell_mode();

ncurses_end(); // clean up and get out
exit;
?>

I tried with and without, ncurses_def_shell_mode() and ncurses_def_prog_mode(), but somehow the window is not reset properly on exit despite properly calling reset. Am I misunderstanding how these functions are supposed to work? I was able to dig up very little information to glean more insight into their proper usage.

I know that ncurses may be archaic, but that just makes it that much more difficult to know how to use it properly.

Expected behavior here is that after calling ncurses_reset_shell_mode() or ncurses_reset_prog_mode() the shell or prog window should go back to its previously saved state as it was before.

The actual behavior seems to be that the shell is an a broken state upon exiting. The cursor doesn't blink, typing does not reveal anything in the terminal. However, the terminal is receiving input properly, because typing in commands and hitting enter still works.

Answer 1

php ncurses is a wrapper around ncurses. The functions you are asking about are documented in more detail in the ncurses manual pages, e.g., curs_kernel(3x). That says that these functions save/restore terminal modes. Those correspond to curses settings in termios (terminal I/O settings).

Terminal I/O settings do not include blinking cursor (that is done using a terminal-specific escape sequence). For echo, the manual page can help:

The def_prog_mode and def_shell_mode routines save the current terminal modes as the "program" (in curses) or "shell" (not in curses) state for use by the reset_prog_mode and reset_shell_mode routines. This is done each screen context allocated by newterm().

When ncurses starts, e.g., initscr (ncurses_init()), it saves the shell-mode and initializes the prog-mode, basically putting the terminal into raw mode to better control it.

Your call to ncurses_def_shell_mode();

• saves the prog-mode as shell-mode, and
• when "restoring" to that using ncurses_reset_shell_mode();,
• it has no effect: the terminal remains in raw mode, with echo disabled.

Further reading:

• PECL /[svn]/pecl/ncurses/trunk
• ncurses_functions, where ncurses_init() is defined.