terminfo man page on MirBSD

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



curs_terminfo(3)    UNIX Programmer's Manual	 curs_terminfo(3)

NAME
     del_curterm, mvcur, putp, restartterm, set_curterm, setterm,
     setupterm, tigetflag, tigetnum, tigetstr, 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(const 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)(char));
     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);

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.

     Initially, setupterm should be called.  Note that	setupterm
     is	 automatically	called	by initscr and newterm.	 This de-
     fines the set of  terminal-dependent  variables  [listed  in
     terminfo(5)].   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 ter-
     minfo 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  run-
     ning  in  a window, the current window size is used.  Other-
     wise, if the environment variables do not exist, the  values
     for lines and columns specified in the terminfo database are
     used.

     The header files curses.h and term.h should be included  (in
     this  order)  to  get  the	 definitions  for  these strings,
     numbers, and flags. Parameterized strings should  be  passed
     through tparm to instantiate them. All terminfo strings [in-

MirOS BSD #10-current	Printed 18.8.2011			1

curs_terminfo(3)    UNIX Programmer's Manual	 curs_terminfo(3)

     cluding the output of tparm] should be printed with tputs or
     putp.   Call  the	reset_shell_mode to restore the tty modes
     before exiting [see  curs_kernel(3)].   Programs  which  use
     cursor  addressing	 should output enter_ca_mode upon startup
     and should output	exit_ca_mode  before  exiting.	 Programs
     desiring shell escapes should call

     reset_shell_mode and output exit_ca_mode before the shell is
     called    and   should   output   enter_ca_mode   and   call
     reset_prog_mode after returning from the shell.

     The setupterm routine reads in the terminfo  database,  ini-
     tializing	the  terminfo structures, but does not set up the
     output virtualization structures used by curses.  The termi-
     nal  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.

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

	  -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 is being  replaced  by	 setupterm.   The
     call:

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

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

     The set_curterm routine sets the variable 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.

MirOS BSD #10-current	Printed 18.8.2011			2

curs_terminfo(3)    UNIX Programmer's Manual	 curs_terminfo(3)

     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 in-
     valid 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 previ-
     ous state (for example, when reloading a  game  saved  as	a
     core image dump).	It 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.  Ac-
     cordingly, it saves various tty state bits,  does	a  setup-
     term, and then restores the bits.

     The tparm routine instantiates the string str  with  parame-
     ters  pi.	 A  pointer is returned to the result of str with
     the parameters applied.

     The tputs routine applies padding information to the  string
     str and outputs it.  The str must be a terminfo string vari-
     able or the return value  from  tparm,  tgetstr,  or  tgoto.
     affcnt is the number of lines affected, or 1 if not applica-
     ble.  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	curses(3).   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, ap-
     plications 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).

MirOS BSD #10-current	Printed 18.8.2011			3

curs_terminfo(3)    UNIX Programmer's Manual	 curs_terminfo(3)

     The tigetflag, tigetnum and  tigetstr  routines  return  the
     value  of	the capability corresponding to the terminfo cap-
     name passed to them, such as xenl.

     The tigetflag routine returns the value -1 if capname is not
     a	boolean capability, or 0 if it is canceled or absent from
     the terminal description.

     The tigetnum routine returns the value -2 if capname is  not
     a numeric capability, or -1 if it is canceled or absent from
     the terminal description.

     The tigetstr routine returns the value (char *)-1 if capname
     is not a string capability, or 0 if it is canceled or absent
     from the terminal description.

     The capname for each capability is given in the table column
     entitled capname code in the capabilities section of termin-
     fo(5).

     char *boolnames, *boolcodes, *boolfnames

     char *numnames, *numcodes, *numfnames

     char *strnames, *strcodes, *strfnames

     These  null-terminated  arrays  contain  the  capnames,  the
     termcap codes, and the full C names, for each of the termin-
     fo variables.

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.

	  restartterm
	       returns an error if the associated call to  setup-
	       term 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  docu-

MirOS BSD #10-current	Printed 18.8.2011			4

curs_terminfo(3)    UNIX Programmer's Manual	 curs_terminfo(3)

	       mented above.

NOTES
     The setupterm routine should be used in place of setterm. It
     may  be  useful when you want to test for terminal capabili-
     ties without committing to the  allocation	 of  storage  in-
     volved in initscr.

     Note that vidattr and vidputs may be macros.

PORTABILITY
     The function setterm is not  described  in	 the  XSI  Curses
     standard  and  must  be  considered non-portable.	All other
     functions are as described in the XSI curses standard.

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

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

     The XSI Curses standard prototypes tparm with a fixed number
     of	 parameters,  rather  than a variable argument list. This
     implementation uses a variable argument list.  Portable  ap-
     plications	 should	 provide  9  parameters after the format;
     zeroes are fine for this purpose.

     XSI 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 im-
     plement mvcur using the SCREEN data allocated in either  in-
     itscr  or	newterm. So though it is documented as a terminfo
     function, mvcur is really a curses	 function  which  is  not
     well specified.

SEE ALSO
     curses(3), curs_initscr(3), curs_kernel(3), curs_termcap(3),
     putc(3), terminfo(5)

MirOS BSD #10-current	Printed 18.8.2011			5

[top]

List of man pages available for MirBSD

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]
Tweet
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