lib/libcurses/curses_inch.3

   1 .\"     $NetBSD: curses_inch.3,v 1.12 2011/08/07 11:37:06 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 7, 2011
  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
  98 These functions read the contents of
  99 .Dv stdscr
 100 or of the specified window.
 101 .Pp
 102 The
 103 .Fn inch
 104 function returns the character that is displayed on
 105 .Dv stdscr
 106 at the current cursor position.
 107 .Pp
 108 The
 109 .Fn winch
 110 function is the same as the
 111 .Fn inch
 112 function, excepting that the character is read from window specified by
 113 .Fa win .
 114 .Pp
 115 The
 116 .Fn inchnstr
 117 function fills an array of
 118 .Ft chtype
 119 with characters read from
 120 .Dv stdscr ,
 121 the characters are read starting from the current cursor position and
 122 continuing until either n \- 1 characters are read or the right hand
 123 side of the screen is reached.
 124 The resulting character array will be
 125 .Dv NULL
 126 terminated.
 127 .Pp
 128 The
 129 .Fn winchnstr
 130 function is the same as
 131 .Fn inchnstr
 132 excepting that the characters are read from the window specified by
 133 .Fa win .
 134 .Pp
 135 The
 136 .Fn inchstr
 137 and
 138 .Fn winchstr
 139 functions are the same as the
 140 .Fn inchnstr
 141 and
 142 .Fn winchnstr
 143 functions, respectively, excepting that they do not limit the number
 144 of characters read.
 145 The characters returned are those from the current starting position to
 146 the right hand side of the screen.
 147 The use of
 148 .Fn inchstr
 149 and
 150 .Fn winchstr
 151 is not recommended as the character buffer can be overflowed.
 152 .Pp
 153 The
 154 .Fn innstr
 155 function
 156 is similar to the
 157 .Fn inchstr
 158 function, excepting that the array of characters returned is stripped of all
 159 the curses attributes making it a plain character string.
 160 .Pp
 161 The
 162 .Fn mvinchstr ,
 163 .Fn mvinchnstr ,
 164 .Fn mvwinchstr ,
 165 and
 166 .Fn mvwinchnstr
 167 functions are the same as the
 168 .Fn inchstr ,
 169 .Fn inchnstr ,
 170 .Fn winchstr ,
 171 and
 172 .Fn winchstr
 173 functions, respectively, except that
 174 .Fn wmove
 175 is called to move the cursor to the position specified by
 176 .Fa y ,
 177 .Fa x
 178 before the output is printed on the window.
 179 Likewise, the
 180 .Fn mvinstr ,
 181 .Fn mvinnstr ,
 182 .Fn mvwinstr ,
 183 and
 184 .Fn mvwinnstr
 185 functions are the same as the
 186 .Fn instr ,
 187 .Fn innstr ,
 188 .Fn winstr ,
 189 and
 190 .Fn winstr
 191 functions, respectively, except that
 192 .Fn wmove
 193 is called to move the cursor to the position specified by
 194 .Fa y ,
 195 .Fa x
 196 before the output is printed on the window.
 197 .Pp
 198 The
 199 .Fn winnstr
 200 function is the same as the
 201 .Fn innstr
 202 function, excepting that characters are read from the window specified by
 203 .Fa win .
 204 .Pp
 205 The
 206 .Fn instr
 207 and
 208 .Fn winstr
 209 functions
 210 are the same as the
 211 .Fn innstr
 212 and
 213 .Fn winnstr
 214 functions, respectively, excepting that there are no limits placed on the
 215 size of the returned string, which may cause buffer overflows.
 216 For this reason, the use of
 217 .Fn instr
 218 and
 219 .Fn winstr
 220 is not recommended.
 221 .Sh RETURN VALUES
 222 If the calls
 223 .Fn innstr ,
 224 .Fn mvinnstr ,
 225 .Fn mvwinnstr ,
 226 and
 227 .Fn winnstr
 228 succeed then they will return the number of characters actually read.
 229 Functions returning pointers will return
 230 .Dv NULL
 231 if an error is detected.
 232 The functions that return an int will return one of the following
 233 values:
 234 .Pp
 235 .Bl -tag -width ERR -compact
 236 .It Er OK
 237 The function completed successfully.
 238 .It Er ERR
 239 An error occurred in the function.
 240 .El
 241 .Sh SEE ALSO
 242 .Xr curses_addch 3 ,
 243 .Xr curses_addstr 3 ,
 244 .Xr curses_attributes 3 ,
 245 .Xr curses_insertch 3
 246 .Sh STANDARDS
 247 The
 248 .Nx
 249 Curses library complies with the X/Open Curses specification, part
 250 of the Single Unix Specification.
 251 .Sh NOTES
 252 The
 253 .Fn inchnstr
 254 and
 255 .Fn innstr
 256 function read at most n \- 1 characters from the screen so as to leave
 257 room for
 258 .Dv NULL
 259 termination.
 260 The X/Open specification is unclear as to whether or not this is the correct
 261 behaviour.
 262 .Sh HISTORY
 263 The Curses package appeared in
 264 .Bx 4.0 .