1.\" $NetBSD: curses_inch.3,v 1.10 2004/04/21 06:24:32 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 April 18, 2004 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 mvinchnstr , 42.Nm winchnstr , 43.Nm mvwinchnstr , 44.Nm inchstr , 45.Nm mvinchstr , 46.Nm winchstr , 47.Nm mvwinchstr , 48.Nm innstr , 49.Nm winnstr , 50.Nm mvinnstr , 51.Nm mvwinnstr , 52.Nm instr , 53.Nm winstr 54.Nm mvinstr , 55.Nm mvwinstr 56.Nd curses read screen contents routines 57.Sh LIBRARY 58.Lb libcurses 59.Sh SYNOPSIS 60.In curses.h 61.Ft chtype 62.Fn inch "void" 63.Ft chtype 64.Fn winch "WINDOW *win" 65.Ft int 66.Fn inchnstr "chtype *chars" "int n" 67.Ft int 68.Fn mvinchnstr "int y" "int x" "chtype *chstr" "int n" 69.Ft int 70.Fn winchnstr "WINDOW *win" "chtype *chars" "int n" 71.Ft int 72.Fn mvwinchnstr "WINDOW *win" "int y" "int x" "chtype *chstr" "int n" 73.Ft int 74.Fn inchstr "chtype *chars" 75.Ft int 76.Fn mvinchstr "int y" "int x" "chtype *chstr" 77.Ft int 78.Fn winchstr "WINDOW *win" "chtype *chars" 79.Ft int 80.Ft mvwinchstr "WINDOW *win" "int y" "int x" "chtype *chstr" 81.Ft int 82.Fn innstr "char *str" "int n" 83.Ft int 84.Fn winnstr "WINDOW *win" "char *str" "int n" 85.Ft int 86.Fn mvinnstr "int y" "int x" "char *str" "int n" 87.Ft int 88.Fn mvwinnstr "WINDOW *win" "int y" "int x" "char *str" "int n" 89.Ft int 90.Fn instr "char *str" 91.Ft int 92.Fn winstr "WINDOW *win" "char *str" 93.Ft int 94.Fn mvinstr "int y" "int x" "char *str" 95.Ft int 96.Fn mvwinstr "WINDOW *win" "int y" "int x" "char *str" 97.Sh DESCRIPTION 98These functions read the contents of 99.Dv stdscr 100or of the specified window. 101.Pp 102The 103.Fn inch 104function returns the character that is displayed on 105.Dv stdscr 106at the current cursor position. 107.Pp 108The 109.Fn winch 110function is the same as the 111.Fn inch 112function, excepting that the character is read from window specified by 113.Fa win . 114.Pp 115The 116.Fn inchnstr 117function fills an array of 118.Ft chtype 119with characters read from 120.Dv stdscr , 121the characters are read starting from the current cursor position and 122continuing until either n \- 1 characters are read or the right hand 123side of the screen is reached. 124The resulting character array will be 125.Dv NULL 126terminated. 127.Pp 128The 129.Fn winchnstr 130function is the same as 131.Fn inchnstr 132excepting that the characters are read from the window specified by 133.Fa win . 134.Pp 135The 136.Fn inchstr 137and 138.Fn winchstr 139functions are the same as the 140.Fn inchnstr 141and 142.Fn winchnstr 143functions, respectively, excepting that they do not limit the number 144of characters read. 145The characters returned are those from the current starting position to 146the right hand side of the screen. 147The use of 148.Fn inchstr 149and 150.Fn winchstr 151is not recommended as the character buffer can be overflowed. 152.Pp 153The 154.Fn innstr 155function 156is similar to the 157.Fn inchstr 158function, excepting that the array of characters returned is stripped of all 159the curses attributes making it a plain character string. 160.Pp 161The 162.Fn mvinchstr , 163.Fn mvinchnstr , 164.Fn mvwinchstr , 165and 166.Fn mvwinchnstr 167functions are the same as the 168.Fn inchstr , 169.Fn inchnstr , 170.Fn winchstr , 171and 172.Fn winchstr 173functions, respectively, except that 174.Fn wmove 175is called to move the cursor to the position specified by 176.Fa y , 177.Fa x 178before the output is printed on the window. 179Likewise, the 180.Fn mvinstr , 181.Fn mvinnstr , 182.Fn mvwinstr , 183and 184.Fn mvwinnstr 185functions are the same as the 186.Fn instr , 187.Fn innstr , 188.Fn winstr , 189and 190.Fn winstr 191functions, respectively, except that 192.Fn wmove 193is called to move the cursor to the position specified by 194.Fa y , 195.Fa x 196before the output is printed on the window. 197.Pp 198The 199.Fn winnstr 200function is the same as the 201.Fn innstr 202function, excepting that characters are read from the window specified by 203.Fa win . 204.Pp 205The 206.Fn instr 207and 208.Fn winstr 209functions 210are the same as the 211.Fn innstr 212and 213.Fn winnstr 214functions, respectively, excepting that there are no limits placed on the 215size of the returned string, which may cause buffer overflows. 216For this reason, the use of 217.Fn instr 218and 219.Fn winstr 220is not recommended. 221.Sh RETURN VALUES 222Functions returning pointers will return 223.Dv NULL 224if an error is detected. 225The functions that return an int will return one of the following 226values: 227.Pp 228.Bl -tag -width ERR -compact 229.It Er OK 230The function completed successfully. 231.It Er ERR 232An error occurred in the function. 233.El 234.Sh SEE ALSO 235.Xr curses_addch 3 , 236.Xr curses_addstr 3 , 237.Xr curses_attributes 3 , 238.Xr curses_insertch 3 239.Sh STANDARDS 240The 241.Nx 242Curses library complies with the X/Open Curses specification, part 243of the Single Unix Specification. 244.Sh NOTES 245The 246.Fn inchnstr 247and 248.Fn innstr 249function read at most n \- 1 characters from the screen so as to leave 250room for 251.Dv NULL 252termination. 253The X/Open specification is unclear as to whether or not this is the correct 254behaviour. 255.Sh HISTORY 256The Curses package appeared in 257.Bx 4.0 . 258