lib/libcurses/curses_tty.3

   1 .\"     $NetBSD: curses_tty.3,v 1.8 2004/03/16 19:27:35 snj 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 June 13, 2003
  34 .Dt CURSES_TTY 3
  35 .Os
  36 .Sh NAME
  37 .Nm curses_tty ,
  38 .Nm beep ,
  39 .Nm flash ,
  40 .Nm curs_set ,
  41 .Nm def_prog_mode ,
  42 .Nm reset_prog_mode ,
  43 .Nm def_shell_mode ,
  44 .Nm reset_shell_mode ,
  45 .Nm echo ,
  46 .Nm noecho ,
  47 .Nm delay_output ,
  48 .Nm erasechar ,
  49 .Nm flushinp ,
  50 .Nm gettmode ,
  51 .Nm halfdelay ,
  52 .Nm has_ic ,
  53 .Nm has_il ,
  54 .Nm idcok ,
  55 .Nm idlok ,
  56 .Nm intrflush ,
  57 .Nm noqiflush ,
  58 .Nm qiflush ,
  59 .Nm killchar ,
  60 .Nm meta ,
  61 .Nm napms ,
  62 .Nm nl ,
  63 .Nm nonl ,
  64 .Nm cbreak ,
  65 .Nm nocbreak ,
  66 .Nm raw ,
  67 .Nm noraw ,
  68 .Nm savetty ,
  69 .Nm resetty
  70 .Nd curses terminal manipulation routines
  71 .Sh LIBRARY
  72 .Lb libcurses
  73 .Sh SYNOPSIS
  74 .In curses.h
  75 .Ft int
  76 .Fn beep "void"
  77 .Ft int
  78 .Fn flash "void"
  79 .Ft int
  80 .Fn curs_set "int visibility"
  81 .Ft int
  82 .Fn def_prog_mode "void"
  83 .Ft int
  84 .Fn reset_prog_mode "void"
  85 .Ft int
  86 .Fn def_shell_mode "void"
  87 .Ft int
  88 .Fn reset_shell_mode "void"
  89 .Ft int
  90 .Fn echo "void"
  91 .Ft int
  92 .Fn noecho "void"
  93 .Ft int
  94 .Fn delay_output "int ms"
  95 .Ft char
  96 .Fn erasechar "void"
  97 .Ft int
  98 .Fn flushinp "void"
  99 .Ft int
 100 .Fn gettmode "void"
 101 .Ft int
 102 .Fn has_ic "void"
 103 .Ft int
 104 .Fn has_il "void"
 105 .Ft int
 106 .Fn idcok "WINDOW *win" "boolf flag"
 107 .Ft int
 108 .Fn idlok "WINDOW *win" "boolf flag"
 109 .Ft int
 110 .Fn intrflush "WINDOW *win" "boolf flag"
 111 .Ft void
 112 .Fn noqiflush "void"
 113 .Ft void
 114 .Fn qiflush "void"
 115 .Ft char
 116 .Fn killchar "void"
 117 .Ft int
 118 .Fn meta "WINDOW *win" "boolf flag"
 119 .Ft int
 120 .Fn napms "int ms"
 121 .Ft int
 122 .Fn nl "void"
 123 .Ft int
 124 .Fn nonl "void"
 125 .Ft int
 126 .Fn cbreak "void"
 127 .Ft int
 128 .Fn nocbreak "void"
 129 .Ft int
 130 .Fn halfdelay "int"
 131 .Ft int
 132 .Fn raw "void"
 133 .Ft int
 134 .Fn noraw "void"
 135 .Ft int
 136 .Fn savetty "void"
 137 .Ft int
 138 .Fn resetty "void"
 139 .Sh DESCRIPTION
 140 These functions manipulate curses terminal settings.
 141 .Pp
 142 The
 143 .Fn beep
 144 function rings the terminal bell, if this is possible.
 145 Failing that, the terminal screen will be flashed.
 146 If neither of these are possible, then no action will be taken.
 147 .Fn flash
 148 will flash the terminal screen if possible.
 149 Failing that, the terminal bell will be rung.
 150 If neither of these are possible then no action will be taken.
 151 .Pp
 152 The cursor
 153 visibility can be set by calling
 154 .Fn curs_set .
 155 The following visibility settings are valid for
 156 .Fn curs_set :
 157 .Pp
 158 .Bl -tag -width visibility -compact -offset indent
 159 .It Visibility
 160 Effect
 161 .It 0
 162 cursor is invisible.
 163 .It 1
 164 cursor is normal visibility
 165 .It 2
 166 cursor is high visibility
 167 .El
 168 .Pp
 169 A successful call to
 170 .Fn curs_set
 171 will return the previous visibility setting for the cursor.
 172 .Pp
 173 The
 174 .Fn delay_output
 175 function pauses the output to the terminal by sending the appropriate
 176 number of terminal pad characters such that the transmission time of
 177 the pad characters will take
 178 .Fa ms
 179 milliseconds.
 180 .Pp
 181 Calling
 182 .Fn def_prog_mode
 183 will cause the current terminal curses setting to be saved.
 184 A subsequent call to
 185 .Fn reset_prog_mode ,
 186 will restore the saved settings.
 187 This is useful when calls to external programs are made that may
 188 reset the terminal characteristics.
 189 .Pp
 190 The
 191 .Fn def_shell_mode
 192 function saves the current terminal line settings.
 193 These settings are the ones that will be restored when the curses
 194 application exits.
 195 Conversely,
 196 .Fn reset_shell_mode
 197 will save the current terminal curses settings for later restoration and
 198 restores the previously saved terminal line settings.
 199 .Pp
 200 The
 201 .Fn echo
 202 function turns on curses echo mode, characters entered will be echoed
 203 to the terminal by curses.
 204 The
 205 .Fn noecho
 206 function disables this feature.
 207 .Pp
 208 The current erase character for the terminal can be determined by
 209 calling the
 210 .Fn erasechar
 211 function.
 212 .Pp
 213 The
 214 .Fn flushinp
 215 function discards any pending input for the current screen.
 216 .Pp
 217 The modes
 218 for the current terminal can be reset by calling
 219 .Fn gettmode ,
 220 this will perform the initialisation on the terminal that is normally
 221 done by curses at start up.
 222 .Pp
 223 The
 224 .Fn has_ic
 225 function returns either
 226 .Dv TRUE
 227 or
 228 .Dv FALSE
 229 depending on whether or not the terminal has a insert character
 230 capability or not.
 231 Similarly the
 232 .Fn has_il
 233 function does the same test but for a insert line capability.
 234 .Pp
 235 The use of the insert character capability in curses operations can be
 236 enabled or disabled by calling
 237 .Fn idcok
 238 on the desired window.
 239 Similarly, the use of the insert line capability can be controlled using the
 240 .Fn idlok
 241 function.
 242 .Pp
 243 The
 244 .Fn intrflush
 245 function controls whether or not a flush of the input buffer is
 246 performed when an interrupt key (kill, suspend or quit) is pressed.
 247 The
 248 .Fa win
 249 parameter is ignored.
 250 The
 251 .Fn noqiflush
 252 function is equivalent to
 253 .Fn intrflush stdscr FALSE .
 254 The
 255 .Fn qiflush
 256 function is equivalent to
 257 .Fn intrflush stdscr TRUE .
 258 .Pp
 259 The character that performs the line kill function can be determined
 260 by calling the
 261 .Fn killchar
 262 function.
 263 .Pp
 264 The
 265 .Fn meta
 266 function turns on and off the generation of 8 bit characters by the
 267 terminal, if
 268 .Fa flag
 269 is
 270 .Dv FALSE
 271 then only 7 bit characters will be returned, if
 272 .Fa flag
 273 is
 274 .Dv TRUE
 275 then 8 bit characters will be returned by the terminal.
 276 .Pp
 277 The
 278 .Fn napms
 279 causes the application to sleep for the number of milliseconds
 280 specified by
 281 .Fa ms .
 282 .Pp
 283 Calling
 284 .Fn nl
 285 will cause curses to map all carriage returns to newlines on input,
 286 this functionality is enabled by default.
 287 The
 288 .Fn nonl
 289 function disables this behaviour.
 290 .Pp
 291 The
 292 .Fn cbreak
 293 function will put the terminal into cbreak mode, which means that
 294 characters will be returned one at a time instead of waiting for a
 295 newline character, line discipline processing will be performed.
 296 The
 297 .Fn nocbreak
 298 function disables this mode.
 299 .Pp
 300 Calling
 301 .Fn halfdelay
 302 puts the terminal into the same mode as
 303 .Fn cbreak
 304 with the exception that if no character is received within the specified
 305 number of tenths of a second then the input routine will return
 306 .Er ERR .
 307 This mode can be cancelled by calling
 308 .Fn nocbreak .
 309 The valid range for the timeout is from 1 to 255 tenths of a second.
 310 .Pp
 311 The
 312 .Fn noraw
 313 function sets the input mode for the current terminal into Cooked mode,
 314 that is input character translation and signal character processing is
 315 performed.
 316 The
 317 .Fn raw
 318 function puts the terminal into Raw mode, no input character
 319 translation is done nor is signal character processing.
 320 .Pp
 321 The terminal
 322 tty flags can be saved by calling
 323 .Fn savetty
 324 and may be restored by calling
 325 .Fn resetty ,
 326 the use of these functions is discouraged as they may cause the
 327 terminal to be put into a state that is incompatible with curses
 328 operation.
 329 .Sh RETURN VALUES
 330 Functions returning pointers will return
 331 .Dv NULL
 332 if an error is detected.
 333 The functions that return an int will return one of the following
 334 values:
 335 .Pp
 336 .Bl -tag -width ERR -compact
 337 .It Er OK
 338 The function completed successfully.
 339 .It Er ERR
 340 An error occurred in the function.
 341 .El
 342 .Sh SEE ALSO
 343 .Xr getch 3 ,
 344 .Xr termios 4
 345 .Sh NOTES
 346 The
 347 .Fn idcok
 348 and
 349 .Fn idlok
 350 currently have no effect on the curses code at all, currently curses
 351 will always use the terminal insert character and insert line
 352 capabilities if available.
 353 .Sh STANDARDS
 354 The
 355 .Nx
 356 Curses library complies with the X/Open Curses specification, part of the
 357 Single Unix Specification.
 358 .Sh HISTORY
 359 The Curses package appeared in
 360 .Bx 4.0 .