1.\" $NetBSD: curses_inch.3,v 1.2 2002/10/21 14:11:52 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 August 12, 2002 34.Dt CURSES_INCH 3 35.Os 36.Sh NAME 37.Nm curses_inch , 38.Nm inch , 39.Nm winch , 40.Nm inchnstr , 41.Nm winchnstr , 42.Nm inchstr , 43.Nm winchstr , 44.Nm innstr , 45.Nm winnstr 46.Nm instr , 47.Nm winstr 48.Nd curses read screen contents routines 49.Sh LIBRARY 50.Lb libcurses 51.Sh SYNOPSIS 52.Fd #include \*[Lt]curses.h\*[Gt] 53.Ft chtype 54.Fn inch "void" 55.Ft chtype 56.Fn winch "WINDOW *win" 57.Ft int 58.Fn inchnstr "chtype *chars" "int n" 59.Ft int 60.Fn winchnstr "WINDOW *win" "chtype *chars" "int n" 61.Ft int 62.Fn inchstr "chtype *chars" 63.Ft int 64.Fn winchstr "WINDOW *win" "chtype *chars" 65.Ft int 66.Fn innstr "char *str" "int n" 67.Ft int 68.Fn winnstr "WINDOW *win" "char *str" "int n" 69.Ft int 70.Fn instr "char *str" 71.Ft int 72.Fn winstr "WINDOW *window" "char *str" 73.Sh DESCRIPTION 74These functions read the contents of 75.Dv stdscr 76or of the specified window. 77.Pp 78The 79.Fn inch 80function returns the character that is displayed on 81.Dv stdscr 82at the current cursor position. 83.Pp 84The 85.Fn winch 86function is the same as the 87.Fn inch 88function, excepting that the character is read from window specified by 89.Fa win . 90.Pp 91The 92.Fn inchnstr 93function fills an an arrray of 94.Ft chtype 95with characters read from 96.Dv stdscr , 97the characters are read starting from the current cursor position and 98continuing until either n \- 1 characters are read or the right hand 99side of the screen is reached. 100The resulting character array will be 101.Dv NULL 102terminated. 103.Pp 104The 105.Fn winchnstr 106function is the same as 107.Fn inchnstr 108excepting that the characters are read from the window specified by 109.Fa win . 110.Pp 111The 112.Fn inchstr 113and 114.Fn winchstr 115functions are the same as the 116.Fn inchnstr 117and 118.Fn winchnstr 119functions, respectively, excepting that they do not limit the number 120of characters read. 121The characters returned are those from the current starting position to 122the right hand side of the screen. 123The use of 124.Fn inchstr 125and 126.Fn winchnstr 127is not recommended as the character buffer can be overflowed. 128.Pp 129The 130.Fn innstr 131function 132is similar to the 133.Fn inchstr 134function, excepting that the array of characters returned is stripped of all 135the curses attributes making it a plain character string. 136.Pp 137The 138.Fn winnstr 139function is the same as the 140.Fn innstr 141function, excepting that characters are read from the window specified by 142.Fa win . 143.Pp 144The 145.Fn instr 146and 147.Fn winstr 148functions 149are the same as the 150.Fn innstr 151and 152.Fn winnstr 153functions, respectively, excepting that there are no limits placed on the 154size of the returned string, which may cause buffer overflows. 155For this reason, the use of 156.Fn instr 157and 158.Fn winstr 159is not recommended. 160.Sh RETURN VALUES 161Functions returning pointers will return 162.Dv NULL 163if an error is detected. 164The functions that return an int will return one of the following 165values: 166.Pp 167.Bl -tag -width ERR -compact 168.It Er OK 169The function completed successfully. 170.It Er ERR 171An error occurred in the function. 172.El 173.Sh SEE ALSO 174.Xr curses_addch 3 , 175.Xr curses_addstr 3 , 176.Xr curses_attributes 3 , 177.Xr curses_insertch 3 178.Sh STANDARDS 179The 180.Nx 181Curses library complies with the X/Open Curses specification, part 182of the Single Unix Specification. 183.Sh NOTES 184The 185.Fn inchnstr 186and 187.Fn innstr 188function read at most n \- 1 characters from the screen so as to leave 189room for 190.Dv NULL 191termination. 192The X/Open specification is unclear as to whether or not this is the correct 193behaviour. 194.Sh HISTORY 195The Curses package appeared in 196.Bx 4.0 . 197