Manual Pages for UNIX Darwin command on man setupterm

cursterminfo(3X) cursterminfo(3X)

NAME

ddeellccuurrtteerrmm, mmvvccuurr, ppuuttpp, rreessttaarrtttteerrmm, sseettccuurrtteerrmm, sseetttteerrmm, sseettuupptteerrmm, ttiiggeettffllaagg, ttiiggeettnnuumm, ttiiggeettssttrr, ttppaarrmm, ttppuuttss, vviiddaattttrr, vviiddppuuttss,

vviiddaattttrr, vviiddppuuttss - ccuurrsseess interfaces to terminfo database

SYNOPSIS

##iinncclluuddee <>

iinntt sseettuupptteerrmm((cchhaarr **term,, iinntt fildes,, iinntt **errret));; iinntt sseetttteerrmm((cchhaarr **term));; TTEERRMMIINNAALL **sseettccuurrtteerrmm((TTEERRMMIINNAALL **nterm));; iinntt ddeellccuurrtteerrmm((TTEERRMMIINNAALL **oterm));; iinntt rreessttaarrtttteerrmm((ccoonnsstt cchhaarr **term,, iinntt fildes,, iinntt **errret));; cchhaarr **ttppaarrmm((cchhaarr **str,, ......));; iinntt ttppuuttss((ccoonnsstt cchhaarr **str,, iinntt affcnt,, iinntt ((**putc))((iinntt))));; iinntt ppuuttpp((ccoonnsstt cchhaarr **str));; iinntt vviiddppuuttss((cchhttyyppee attrs,, iinntt ((**putc))((iinntt))));; iinntt vviiddaattttrr((cchhttyyppee attrs));; iinntt vviiddppuuttss((aattttrrtt attrs,, sshhoorrtt pair,, vvooiidd **opts,, iinntt ((**putc))((cchhaarr))));; iinntt vviiddaattttrr((aattttrrtt attrs,, sshhoorrtt pair,, vvooiidd **opts));; iinntt mmvvccuurr((iinntt oldrow,, iinntt oldcol,, iinntt newrow, int newcol));; iinntt ttiiggeettffllaagg((cchhaarr **capname));; iinntt ttiiggeettnnuumm((cchhaarr **capname));; cchhaarr **ttiiggeettssttrr((cchhaarr **capname));;

DESCRIPTION

These low-level routines must be called by programs that have to deal

directly with the tteerrmmiinnffoo database to handle certain terminal capabil-

ities, such as programming function keys. For all other functionality, ccuurrsseess routines are more suitable and their use is recommended.

Initially, sseettuupptteerrmm should be called. Note that sseettuupptteerrmm is automat-

ically called by iinniittssccrr and nneewwtteerrmm. This defines the set of termi-

nal-dependent variables [listed in tteerrmmiinnffoo(5)]. The tteerrmmiinnffoo vari-

ables lliinneess and ccoolluummnnss are initialized by sseettuupptteerrmm as follows: If uusseeeennvv((FFAALLSSEE)) has been called, values for lliinneess and ccoolluummnnss specified in tteerrmmiinnffoo are used. Otherwise, if the environment variables LLIINNEESS

and CCOOLLUUMMNNSS exist, their values are used. If these environment vari-

ables 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 lliinneess and ccoolluummnnss specified in the tteerrmmiinnffoo data-

base are used. The header files ccuurrsseess..hh and tteerrmm..hh should be included (in this order)

to get the definitions for these strings, numbers, and flags. Parame-

terized strings should be passed through ttppaarrmm to instantiate them. All tteerrmmiinnffoo strings [including the output of ttppaarrmm] should be printed with ttppuuttss or ppuuttpp. Call the rreesseettsshheellllmmooddee to restore the tty modes

before exiting [see ccuurrsskkeerrnneell(3X)]. Programs which use cursor ad-

dressing should output eenntteerrccaammooddee upon startup and should output eexx-

iittccaammooddee before exiting. Programs desiring shell escapes should call rreesseettsshheellllmmooddee and output eexxiittccaammooddee before the shell is called and should output eenntteerrccaammooddee and call rreesseettpprrooggmmooddee after returning from the shell. The sseettuupptteerrmm routine reads in the tteerrmmiinnffoo database, initializing the tteerrmmiinnffoo structures, but does not set up the output virtualization structures used by ccuurrsseess. The terminal type is the character string

term; if term is null, the environment variable TTEERRMM is used. All out-

put is to file descriptor ffiillddeess which is initialized for output. If

errret is not null, then sseettuupptteerrmm returns OOKK or EERRRR and stores a sta-

tus value in the integer pointed to by errret. A return value of OOKK

combined with status of 11 in errret is normal. If EERRRR is returned, ex-

amine errret: 11 means that the terminal is hardcopy, cannot be used for curses applications. 00 means that the terminal could not be found, or that it is a

generic type, having too little information for curses ap-

plications to run.

-11 means that the tteerrmmiinnffoo database could not be found.

