mvcur(3ncurses)


NAME

   del_curterm, mvcur, putp, restartterm, set_curterm, setterm, setupterm,
   tigetflag, tigetnum, tigetstr, tiparm, tparm, tputs, vid_attr,
   vid_puts, vidattr, vidputs - curses interfaces to terminfo database

SYNOPSIS

   #include <curses.h>
   #include <term.h>

   int setupterm(char *term, int fildes, int *errret);
   int setterm(char *term);
   TERMINAL *set_curterm(TERMINAL *nterm);
   int del_curterm(TERMINAL *oterm);
   int restartterm(char *term, int fildes, int *errret);
   char *tparm(char *str, ...);
   int tputs(const char *str, int affcnt, int (*putc)(int));
   int putp(const char *str);
   int vidputs(chtype attrs, int (*putc)(int));
   int vidattr(chtype attrs);
   int vid_puts(attr_t attrs, short pair, void *opts, int (*putc)(int));
   int vid_attr(attr_t attrs, short pair, void *opts);
   int mvcur(int oldrow, int oldcol, int newrow, int newcol);
   int tigetflag(char *capname);
   int tigetnum(char *capname);
   char *tigetstr(char *capname);
   char *tiparm(const char *str, ...);

DESCRIPTION

   These  low-level  routines must be called by programs that have to deal
   directly  with  the  terminfo  database  to  handle  certain   terminal
   capabilities,  such  as  programming  function  keys.   For  all  other
   functionality, curses routines are  more  suitable  and  their  use  is
   recommended.

   Initialization
   Initially,   setupterm  should  be  called.   Note  that  setupterm  is
   automatically called by initscr and newterm.  This defines the  set  of
   terminal-dependent variables [listed in terminfo(5)].

   Each  initialization  routine  provides  applications with the terminal
   capabilities either directly (via header definitions),  or  by  special
   functions.  The header files curses.h and term.h should be included (in
   this order) to get the definitions  for  these  strings,  numbers,  and
   flags.

   The  terminfo  variables lines and columns are initialized by setupterm
   as follows:

   *   If use_env(FALSE) has been called, values  for  lines  and  columns
       specified in terminfo are used.

   *   Otherwise,  if  the  environment variables LINES and COLUMNS exist,
       their values are used.  If these environment variables do not exist
       and  the program is running in a window, the current window size is
       used.  Otherwise, if the environment variables do  not  exist,  the
       values for lines and columns specified in the terminfo database are
       used.

   Parameterized strings should be passed  through  tparm  to  instantiate
   them.   All  terminfo strings [including the output of tparm] should be
   printed with tputs or putp.  Call reset_shell_mode to restore  the  tty
   modes before exiting [see kernel(3NCURSES)].

   Programs which use cursor addressing should

   *   output enter_ca_mode upon startup and

   *   output exit_ca_mode before exiting.

   Programs which execute shell subprocesses should

   *   call  reset_shell_mode  and output exit_ca_mode before the shell is
       called and

   *   output enter_ca_mode and call reset_prog_mode after returning  from
       the shell.

   The  setupterm routine reads in the terminfo database, initializing the
   terminfo structures, but does not  set  up  the  output  virtualization
   structures  used  by curses.  The terminal type is the character string
   term; if term is null, the environment  variable  TERM  is  used.   All
   output  is  to  file descriptor fildes which is initialized for output.
   If errret is not null, then setupterm returns OK or ERR  and  stores  a
   status value in the integer pointed to by errret.  A return value of OK
   combined with status of 1 in errret is normal.   If  ERR  is  returned,
   examine errret:

   1    means  that  the  terminal  is hardcopy, cannot be used for curses
        applications.

        setupterm determines if the entry is a hardcopy type  by  checking
        the hc (hardcopy) capability.

   0    means  that  the  terminal  could  not  be  found, or that it is a
        generic  type,  having   too   little   information   for   curses
        applications to run.

        setupterm  determines  if  the entry is a generic type by checking
        the gn (generic) capability.

   -1   means that the terminfo database could not be found.

   If errret is null, setupterm prints an error message  upon  finding  an
   error and exits.  Thus, the simplest call is:

         setupterm((char *)0, 1, (int *)0);,

   which uses all the defaults and sends the output to stdout.

   The setterm routine was replaced by setupterm.  The call:

         setupterm(term, 1, (int *)0)

   provides  the same functionality as setterm(term).  The setterm routine
   is provided for BSD compatibility,  and  is  not  recommended  for  new
   programs.

   The Terminal State
   The  setupterm  routine  stores its information about the terminal in a
   TERMINAL structure pointed to by the global variable cur_term.   If  it
   detects  an error, or decides that the terminal is unsuitable (hardcopy
   or generic), it discards this information, making it not  available  to
   applications.

   If  setupterm  is called repeatedly for the same terminal type, it will
   reuse  the  information.   It  maintains  only  one  copy  of  a  given
   terminal's  capabilities  in  memory.   If  it  is called for different
   terminal types,  setupterm  allocates  new  storage  for  each  set  of
   terminal capabilities.

   The  set_curterm  routine  sets cur_term to nterm, and makes all of the
   terminfo boolean, numeric, and string variables  use  the  values  from
   nterm.  It returns the old value of cur_term.

   The  del_curterm  routine frees the space pointed to by oterm and makes
   it available for further use.   If  oterm  is  the  same  as  cur_term,
   references  to  any  of  the  terminfo  boolean,  numeric,  and  string
   variables thereafter  may  refer  to  invalid  memory  locations  until
   another setupterm has been called.

   The  restartterm  routine  is  similar to setupterm and initscr, except
   that it is called after restoring  memory  to  a  previous  state  (for
   example,   when   reloading  a  game  saved  as  a  core  image  dump).
   restartterm assumes that the windows and the input and  output  options
   are  the  same as when memory was saved, but the terminal type and baud
   rate may be different.   Accordingly,  restartterm  saves  various  tty
   state bits, calls setupterm, and then restores the bits.

   Formatting Output
   The  tparm  routine  instantiates the string str with parameters pi.  A
   pointer is returned to the result of str with the parameters applied.

   tiparm is a newer form of tparm which uses  <stdarg.h>  rather  than  a
   fixed-parameter list.  Its numeric parameters are integers (int) rather
   than longs.

   Output Functions
   The tputs routine applies padding information to  the  string  str  and
   outputs  it.   The str must be a terminfo string variable or the return
   value from tparm, tgetstr, or tgoto.  affcnt is  the  number  of  lines
   affected,  or  1  if not applicable.  putc is a putchar-like routine to
   which the characters are passed, one at a time.

   The putp routine calls tputs(str, 1, putchar).  Note that the output of
   putp always goes to stdout, not to the fildes specified in setupterm.

   The  vidputs  routine  displays the string on the terminal in the video
   attribute mode attrs, which is any combination of the attributes listed
   in  ncurses(3NCURSES).   The  characters are passed to the putchar-like
   routine putc.

   The vidattr routine is like the vidputs routine, except that it outputs
   through putchar.

   The  vid_attr  and vid_puts routines correspond to vidattr and vidputs,
   respectively.  They use a set of arguments for representing  the  video
   attributes  plus color, i.e., one of type attr_t for the attributes and
   one of short for the color_pair  number.   The  vid_attr  and  vid_puts
   routines  are  designed  to  use  the  attribute constants with the WA_
   prefix.  The opts argument is  reserved  for  future  use.   Currently,
   applications must provide a null pointer for that argument.

   The  mvcur  routine  provides low-level cursor motion.  It takes effect
   immediately (rather than at the next refresh).

   Terminal Capability Functions
   The tigetflag, tigetnum and tigetstr routines return the value  of  the
   capability  corresponding  to the terminfo capname passed to them, such
   as xenl.  The capname for each capability is given in the table  column
   entitled capname code in the capabilities section of terminfo(5).

   These routines return special values to denote errors.

   The tigetflag routine returns

   -1     if capname is not a boolean capability, or

   0      if it is canceled or absent from the terminal description.

   The tigetnum routine returns

   -2     if capname is not a numeric capability, or

   -1     if it is canceled or absent from the terminal description.

   The tigetstr routine returns

   (char *)-1
          if capname is not a string capability, or

   0      if it is canceled or absent from the terminal description.

   Terminal Capability Names
   These   null-terminated   arrays   contain  the  short  terminfo  names
   ("codes"), the termcap names, and the long  terminfo  names  ("fnames")
   for each of the predefined terminfo variables:
          char *boolnames[], *boolcodes[], *boolfnames[]

          char *numnames[], *numcodes[], *numfnames[]

          char *strnames[], *strcodes[], *strfnames[]

