1.\" $NetBSD: curses_screen.3,v 1.3 2002/12/05 19:13:12 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 August 12, 2002 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.Fd #include \*[Lt]curses.h\*[Gt] 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 int 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.Sh DESCRIPTION 68These functions initialize terminals and screens. 69.Pp 70The 71.Fn newterm 72function initialises the curses datastructures and pointers ready for 73use by curses. 74The 75.Fa type 76argument points to a 77.Xr termcap 5 78capability name, or it may be 79.Dv NULL 80in which case the TERM environment variable is used. 81The 82.Fa outfd 83and 84.Fa infd 85are the output and input file descriptors for the terminal. 86The 87.Fn newterm 88function must only be called once per terminal. 89.Pp 90The 91.Fn set_term 92function can be used to switch between the screens defined by calling 93.Fn newterm , 94a pointer to the previous screen structure that was in use will be 95returned on success. 96.Pp 97Calling 98.Fn delscreen 99will destroy the given screen and free all allocated resources. 100.Pp 101Calling 102.Fn endwin 103will end the curses session and restore the saved terminal settings. 104.Pp 105The curses session must be initialised by calling 106.Fn initscr 107which saves the current terminal state and sets up the terminal and 108internal data structures to support the curses application. 109This 110function call must be, with few exceptions, the first curses library 111call made. 112The exception to this rule is the 113.Fn newterm 114call which may be called prior to 115.Fn initscr . 116.Pp 117The 118.Fn isendwin 119function can be used to determine whether or not a refresh of the 120screen has occurred since the last call to 121.Fn endwin . 122.Pp 123The size of the screen may be changed by calling 124.Fn resizeterm 125with the updated number of lines and columns. 126This will resize the curses internal data structures to accomodate the 127changed terminal geometry. 128The application must redraw the screen after a call to 129.Fn resizeterm . 130.Pp 131The 132.Fn setterm 133function sets the terminal type for the current screen to the one 134passed, initialising all the curses internal data structures with 135information related to the named terminal. 136The 137.Fa name 138argument must be a valid name or alias in the 139.Xr termcap 5 140database for this function to succeed. 141.Sh RETURN VALUES 142Functions returning pointers will return 143.Dv NULL 144if an error is detected. 145The functions that return an int will return one of the following 146values: 147.Pp 148.Bl -tag -width ERR -compact 149.It Er OK 150The function completed successfully. 151.It Er ERR 152An error occurred in the function. 153.El 154.Sh SEE ALSO 155.Xr curses_window 3 , 156.Xr termcap 5 157.Sh STANDARDS 158The 159.Lb libcurses 160library complies with the X/Open Curses specification, part of the 161Single Unix Specification. 162.Nx 163.Sh HISTORY 164The Curses package appeared in 165.Bx 4.0 . 166The 167.Fn resizeterm 168function is a ncurses extension to the Curses library and was added in 169.Nx 1.6 . 170