If errret is null, sseettuupptteerrmm prints an error message upon finding an error and exits. Thus, the simplest call is: sseettuupptteerrmm((((cchhaarr **))00,, 11,, ((iinntt **))00));;, which uses all the defaults and sends the output to ssttddoouutt. The sseetttteerrmm routine is being replaced by sseettuupptteerrmm. The call: sseettuupptteerrmm((term,, 11,, ((iinntt **))00)) provides the same functionality as sseetttteerrmm((term)). The sseetttteerrmm routine is included here for BSD compatibility, and is not recommended for new programs. The sseettccuurrtteerrmm routine sets the variable ccuurrtteerrmm to nterm, and makes

all of the tteerrmmiinnffoo boolean, numeric, and string variables use the val-

ues from nterm. It returns the old value of ccuurrtteerrmm. The ddeellccuurrtteerrmm routine frees the space pointed to by oterm and makes

it available for further use. If oterm is the same as ccuurrtteerrmm, refer-

ences to any of the tteerrmmiinnffoo boolean, numeric, and string variables

thereafter may refer to invalid memory locations until another ssee-

ttuupptteerrmm has been called. The rreessttaarrtttteerrmm routine is similar to sseettuupptteerrmm and iinniittssccrr, except

that it is called after restoring memory to a previous state (for exam-

ple, 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.

Accordingly, it saves various tty state bits, does a setupterm, and

then restores the bits. The ttppaarrmm routine instantiates the string str with parameters pi. A pointer is returned to the result of str with the parameters applied. The ttppuuttss routine applies padding information to the string str and outputs it. The str must be a terminfo string variable or the return

value from ttppaarrmm, ttggeettssttrr, or ttggoottoo. affcnt is the number of lines af-

fected, or 1 if not applicable. putc is a ppuuttcchhaarr-like routine to

which the characters are passed, one at a time. The ppuuttpp routine calls ttppuuttss((str,, 11,, ppuuttcchhaarr)). Note that the output of ppuuttpp always goes to ssttddoouutt, not to the fildes specified in sseettuupptteerrmm. The vviiddppuuttss routine displays the string on the terminal in the video attribute mode attrs, which is any combination of the attributes listed

in ccuurrsseess(3X). The characters are passed to the ppuuttcchhaarr-like routine

putc. The vviiddaattttrr routine is like the vviiddppuuttss routine, except that it outputs through ppuuttcchhaarr. The vviiddaattttrr and vviiddppuuttss 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 attrt for the attributes and

one of short for the colorpair number. The vviiddaattttrr and vviiddppuuttss rou-

tines 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 mmvvccuurr routine provides low-level cursor motion. It takes effect

immediately (rather than at the next refresh). The ttiiggeettffllaagg, ttiiggeettnnuumm and ttiiggeettssttrr routines return the value of the capability corresponding to the tteerrmmiinnffoo capname passed to them, such as xxeennll.

The ttiiggeettffllaagg routine returns the value -11 if capname is not a boolean

capability, or 00 if it is canceled or absent from the terminal descrip-

tion.

The ttiiggeettnnuumm routine returns the value -22 if capname is not a numeric

capability, or -11 if it is canceled or absent from the terminal de-

scription.

The ttiiggeettssttrr routine returns the value ((cchhaarr **))-11 if capname is not a

string capability, or 00 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 tteerrmmiinnffoo(5). cchhaarr **bboooollnnaammeess, **bboooollccooddeess, **bboooollffnnaammeess cchhaarr **nnuummnnaammeess, **nnuummccooddeess, **nnuummffnnaammeess cchhaarr **ssttrrnnaammeess, **ssttrrccooddeess, **ssttrrffnnaammeess

These null-terminated arrays contain the capnames, the tteerrmmccaapp codes,

and the full C names, for each of the tteerrmmiinnffoo variables. RREETTUURRNN VVAALLUUEE Routines that return an integer return EERRRR upon failure and OOKK (SVr4

only specifies "an integer value other than EERRRR") upon successful com-

pletion, unless otherwise noted in the preceding routine descriptions. Routines that return pointers always return NNUULLLL on error. X/Open defines no error conditions. In this implementation ddeellccuurrtteerrmm returns an error if its terminal parameter is null. rreessttaarrtttteerrmm

returns an error if the associated call to sseettuupptteerrmm re-

turns an error. sseettuupptteerrmm returns an error if it cannot allocate enough memory, or create the initial windows (stdscr, curscr, newscr). Other error conditions are documented above. NNOOTTEESS The sseettuupptteerrmm routine should be used in place of sseetttteerrmm. It may be

useful when you want to test for terminal capabilities without commit-

ting to the allocation of storage involved in iinniittssccrr. Note that vviiddaattttrr and vviiddppuuttss may be macros. PPOORRTTAABBIILLIITTYY The function sseetttteerrmm 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, sseettccuurrtteerrmm has an iinntt return type and returns OOKK or EERRRR. We have chosen to implement the XSI Curses semantics. In System V Release 4, the third argument of ttppuuttss has the type iinntt ((**ppuuttcc))((cchhaarr)).

The XSI Curses standard prototypes ttppaarrmm with a fixed number of parame-

ters, rather than a variable argument list. This implementation uses a

variable argument list. Portable applications should provide 9 parame-

ters after the format; zeroes are fine for this purpose. XSI notes that after calling mmvvccuurr, 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 Sys-

tem V Release 4 curses implement mmvvccuurr using the SCREEN data allocated in either iinniittssccrr or nneewwtteerrmm. So though it is documented as a terminfo

function, mmvvccuurr is really a curses function which is not well speci-

fied.