intro man page on Ultrix

Man page or keyword search:  
man Server   3690 pages
apropos Keyword Search (all sections)
Output format
Ultrix logo
[printable version]

intro(3cur)							   intro(3cur)

       intro - introduction to the X/Open Curses Package, which optimizes ter‐
       minal screen handling and updating

       #include <cursesX.h>
       cc [ options ] files -lcursesX [ libraries ]

       The (cursor optimization) package is the X/Open set of library routines
       used for writing screen-management programs.  Cursor optimization mini‐
       mizes the amount the cursor has to be moved around the screen in	 order
       to  update  it.	 Screen-management programs are used for tasks such as
       moving the cursor, printing a menu, dividing  a	terminal  screen  into
       windows or drawing a display on a screen for data entry and retrieval.

       The package is split into three parts: screen updating, screen updating
       with user input, and cursor motion optimization.	 Screen-updating  rou‐
       tines  are  used	 when  parts  of the screen need to be changed but the
       overall image remains the same.	The cursor motion part of the  package
       can  be used separately for tasks such as defining how the cursor moves
       in response to tabs and newline characters

       The routines do not write directly to the terminal screen (the physical
       screen):	 instead,  they	 write to a window, a two-dimensional array of
       characters which represents all or part of the terminal screen.	A win‐
       dow  can be as big as the terminal screen or any smaller size down to a
       single character.

       The header file supplies two default  windows,  (standard  screen)  and
       (current	 screen)  for  all programs using routines.  The window is the
       size of the current  terminal  screen.	The  window  is	 not  normally
       accessed directly by the screen-management program; changes are made to
       the appropriate window and then the routine is called.  The screen pro‐
       gram  keeps track of what is on the physical screen and what is on When
       is called, it compares the two screen images and then sends a stream of
       characters to the terminal to make the physical screen look like

       The  header  file  defines  to  be of the type This is a pointer to a C
       structure which includes the starting position of  the  window  on  the
       screen and the window size.

       Some  routines  are  designed  to work with a A pad is a type of window
       whose size is not restricted by the size of the screen.	Use a pad when
       you only need part of a window on the screen at any one time, for exam‐
       ple when running a spreadsheet application.

       Other windows can be created with and used instead of  for  maintaining
       several	different  screen  images, for example, one window can control
       input/output and another can display error messages.  The routine  cre‐
       ates  subwindows within windows.	 When windows overlap, the contents of
       the current screen show the most recently refreshed window.

       Among the most basic routines are and These routines are used  to  move
       the cursor around and to add characters to the default window,

       All  data  is  manipulated  using the routines provided by the library.
       You should not use routines or system calls from other libraries	 in  a
       program as they may cause undesirable results when you run the program.

       Using Curses

       The  library  has three types of routines; Main routines, TERMINFO rou‐
       tines and TERMCAP compatibility routines

       The routines are a group of routines within the library which provide a
       database	 containing  descriptions  of  many terminals that can be used
       with programs.  The termcap compatibility routines are  provided	 as  a
       conversion aid for programs using termcap.

       Most screen handling can be achieved using the Main routines.  The fol‐
       lowing hints should help you make the most of the screen-handling  rou‐

       The  header file must always be included whenever functions are used in
       a program. Note that the header file includes to enable the terminal to
       use the features provided by ULTRIX.  All the manual definitions assume
       that has been included in the code.

       The header file defines	global	variables  and	data  structures,  and
       defines	several	 of the routines as macros.  The integer variables and
       are defined so that when a program is run  on  a	 particular  terminal,
       assigns	the  vertical and horizontal dimensions of the terminal screen
       to these variables.

       A program must start by calling the routine to  allocate	 memory	 space
       for the windows.	 It should only be called once in a program, as it can
       overflow core memory if it is called repeatedly.	 The routine  is  used
       to exit from the screen-handling routines.

       Most  interactive  screen-oriented  programs  need  character-at-a-time
       input without echoing.  To achieve this, you should call:
       immediately after calling All routines that move the  cursor,  move  it
       relative	 to  the home position in the upper left corner of the screen.
       The coordinate at this position is (1,1).  Note that the vertical coor‐
       dinate  is  given  first and the horizontal coordinate is given second.
       The -1 in the example program takes the home position into  account  to
       place  the cursor on the centre line of the terminal screen.  The exam‐
       ple program displays MIDSCREEN in the centre of the  screen.   Use  the
       routine after changing a screen to make the terminal screen look like

       Example Program ®
       #include <cursesX.h>
       main ()
       initscr();     /*initialize terminal settings, data
		  ** structures and variables*/
       move(LINES/2 -1, COLS/2 -4);
       refresh();     /* send output to update terminal
		       **  screen */
       refresh();     /* send more output to terminal
		       **  screen */
       endwin();      /*restore all terminal settings */

