Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
curs_termcap(3X)					      curs_termcap(3X)

       tgetent,	 tgetflag,  tgetnum, tgetstr, tgoto, tputs - direct curses in-
       terface to the terminfo capability database

       #include	<curses.h>
       #include	<term.h>
       extern char PC; extern char * UP; extern	char * BC;  extern  short  os-
       int tgetent(char	*bp, const char	*name);
       int tgetflag(char *id);
       int tgetnum(char	*id);
       char *tgetstr(char *id, char **area);
       char *tgoto(const char *cap, int	col, int row);
       int tputs(const char *str, int affcnt, int (*putc)(int));

       These  routines	are included as	a conversion aid for programs that use
       the termcap library.  Their parameters are the same  and	 the  routines
       are  emulated using the terminfo	database.  Thus, they can only be used
       to query	the capabilities of entries for	which  a  terminfo  entry  has
       been compiled.

       The tgetent routine loads the entry for name.  It returns 1 on success,
       0 if there is no	such entry, and	-1 if the terminfo database could  not
       be found.  The emulation	ignores	the buffer pointer bp.

       The  tgetflag  routine  gets the	boolean	entry for id, or zero if it is
       not available.

       The tgetnum routine gets	the numeric entry for id, or -1	if it  is  not

       The  tgetstr  routine returns the string	entry for id, or zero if it is
       not available.  Use tputs to output the returned	 string.   The	return
       value  will  also  be  copied to	the buffer pointed to by area, and the
       area value will be updated to point past	the null ending	this value.

       Only the	first two characters of	the id parameter of tgetflag,  tgetnum
       and tgetstr are compared	in lookups.

       The  tgoto  routine instantiates	the parameters into the	given capabil-
       ity.  The output	from this routine is to	be passed to tputs.

       The tputs routine is described on the  curs_terminfo(3X)	 manual	 page.
       It can retrieve capabilities by either termcap or terminfo name.

       The  variables PC, UP and BC are	set by tgetent to the terminfo entry's
       data for	pad_char, cursor_up and	backspace_if_not_bs, respectively.  UP
       is  not used by ncurses.	 PC is used in the tdelay_output function.  BC
       is used in the tgoto emulation.	The variable ospeed is set by  ncurses
       in a system-specific coding to reflect the terminal speed.

       Except  where  explicitly noted,	routines that return an	integer	return
       ERR upon	failure	and OK (SVr4 only specifies "an	 integer  value	 other
       than ERR") upon successful completion.

       Routines	that return pointers return NULL on error.

       If  you	call tgetstr to	fetch ca or any	other parameterized string, be
       aware that it will be returned in terminfo notation, not	the older  and
       not-quite-compatible  termcap  notation.	  This won't cause problems if
       all you do with it is call tgoto	or tparm, which	both expand  terminfo-
       style  strings as terminfo.  (The tgoto function, if configured to sup-
       port termcap, will check	if the	string	is  indeed  terminfo-style  by
       looking	for  "%p"  parameters or "$<..>" delays, and invoke a termcap-
       style parser if the string does not appear to be	terminfo).

       Because terminfo	conventions for	representing padding in	 string	 capa-
       bilities	 differ	 from  termcap's,  tputs("50");	will put out a literal
       "50" rather than	busy-waiting for 50 milliseconds.  Cope	with it.

       The XSI Curses standard,	Issue 4	describes these	 functions.   However,
       they are	marked TO BE WITHDRAWN and may be removed in future versions.

       Neither	the  XSI Curses	standard nor the SVr4 man pages	documented the
       return values of	tgetent	correctly, though all three were in  fact  re-
       turned  ever  since SVr1.  In particular, an omission in	the XSI	Curses
       documentation has been misinterpreted to	mean that tgetent  returns  OK
       or  ERR.	 Because the purpose of	these functions	is to provide compati-
       bility with the termcap library,	that is	a defect in XCurses, Issue  4,
       Version 2 rather	than in	ncurses.

       External	variables are provided for support of certain termcap applica-
       tions.  However,	termcap	applications' use of those variables is	poorly
       documented, e.g., not distinguishing between input and output.  In par-
       ticular,	some applications are reported to declare  and/or  modify  os-

       curses(3X), terminfo(5),	putc(3S).



Want to link to this manual page? Use this URL:

home | help