TERMCAP(3)              NetBSD Library Functions Manual             TERMCAP(3)

NAME
     tgetent, tgetnum, tgetflag, tgetstr, tgoto, tputs -- terminal independent
     operation routines

LIBRARY
     Termcap Access Library (libtermcap, -ltermcap)

SYNOPSIS
     #include <termcap.h>

     char PC;
     char *BC;
     char *UP;
     short ospeed;
     struct tinfo *info;

     int
     tgetent(char *bp, const char *name);

     int
     tgetnum(const char *id);

     int
     tgetflag(const char *id);

     char *
     tgetstr(const char *id, char **area);

     char *
     tgoto(const char *cm, int destcol, int destline);

     void
     tputs(const char *cp, int affcnt, int (*outc)(int));

     int
     t_getent(struct tinfo **info, const char *name);

     int
     t_getnum(struct tinfo *info, const char *id);

     int
     t_getflag(struct tinfo *info, const char *id);

     char *
     t_getstr(struct tinfo *info, const char *id, char **area, size_t *limit);

     char *
     t_agetstr(struct tinfo *info, const char *id);

     int
     t_getterm(struct tinfo *info, char **area, size_t *limit);

     int
     t_goto(struct tinfo *info, const char *id, int destcol, int destline,
         char *buffer, size_t limit);

     int
     t_puts(struct tinfo *info, const char *cp, int affcnt,
         void (*outc)(char, void *), void *args);

     void
     t_freent(struct tinfo *info);

     int
     t_setinfo(struct tinfo **info, const char *entry);

     #include <wchar.h>

     int
     t_putws(struct tinfo *info, const wchar_t *cp, int affcnt,
         void (*outc)(wchar_t, void *), void *args);

