--- name: "idlok" section: "3" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["freebsd"] url: "https://new.carta.tech/clearok" --- # idlok(3) set curses output options Part of [clearok(3)](/clearok/3.md). ## NAME **clearok**, **idcok**, **idlok**, **immedok**, **leaveok**, **scrollok**, **setscrreg**, **wsetscrreg** - set *curses* output options ## SYNOPSIS ``` #include ``` **int clearok(WINDOW \*** *win***, bool** *bf***);** **void idcok(WINDOW \*** *win***, bool** *bf***);** **int idlok(WINDOW \*** *win***, bool** *bf***);** **void immedok(WINDOW \*** *win***, bool** *bf***);** **int leaveok(WINDOW \*** *win***, bool** *bf***);** **int scrollok(WINDOW \*** *win***, bool** *bf***);** **int setscrreg(int** *top***, int** *bot***);** **int wsetscrreg(WINDOW \*** *win***, int** *top***, int** *bot***);** ## DESCRIPTION **These functions configure properties of** *curses* **windows that affect their manner of output.** **Boolean-valued properties are initially** **FALSE** **except where noted.** **endwin(3X) resets any terminal modes corresponding to these** **properties;** **an application need not restore their initial values.** ### clearok **Setting** *win*'s **clearok** **property to** **TRUE** **causes the next** **wrefresh** **call on it to clear the terminal screen and redraw it entirely.** **This property is useful to restore the contents of the screen** **(perhaps because another process has written to the terminal),** **or in some cases to achieve a more pleasing visual effect.** **If** *win* **is** **curscr** **(see curs\_variables(3X)),** **the next** **wrefresh** **call on** *any* **window causes the terminal screen to clear and redraw as above.** **wrefresh** **resets this property to** **FALSE**. ### idcok **(This property defaults** **TRUE**.) **Setting** *win*'s **idcok** **property to** **FALSE** **prevents** *curses* **from using the insert/delete character capabilities of terminal types** **possessing them according to the** *terminfo* **database.** ### idlok **Setting** *win*'s **idlok** **property to** **TRUE** **causes** *curses* **to consider** **using the insert/delete line capabilities of terminal types** **possessing them according to the** *terminfo* **database.** **Enable this option** **if the application explicitly requires these operations,** **as a full-screen text editor might;** **otherwise the results may be visually annoying to the user.** ### immedok **If** **immedok** **is called with** **TRUE** **as second argument,** **changes to the window image,** **such as those caused by** **waddch**, **wclrtobot**, **or** **wscrl**, **automatically cause a call to** **wrefresh**. **Setting a window's** **immedok** **property may degrade performance considerably** **if writes are frequent.** **Calling** **immedok** **with** **FALSE** **as second argument** **restores the default behavior,** **deferring screen updates until a refresh is needed** **or explicitly directed by the application.** ### leaveok **Normally,** *curses* **leaves the hardware cursor at the library's cursor location** **of the window being refreshed.** **The** **leaveok** **option allows the cursor to be left** **wherever the update happens to leave it.** **It is useful for applications that do not employ a visible cursor,** **since it reduces the need for cursor motions.** ### scrollok **The** **scrollok** **option controls what happens when a window's cursor** **moves off the edge of the window or scrolling region,** **as a result of either** **(1) writing a newline anywhere on its bottom line,** **or** **(2) writing a character that advances the cursor to the last position** **on its bottom line.** **If disabled** (*bf* **is** **FALSE**), *curses* **leaves the cursor on the bottom line of the window.** **If enabled** (*bf* **is** **TRUE**), *curses* **scrolls the window up one line.** **(To get the physical scrolling effect on the terminal,** **the application must also enable** **idlok**). ### setscrreg, wsetscrreg **The** **wsetscrreg** **and** **setscrreg** **functions allow the application** **to set a software scrolling region in the specified window or** **stdscr**, **respectively.** **The** *top* **and** *bot* **parameters** **are the line numbers of the top and bottom margin of the scrolling** **region.** **If this option and** **scrollok** **are enabled,** **an attempt to move off the bottom margin line** **causes all lines in the scrolling region** **to scroll one line in the direction of the first line.** **Only the text of the window is scrolled.** **(This process has nothing to do** **with the scrolling region capability of the terminal,** **as found in the DEC VT100.)** **If** **idlok** **is enabled and the terminal** **has either a scrolling region or insert/delete line capability,** **they will probably be used by the output routines.** ## RETURN VALUE **The functions** **setscrreg** **and** **wsetscrreg** **return** **OK** **upon success** **and** **ERR** **upon failure.** **All other routines that return an integer always** **return** **OK**. **In** *ncurses*, **these functions fail if** - • **the** *curses* **screen has not been initialized,** - • **(for functions taking a** *WINDOW* **pointer argument)** *win* **is a null pointer,** **or** - • **(for** **setscrreg** **and** **wsetscrreg**) **the function is passed arguments describing a scrolling region** **with limits that extend outside the window boundaries.** ## NOTES **clearok**, **leaveok**, **scrollok**, **idcok**, **and** **setscrreg** **may be implemented as macros.** **Unlike the other functions described by this page,** **setscrreg** **does not accept a** pointer-to-*WINDOW* **parameter,** **but operates on** **stdscr**. **Use** **wsetscrreg** **to configure the scrolling region of a selected window.** **Historically,** **applications used** **idcok(FALSE)** **to accommodate the “magic cookie” feature** **of some terminal types;** **see subsection “Highlighting, Underlining, and Visible Bells”** **of [terminfo(5)](/terminfo/5.md).** **When updating a line,** **the presence of character cells with magic cookies in them** **made the** *curses* **library's computations of characters to be rewritten inaccurate.** **A better solution is to indicate the** **magic\_cookie\_glitch** (**xmc**) **capability in the terminal's type description.** **immedok** **is useful for windows that are used as terminal emulators.** ## PORTABILITY **X/Open Curses Issue 4 describes these functions.** **It specifies no error conditions for them.** **Some historic** *curses* **implementations,** **as an undocumented feature,** **did the equivalent of** “**clearok(**...**, 1)**” **when** **touchwin(stdstr)** **or** **clear(stdstr)** **were used.** **This trick does not work with** *ncurses*. **Early System V** *curses* **implementations specified that with** *scrollok* **enabled,** **any window modification triggering a scroll** **also forced a physical refresh.** **X/Open Curses does not require this,** **and** *ncurses* **avoids doing so to better optimize vertical motions upon a** *wrefresh*. **X/Open Curses does not mention that the cursor should be** **made invisible as a side effect of** *leaveok*. **SVr4** *curses* **documentation notes this behavior,** **but the code neglects to implement it.** **Use curs\_set(3X) to make the cursor invisible.** ## HISTORY **4BSD (1980)** **introduced** *clearok*, *leaveok*, **and** *scrollok*. **SVr2 (1984)** **supplied** *idlok*, *setscrreg*, **and** *wsetscrreg*. **SVr3.1 (1987)** **implemented** *idcok* **and** *immedok*. *ncurses* **formerly treated** *nl* **and** *nonl* **as both input** *and* **output options,** **but no longer;** **see curs\_inopts(3X).** ## SEE ALSO **curses(3X),** **curs\_addch(3X),** **curs\_clear(3X),** **curs\_initscr(3X),** **curs\_refresh(3X),** **curs\_scroll(3X),** **curs\_variables(3X)**