1.\" $NetBSD: curses_screen.3,v 1.9 2003/04/16 13:35:01 wiz 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 April 8, 2003 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 datastructures 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 131The 132.Fn isendwin 133function can be used to determine whether or not a refresh of the 134screen has occurred since the last call to 135.Fn endwin . 136.Pp 137The size of the screen may be changed by calling 138.Fn resizeterm 139with the updated number of lines and columns. 140This will resize the curses internal data structures to accomodate the 141changed terminal geometry. 142The application must redraw the screen after a call to 143.Fn resizeterm . 144.Pp 145The 146.Fn setterm 147function sets the terminal type for the current screen to the one 148passed, initialising all the curses internal data structures with 149information related to the named terminal. 150The 151.Fa name 152argument must be a valid name or alias in the 153.Xr termcap 5 154database for this function to succeed. 155.Sh RETURN VALUES 156Functions returning pointers will return 157.Dv NULL 158if an error is detected. 159The functions that return an int will return one of the following 160values: 161.Pp 162.Bl -tag -width ERR -compact 163.It Er OK 164The function completed successfully. 165.It Er ERR 166An error occurred in the function. 167.El 168.Sh SEE ALSO 169.Xr curses_window 3 , 170.Xr tty 4 , 171.Xr termcap 5 172.Sh STANDARDS 173The 174.Nx 175Curses library complies with the X/Open Curses specification, part of the 176Single Unix Specification. 177.Sh HISTORY 178The Curses package appeared in 179.Bx 4.0 . 180The 181.Fn resizeterm 182function is a ncurses extension to the Curses library and was added in 183.Nx 1.6 . 184