DESCRIPTION
     These functions extract and use capabilities from a terminal capability
     data base, usually /usr/share/misc/termcap, the format of which is
     described in termcap(5).  These are low level routines; see curses(3) for
     a higher level package.

     The tgetent() function extracts the entry for terminal name into the
     buffer at bp.  The bp argument should be a character buffer of size 1024
     and must be retained through all subsequent calls to tgetnum(),
     tgetflag(), and tgetstr().  The tgetent() function returns -1 if none of
     the termcap data base files could be opened, 0 if the terminal name given
     does not have an entry, and 1 if all goes well.  It will look in the
     environment for a TERMCAP variable.  If found, and the value does not
     begin with a slash, the value does not contain the ZZ capability (see
     NOTES for a description of this capability), and the terminal type name
     is the same as the environment string TERM, the TERMCAP string is used
     instead of reading a termcap file.  If the value does contain the ZZ
     capability then the TERM environment string is used to read termcap, if
     the read fails for any reason the value of TERMCAP will be used despite
     it containing ZZ.  If TERMCAP does begin with a slash, the string is used
     as a path name of the termcap file to search.  If TERMCAP does not begin
     with a slash and name is different from TERM, tgetent() searches the
     files $HOME/.termcap and /usr/share/misc/termcap, in that order, unless
     the environment variable TERMPATH exists, in which case it specifies a
     list of file pathnames (separated by spaces or colons) to be searched
     instead.  Whenever multiple files are searched and a tc field occurs in
     the requested entry, the entry it names must be found in the same file or
     one of the succeeding files.  This can speed up entry into programs that
     call tgetent(), as well as help debug new terminal descriptions or make
     one for your terminal if you can't write the file
     /usr/share/misc/termcap.

     The tgetnum() function gets the numeric value of capability id, returning
     -1 if it is not given for the terminal.  The tgetflag() function returns
     1 if the specified capability is present in the terminal's entry, 0 if it
     is not.  The tgetstr() function returns the string value of the capabil-
     ity id; if area does not point to NULL and does not point to a pointer to
     NULL, it copies the string value into the buffer pointed to by *area, and
     advances the *area pointer past the copy of the string.  It decodes the
     abbreviations for this field described in termcap(5), except for cursor
     addressing and padding information.  The tgetstr() function returns NULL
     if the capability was not found.

     The tgoto() function returns a cursor addressing string decoded from cm
     to go to column destcol in line destline.  It uses the external variables
     UP (from the up capability) and BC (if bc is given rather than bs) if
     necessary to avoid placing \n, ^D or ^@ in the returned string.  (Pro-
     grams which call tgoto() should be sure to turn off the XTABS bit(s),
     since tgoto() may now output a tab.  Note that programs using termcap
     should in general turn off XTABS anyway since some terminals use control-
     I for other functions, such as nondestructive space.)  If a % sequence is
     given which is not understood, then tgoto() returns (OOPS).

     The tputs() function decodes the leading padding information of the
     string cp; affcnt gives the number of lines affected by the operation, or
     1 if this is not applicable, outc is a routine which is called with each
     character in turn.  The external variable ospeed should contain the out-
     put speed of the terminal as encoded by stty(3).  The external variable
     PC should contain a pad character to be used (from the pc capability) if
     a null (^@) is inappropriate.

     The t_getent() function operates in a similar manner to the tgetent()
     function excepting that the info argument is a pointer to a pointer of
     the opaque type tinfo.  If the call to t_getent() succeeds then the argu-
     ment info will be updated with the address of an object that contains the
     termcap entry.  This pointer can then be passed to calls of t_getnum(),
     t_getflag() and t_getstr().  When the information pointed to by info is
     no longer required any storage associated with the object can be released
     by calling t_freent().

     The functions t_getnum() and t_getflag() operate in the same manner as
     tgetnum() and tgetflag() with the exception that the pointer to the term-
     cap object is passed along with the id of the capability required.

     The function t_getstr() performs the same function as tgetstr() but has a
     limit parameter that gives the number of characters that can be inserted
     in to the array pointed to by area.  The limit argument is updated by the
     t_getstr() call to give the number of characters that remain available in
     area.  If the t_getstr call fails then NULL will be returned and errno
     set to indicate the failure, ENOENT indicates there was no termcap entry
     for the given id, E2BIG indicates the retrieved entry would have over-
     flowed area.  If t_getstr is called with area being NULL then the size
     required to hold the capability string will be returned in limit so the
     caller can allocate enough storage to hold the capability.

     The function t_agetstr() performs the same function as t_getstr() except
     it handles memory allocation automatically.  The memory that t_agetstr()
     allocates will be freed when t_freent() is called.

     The function t_getterm() returns a copy of the termcap name string of the
     termcap entry associated with info in the buffer pointed to by area.
     t_getterm() returns 0 on success and -1 on error.  On error errno will be
     set to EINVAL if the termcap entry in info is malformed or E2BIG if the
     size of the name exceeds the size specified by limit.  If area is NULL
     then the size required to hold the terminal name will be returned in
     limit allowing sufficient storage to be allocated.  If limit is NULL then
     no bounds checking will be performed.

     The t_goto() function is the same as the tgoto() function excepting that
     the capabilities for up and bc are extracted from the info object and
     that the string formed by t_goto() is placed in the buffer argument, the
     number of characters allowed to be placed in buffer is controlled by
     limit.  If the expansion performed by t_goto() would exceed the space in
     buffer then t_goto() will return -1 and set errno to E2BIG.  The function
     t_puts() is similar to the tputs() function excepting that info holds a
     pointer to the termcap object that was returned by a previous t_getent()
     call, this object will be used to retrieve the pc attribute for the ter-
     minal.  The function t_putws() is similar to t_puts() but it operates on
     a string of wide characters.  The outc function is a pointer to a func-
     tion that will be called by t_puts() to output each character in the cp
     string.  The outc function will be called with two parameters.  The first
     is the character to be printed and the second is an optional argument
     that was passed to t_puts() in the args argument.  The interpretation of
     the contents of args is dependent solely on the implementation of outc.

     The t_setinfo() function allows the termcap entry contained in the entry
     string to be inserted into the info structure.  Memory sufficient to hold
     the contents of entry is automatically allocated.  This allows the pro-
     grammer to provide a fail over terminal capability string if fetching the
     termcap entry from the termcap database fails.  The format of the string
     entry is assumed to be a valid termcap entry.

     NOTE: A special capability of ZZ is added to the end of the termcap entry
     retrieved.  The number that follows this entry is the address of the
     buffer allocated to hold the full termcap entry.  The caller may retrieve
     the pointer to the extended buffer by performing a tgetstr() to retrieve
     the ZZ capability, the string is the output of a printf() %p and may be
     converted back to a pointer using sscanf() or similar.  The ZZ capability
     is only necessary if the caller wishes to directly manipulate the termcap
     entry, all the termcap function calls automatically use the extended
     buffer to retrieve terminal capabilities.

FILES
     /usr/lib/libtermcap.a    -l termcap library (also known as -l termlib)
     /usr/share/misc/termcap  standard terminal capability data base
     $HOME/.termcap           user's terminal capability data base

SEE ALSO
     ex(1), curses(3), termcap(5)

HISTORY
     The termcap t_*() functions appeared in NetBSD 1.5.  The rest of the
     termcap functions appeared in 4.0BSD.

NetBSD 5.0.1                   December 17, 2006                  NetBSD 5.0.1

You can also request any man page by name and (optionally) by section:

Command: 
Section: 
Architecture: 
Collection: 
 

Use the DEFAULT collection to view manual pages for third-party software.


©1994 Man-cgi 1.15, Panagiotis Christias <christia@softlab.ntua.gr>
©1996-2014 Modified for NetBSD by Kimmo Suominen