1.\" $NetBSD: curses_screen.3,v 1.14 2007/10/25 20:42:07 jdc Exp $ 2.\" 3.\" Copyright (c) 2002 4.\" Brett Lymn (blymn@NetBSD.org, brett_lymn@yahoo.com.au) 5.\" 6.\" This code is donated to the NetBSD Foundation by the Author. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. The name of the Author may not be used to endorse or promote 17.\" products derived from this software without specific prior written 18.\" permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" 33.Dd October 24, 2007 34.Dt CURSES_SCREEN 3 35.Os 36.Sh NAME 37.Nm curses_screen , 38.Nm newterm , 39.Nm set_term , 40.Nm delscreen , 41.Nm endwin , 42.Nm initscr , 43.Nm isendwin , 44.Nm resizeterm , 45.Nm setterm 46.Nd curses terminal and screen routines 47.Sh LIBRARY 48.Lb libcurses 49.Sh SYNOPSIS 50.In curses.h 51.Ft SCREEN * 52.Fn newterm "char *type" "FILE *outfd" "FILE *infd" 53.Ft SCREEN * 54.Fn set_term "SCREEN *screen" 55.Ft void 56.Fn delscreen "SCREEN *screen" 57.Ft int 58.Fn endwin "void" 59.Ft WINDOW * 60.Fn initscr "void" 61.Ft bool 62.Fn isendwin "void" 63.Ft int 64.Fn resizeterm "int lines" "int cols" 65.Ft int 66.Fn setterm "char *name" 67.Pp 68.Va extern int LINES ; 69.Pp 70.Va extern int COLS ; 71.Sh DESCRIPTION 72These functions initialize terminals and screens. 73.Pp 74The 75.Fn newterm 76function initialises the curses data structures and pointers ready for 77use by curses. 78The 79.Fa type 80argument points to a 81.Xr termcap 5 82capability name, or it may be 83.Dv NULL 84in which case the TERM environment variable is used. 85The 86.Fa outfd 87and 88.Fa infd 89are the output and input file descriptors for the terminal. 90The 91.Fn newterm 92function must only be called once per terminal. 93.Pp 94The 95.Fn set_term 96function can be used to switch between the screens defined by calling 97.Fn newterm , 98a pointer to the previous screen structure that was in use will be 99returned on success. 100.Pp 101Calling 102.Fn delscreen 103will destroy the given screen and free all allocated resources. 104.Pp 105Calling 106.Fn endwin 107will end the curses session and restore the saved terminal settings. 108.Pp 109The curses session must be initialised by calling 110.Fn initscr 111which saves the current terminal state and sets up the terminal and 112internal data structures to support the curses application. 113This 114function call must be, with few exceptions, the first Curses library 115call made. 116The exception to this rule is the 117.Fn newterm 118call which may be called prior to 119.Fn initscr . 120The size of the curses screen is determined by checking the 121.Xr tty 4 122size and then the 123.Xr termcap 5 124entries for the terminal type. 125If the environment variables 126.Va LINES 127or 128.Va COLS 129are set, then these will be used instead. 130.Pp 131When either 132.Fn newterm 133or 134.Fn initscr 135are called, the Curses library sets up signal handlers for 136.Dv SIGTSTP 137and 138.Dv SIGWINCH . 139If a signal handler is already installed for 140.Dv SIGWINCH , 141this will also be called when the Curses library handler is called. 142.Pp 143The 144.Fn isendwin 145function can be used to determine whether or not a refresh of the 146screen has occurred since the last call to 147.Fn endwin . 148.Pp 149The size of the screen may be changed by calling 150.Fn resizeterm 151with the updated number of lines and columns. 152This will resize the curses internal data structures to accommodate the 153changed terminal geometry. 154The 155.Dv curscr 156and 157.Dv stdscr 158windows and any of their subwindows will be resized to fit the new 159screen size. 160The application must redraw the screen after a call to 161.Fn resizeterm . 162.Pp 163The 164.Fn setterm 165function sets the terminal type for the current screen to the one 166passed, initialising all the curses internal data structures with 167information related to the named terminal. 168The 169.Fa name 170argument must be a valid name or alias in the 171.Xr termcap 5 172database for this function to succeed. 173.Sh RETURN VALUES 174Functions returning pointers will return 175.Dv NULL 176if an error is detected. 177The functions that return an int will return one of the following 178values: 179.Pp 180.Bl -tag -width ERR -compact 181.It Er OK 182The function completed successfully. 183.It Er ERR 184An error occurred in the function. 185.El 186.Sh SEE ALSO 187.Xr curses_window 3 , 188.Xr tty 4 , 189.Xr termcap 5 , 190.Xr signal 7 191.Sh STANDARDS 192The 193.Nx 194Curses library complies with the X/Open Curses specification, part of the 195Single Unix Specification. 196.Sh HISTORY 197The Curses package appeared in 198.Bx 4.0 . 199The 200.Fn resizeterm 201function is a 202.Em ncurses 203extension to the Curses library and was added in 204.Nx 1.6 . 205