Why do I need to call `clear` after `initscr` with ncurses?

Question

I have solved this problem in the sense I have code that does what I want, but I don't understand why it is necessary to do what I do, and I cannot see this behaviour documented, so I wonder if someone could explain why?

I am actually "porting" ncurses to Forth. More correctly I am writing some RISC-V assembly that lightly wraps around the C library calls to give Forth users an interface to ncurses.

This is what the code looks like in Forth:

: hello S" Hello, World!" ;
: goodbye S" Goodbye, World! " ;
: garish 1 color_red color_yellow init_pair ;
: cool 2 color_cyan color_black init_pair ;
: doit initscr clear start_color garish cool 1 color_pair attron 10 10 movew hello drop printw refresh getch 1 color_pair attroff ;
: endit 2 color_pair attron 30 30 movew goodbye drop printw refresh getch 2 color_pair attroff endwin ;
doit
endit

For those who don't know Forth this defines a few words then calls the doit and endit words to actually execute the program. But this isn't a question about Forth but about why I need to call clear (which is simply a wrapper around a call to the ncurses clear call) after I call initscr (again just a simple wrapper around a call to the ncurses function).

The assembly is shown below. 'CODEEND' and 'CODEHEADER' are macros that generate Forth function headings and 'TAILMOD' generates the return to the loop code - but the key point is you can see these are very light wrappers around the C calls:

      CODEEND INITSCR, 0x01
      #(--)
      call initscr
      la t0, STDSCR                   #store stdscr
      sd a0, 0(t0)
      TAILMOD t1

      CODEHEADER CLEAR, INITSCR, 0x01
      #( -- )
      call clear
      TAILMOD t1

If I don't call clear , then on every subsequent call of the doit endit pair I just see the previous output - ie initscr has not cleared the screen without this explicit call to clear .

Am I right in thinking that initscr should normally clear the screen on every invocation (at the next call of refresh )? Is it just a function of my terminal type (this is a tty over ssh in this case) that I have to call clear or is there something else at work here?

Adding Just to be totally clear, I know the documentation says a call to refresh is required to clear the screen and I have done that but it doesn't work - that is implicit in the code I've posted where there is an explicit refresh but I am adding this to make it obvious to people who maybe don't grok Forth. (Originally where the clear is there was a refresh but it does not clear the screen on subsequent calls.)

Answer 1

Per manpage :

initscr also causes the first call to refresh(3x) to clear the screen.

You won't see any change on the screen until that refresh . Some functions (such asgetch ) do a refresh as a side-effect.