RETURN VALUE

   Routines  that  return  an integer return ERR upon failure and OK (SVr4
   only specifies "an integer  value  other  than  ERR")  upon  successful
   completion,   unless   otherwise   noted   in   the  preceding  routine
   descriptions.

   Routines that return pointers always return NULL on error.

   X/Open defines no error conditions.  In this implementation

        del_curterm
             returns an error if its terminal parameter is null.

        putp calls tputs, returning the same error-codes.

        restartterm
             returns an error if the associated call to setupterm  returns
             an error.

        setupterm
             returns  an  error  if  it  cannot allocate enough memory, or
             create the initial windows (stdscr, curscr,  newscr).   Other
             error conditions are documented above.

        tputs
             returns  an  error  if the string parameter is null.  It does
             not detect I/O errors: X/Open states that tputs  ignores  the
             return value of the output function putc.

PORTABILITY

   X/Open notes that vidattr and vidputs may be macros.

   The  function setterm is not described by X/Open and must be considered
   non-portable.  All other functions are as described by X/Open.

   setupterm copies the terminal name to the array ttytype.  This  is  not
   part of X/Open Curses, but is assumed by some applications.

   If configured to use the terminal-driver, e.g., for the MinGW port,

   *   setupterm  interprets  a missing/empty TERM variable as the special
       value "unknown".

   *   setupterm allows explicit use of the the windows console driver  by
       checking  if $TERM is set to "#win32con" or an abbreviation of that
       string.

   Older versions of ncurses assumed that the file  descriptor  passed  to
   setupterm from initscr or newterm uses buffered I/O, and would write to
   the corresponding stream.  In  addition  to  the  limitation  that  the
   terminal was left in block-buffered mode on exit (like SystemV curses),
   it was problematic because ncurses did not  allow  a  reliable  way  to
   cleanup  on receiving SIGTSTP.  The current version uses output buffers
   managed directly by ncurses.  Some of the low-level functions described
   in this manual page write to the standard output.  They are not signal-
   safe.  The high-level functions in ncurses use  alternate  versions  of
   these functions using the more reliable buffering scheme.

   In  System  V Release 4, set_curterm has an int return type and returns
   OK or ERR.  We have chosen to implement the X/Open Curses semantics.

   In System V Release 4, the third argument of tputs  has  the  type  int
   (*putc)(char).

   At  least one implementation of X/Open Curses (Solaris) returns a value
   other than OK/ERR from tputs.  That returns the length of  the  string,
   and does no error-checking.

   X/Open  Curses  prototypes  tparm  with  a  fixed number of parameters,
   rather than a variable  argument  list.   This  implementation  uses  a
   variable  argument  list,  but  can  be  configured  to  use the fixed-
   parameter list.  Portable  applications  should  provide  9  parameters
   after the format; zeroes are fine for this purpose.

   In  response  to  comments  by  Thomas E. Dickey, X/Open Curses Issue 7
   proposed the tiparm function in mid-2009.

   X/Open notes that after calling mvcur, the curses state may  not  match
   the  actual  terminal  state,  and that an application should touch and
   refresh the window before resuming normal curses calls.   Both  ncurses
   and  System  V  Release  4 curses implement mvcur using the SCREEN data
   allocated in either initscr or newterm.  So though it is documented  as
   a  terminfo  function,  mvcur  is really a curses function which is not
   well specified.

   X/Open states that the old location must  be  given  for  mvcur.   This
   implementation allows the caller to use -1's for the old ordinates.  In
   that case, the old location is unknown.

   Other implementions may not declare the capability name  arrays.   Some
   provide them without declaring them.  X/Open does not specify them.

   Extended terminal capability names, e.g., as defined by tic -x, are not
   stored in the arrays described here.

SEE ALSO

   ncurses(3NCURSES),         initscr(3NCURSES),         kernel(3NCURSES),
   termcap(3NCURSES),                          curses_variables(3NCURSES),
   terminfo_variables(3NCURSES), putc(3), terminfo(5)

                                                        terminfo(3NCURSES)





Opportunity


Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.

Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.





Free Software


Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.


Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.





Free Books


The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.


Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.





Education


Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.


Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.