Main Routines
       Routines	 listed	 here  can be called when using the library.  Routines
       that are preceded by a w affect a specified window, those preceded by a
       p affect a specified pad.  All other routines affect the default window
       Windows are specified by a numeric argument, for example:  (win)	 where
       win is the specified window.

       addch(ch)	     Add  a  character to stdscr (like putchar wraps
			     to next line at end of line)
       addstr(str)	     Call addch with each character in str
       attroff(attrs)	     Turn off named attributes
       attron(attrs)	     Turn on named attributes
       attrset(attrs)	     Set current attributes to attrs
       baudrate()	     Display current terminal speed
       beep()		     Sound beep on terminal
       box(win, vert, hor)   Draw a box around edges of win,
			     vert and hor are characters to use for vertical
			     and horizontal edges of box
       clear()		     Clear stdscr
       clearok(win, bf)	     Clear screen before next redraw of win
       clrtobot()	     Clear to bottom of stdscr
       clrtoeol()	     Clear to end of line on stdscr
       cbreak()		     Set cbreak mode
       delay_output(ms)	     Insert ms millisecond pause in output
       delch()		     Delete a character
       deleteln()	     Delete a line
       delwin(win)	     Delete win
       doupdate()	     Update screen from all wnoutrefresh
       echo()		     Set echo mode
       endwin()		     End window modes
       erase()		     Erase stdscr
       erasechar()	     Return user's erase character
       fixterm()	     Restore tty to in ``curses'' state
       flash()		     Flash screen or beep
       flushinp()	     Throw away any typeahead
       getch()		     Get a character from tty
       getstr(str)	     Get a string through stdscr
       gettmode()	     Establish current tty modes
       getyx(win, y, x)	     Get (y, x) coordinates
       has_ic()		     True if terminal can do insert character
       has_il()		     True if terminal can do insert line
       idlok(win, bf)	     Use terminal's insert/delete line if bf != 0
       inch()		     Get character at current (y, x) coordinates
       initscr()	     Initialize screens
       insch(c)		     Insert a character
       insertln()	     Insert a line
       intrflush(win, bf)    Interrupt flush output if bf is TRUE
       keypad(win, bf)	     Enable keypad input
       killchar()	     Return current user's kill character
       leaveok(win, flag)    Leave cursor anywhere after refresh if
			     flag!=0 for win. Otherwise cursor must be left
			     at current position
       longname()	     Return verbose name of terminal
       meta(win, flag)	     Allow meta characters on input if flag != 0
       move(y, x)	     Move to (y, x) on stdscr

       NOTE: The following routines prefixed with mv require  and  coordinates
       to  move	 to, before performing the same functions as the standard rou‐
       tines. As an example, performs the same	function  as  and  coordinates
       must  be supplied first.	 The routines prefixed with mvw also require a
       window or pad argument.

       mvaddch(y, x, ch)
       mvaddstr(y, x, str)
       mvcur(oldrow, oldcol, newrow,	  low level cursor motion
       mvdelch(y, x)
       mvgetch(y, x)
       mvgetstr(y, x)
       mvinch(y, x)
       mvinsch(y, x, c)

       mvprintw(y, x, fmt, args)
       mvscanw(y, x, fmt, args)
       mvwaddch(win, y, x, ch)
       mvwaddstr(win, y, x, str)
       mvwdelch(win, y, x)
       mvwgetch(win, y, x)
       mvwgetstr(win, y, x)
       mvwin(win, by, bx)
       mvwinch(win, y, x)
       mvwinsch(win, y, x, c)
       mvwprintw(win, y, x, fmt, args)
       mvwscanw(win, y, x, fmt, args)
       newpad(nlines, ncols)		  Create a new pad with given dimensions
       newterm(type, fd)		  Set up new terminal  of  given  type	to
					  output on fd
       newwin(lines, cols,		  Create a new window
       begin_y, begin_x)
       nl()				  Set newline mapping
       nocbreak()			  Unset cbreak mode
       nodelay(win, bf)			  Enable nodelay input mode through getch
       noecho()				  Unset echo mode
       nonl()				  Unset newline mapping
       noraw()				  Unset raw mode
       overlay(win1, win2)		  Overlay win1 on win2
       overwrite(win1, win2)		  Overwrite win1 on top of win2
       pnoutrefresh(pad, pminrow,	  Like prefresh but with no output
       pmincol, sminrow, smincol,	  until doupdate called
       smaxrow, smaxcol)
       prefresh(pad, pminrow,		  Refresh  from	 pad  starting	with given
       pmincol, sminrow, smincol,	  left corner of pad with output to
       smaxrow, smaxcol)		  given portion of screen
       printw(fmt, arg1, arg2, ...)	  printf on stdscr
       raw()				  Set raw mode
       refresh()			  Make current screen look like stdscr
       resetterm()			  Set tty modes to ``out of curses'' state
       resetty()			  Reset tty flags to stored value
       saveterm()			  Save	current	 modes	as  ``in  curses''
       savetty()			  Store current tty flags
       scanw(fmt, arg1, arg2, ...)	  scanf through stdscr
       scroll(win)			  Scroll win one line
       scrollok(win, flag)		  Allow terminal to scroll if flag != 0
       set_term(new)			  Switch between different terminals
       setscrreg(t, b)			  Set  user  scrolling	region	to lines t
					  through b
       setupterm(term, filenum, errret)	  Low level terminal setup
       standend()			  Clear standout mode attribute
       standout()			  Set standout mode attribute
       subwin(win, lines, cols,		  Create a subwindow
       begin_y, begin_x)
       touchwin(win)			  “change” all of win
       traceoff()			  Turn off debugging trace output
       traceon()			  Turn on debugging trace output
       typeahead(fd)			  Use file descriptor fd to  check  typea‐
       unctrl(ch)			  Produce printable version of ch
       waddch(win, ch)			  Add character to win
       waddstr(win, str)		  Add string to win
       wattroff(win, attrs)		  Turn off attrs in win
       wattron(win, attrs)		  Turn on attrs in win
       wattrset(win, attrs)		  Set attrs in win to attrs
       wclear(win)			  Clear win
       wclrtobot(win)			  Clear to bottom of win
       wclrtoeol(win)			  Clear to end of line on win

       wdelch(win, c)			  Delete char from win
       wdeleteln(win)			  Delete line from win
       werase(win)			  Erase win
       wgetch(win)			  Get a character through win
       wgetstr(win, str)		  Get a string through win
       winch(win)			  Get character at current (y, x) in win
       winsch(win, c)			  Insert char into win
       winsertln(win)			  Insert line into win
       wmove(win, y, x)			  Set current (y, x) coordinates on win
       wnoutrefresh(win)		  Refresh but no screen output
       wprintw(win, fmt,		  printf on win
       arg1, arg2, ...)
       wrefresh(win)			  Make screen look like win
       wscanw(win, fmt,			  scanf through win
       arg1, arg2, ...)
       wsetscrreg(win, t, b)		  Set scrolling region of win
       wstandend(win)			  Clear standout attribute in win
       wstandout(win)			  Set standout attribute in win


       The  plotting  library  and the library both use the names and The ver‐
       sions are macros.  If you need both libraries, put the code in  a  dif‐
       ferent source file to the code, and/or and in the code.

TERMINFO Level Routines
       If the environment variable TERMINFO is defined, any program using will
       check for a local terminal definition before checking in	 the  standard
       libraries.   For	 example,  if  the standard place is set to vt100, the
       compiled file will normally be found in The v is copied from the	 first
       letter  of  vt100 to avoid creating huge directories.  However, if TER‐
       MINFO is set to will first check and if that  fails,  will  then	 check
       This is useful for developing experimental definitions or when there is
       no write permission for

       These routines should be called by programs that need to deal  directly
       with the database, but as this is a low level interface, it is not rec‐

       Initially, the routine should be called.	 This will define the  set  of
       terminal-dependent variables defined in The include files and should be
       included to get the definitions for these strings, numbers, and	flags.
       Parameterized  strings  should  be  passed through to instantiate them.
       All terminfo strings (including the output of should be printed with or
       Before exiting, should be called to restore the tty modes.

       Programs	 which	want  shell  escapes or suspending can call before the
       shell is called and after returning from the shell.

       fixterm()		     Restore tty modes for terminfo use
				     (called by setupterm)
       resetterm()		     Reset tty modes to state before program entry
       setupterm(term, fd, rc)	     Read in database.	Terminal type is the
				     character string term, all output is to ULTRIX
				     System file descriptor fd.	 A status value is
				     returned in the integer pointed to by rc: 1
				     is normal.	 The simplest call would be
				     setupterm(0, 1, 0) which uses all defaults
       tparm(str, p1, p2, ..., p9)   Instantiate string str with parms pi

       tputs(str, affcnt, putc)	     Apply padding info to string str
				     affcnt is the number of lines affected,
				     or 1 if not applicable.  Putc is a

				     putchar-like function to which the characters
				     are passed, one at a time
       putp(str)		     A function that calls tputs
				     (str, 1, putchar)
       vidputs(attrs, putc)	     Output the string to put terminal in video
				     attribute mode attrs, which is any
				     combination of the attributes listed below
				     Chars are passed to putchar-like
				     function putc
       vidattr(attrs)		     Like vidputs but outputs through

Termcap Compatibility Routines
       The following routines were included as a conversion aid	 for  programs
       that  use termcap.  Their parameters are the same as for termcap.  They
       are emulated using the database.

       DO NOT use these routines in new programs.

       tgetent(bp, name)	Look up termcap entry for name
       tgetflag(id)		Get boolean entry for id
       tgetnum(id)		Get numeric entry for id
       tgetstr(id, area)	Get string entry for id
       tgoto(cap, col, row)	Apply parms to given cap
       tputs(cap, affcnt, fn)	Apply padding to cap calling fn as putchar

       As an aid to compatibility, the object module has been provided in This
       module  should  be  linked into an application before resolving against
       the library.  If your application  contains  references	such  as  then
       recompile using
       cc [options] files /usr/lib/termcap.o -lcursesX [libs]

       No errors are defined for the functions.

Return Values
       For  most routines, the value is returned if a routine is properly com‐
       pleted and the value is returned if some error occurs.

See Also
       tic(1),	ioctl(2),  getenv(3),  printf(3s),   putchar(3s),   scanf(3s),
       plot(3x), termcap(5), terminfo(5)
       Guide to X/Open curses Screen Handling


List of man pages available for Ultrix

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net