Movatterモバイル変換

SYNOPSIS top

#include <curses.h>#include <term.h>TERMINAL *cur_term;const char * const boolnames[];const char * const boolcodes[];const char * const boolfnames[];const char * const numnames[];const char * const numcodes[];const char * const numfnames[];const char * const strnames[];const char * const strcodes[];const char * const strfnames[];int setupterm(const char *term, intfiledes, int *errret);TERMINAL *set_curterm(TERMINAL *nterm);int del_curterm(TERMINAL *oterm);int restartterm(const char *term, intfiledes, int *errret);char *tparm(const char *str, ...);int tputs(const char *str, intaffcnt, int (*putc)(int));int putp(const char *str);int vidputs(chtypeattrs, int (*putc)(int));int vidattr(chtypeattrs);int vid_puts(attr_tattrs, shortpair, void *opts, int (*putc)(int));int vid_attr(attr_tattrs, shortpair, void *opts);int mvcur(intoldrow, intoldcol, intnewrow, intnewcol);int tigetflag(const char *capname);int tigetnum(const char *capname);char *tigetstr(const char *capname);char *tiparm(const char *str, ...);

DESCRIPTION top

These low-level routines must be called by programs that have to deal directly with theterminfodatabase to handle certain termi‐ nal capabilities, such as programming function keys. For all oth‐ er functionality,cursesroutines are more suitable and their use is recommended. None of these functions use (or are aware of) multibyte character strings such as UTF-8: • capability names use the POSIX portable character set • capability string values have no associated encoding; they are strings of 8-bit characters.Initialization Initially,setuptermshould be called. The high-level curses functionsinitscrandnewtermcallsetuptermto initialize the low-level set of terminal-dependent variables [listed intermin‐fo(5)]. Applications can use the terminal capabilities either directly (via header definitions), or by special functions. The header filescurses.handterm.hshould be included (in this order) to get the definitions for these strings, numbers, and flags. Theterminfovariableslinesandcolumnsare initialized byse‐tuptermas follows: • Ifuse_env(FALSE)has been called, values forlinesandcolumnsspecified interminfoare used. • Otherwise, if the environment variablesLINESandCOLUMNSex‐ ist, 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 forlinesandcolumnsspecified in theterminfodatabase are used. Parameterized strings should be passed throughtparmto instanti‐ ate them. Allterminfostrings (including the output oftparm) should be printed withtputsorputp. Callreset_shell_modeto restore the tty modes before exiting [seecurs_kernel(3X)]. Programs which use cursor addressing should • outputenter_ca_modeupon startup and • outputexit_ca_modebefore exiting. Programs which execute shell subprocesses should • callreset_shell_modeand outputexit_ca_modebefore the shell is called and • outputenter_ca_modeand callreset_prog_modeafter returning from the shell. Thesetuptermroutine reads in theterminfodatabase, initializing theterminfostructures, but does not set up the output virtual‐ ization structures used bycurses. These are its parameters:term is the terminal type, a character string. Ifterm is null, the environment variableTERMis used.filedes is the file descriptor used for all output.errret points to an optional location where an error status can be returned to the caller. Iferrret is not null, thensetuptermreturnsOKorERRand stores a status value in the integer pointed to byerrret. A return value ofOK combined with status of1inerrret is normal. IfERRis returned, examineerrret:1means that the terminal is hardcopy, cannot be used for curses applications.setuptermdetermines if the entry is a hardcopy type by checking thehc(hardcopy) capability.0means that the terminal could not be found, or that it is a generic type, having too little information for curses applications to run.setuptermdetermines if the entry is a generic type by checking thegn(generic) capability.-1means that theterminfodatabase could not be found. Iferrret is null,setuptermprints 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 tostd‐out.The Terminal State Thesetuptermroutine stores its information about the terminal in aTERMINALstructure pointed to by the global variablecur_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. Ifsetuptermis 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,setuptermallocates new storage for each set of terminal capabilities. Theset_curtermroutine setscur_termtonterm, and makes all of theterminfoboolean, numeric, and string variables use the values fromnterm. It returns the old value ofcur_term. Thedel_curtermroutine frees the space pointed to byoterm and makes it available for further use. Ifoterm is the same ascur_term, references to any of theterminfoboolean, numeric, and string variables thereafter may refer to invalid memory locations until anothersetuptermhas been called. Therestarttermroutine is similar tosetuptermandinitscr, ex‐ cept that it is called after restoring memory to a previous state (for example, when reloading a game saved as a core image dump).restarttermassumes that the windows and the input and output op‐ tions are the same as when memory was saved, but the terminal type and baud rate may be different. Accordingly,restarttermsaves various tty state bits, callssetupterm, and then restores the bits.Formatting Output Thetparmroutine instantiates the stringstr with parameterspi. A pointer is returned to the result ofstr with the parameters ap‐ plied. Application developers should keep in mind these quirks of the interface: • Althoughtparm's actual parameters may be integers or strings, the prototype expectslong(integer) values. • Aside from theset_attributes(sgr) capability, most terminal capabilities require no more than one or two parameters. • Padding information is ignored bytparm; it is interpreted bytputs. • The capability string is null-terminated. Use “\200” where an ASCII NUL is needed in the output.tiparmis a newer form oftparmwhich uses<stdarg.h> rather than a fixed-parameter list. Its numeric parameters are integers (int) rather than longs.Output Functions Thetputsroutine applies padding information (i.e., by interpret‐ ing marker embedded in the terminfo capability such as “$<5>” as 5 milliseconds) to the stringstr and outputs it: • Thestr parameter must be a terminfo string variable or the return value fromtparm,tiparm,tgetstr, ortgoto. Thetgetstrandtgotofunctions are part of thetermcap inter‐ face, which happens to share this function name with theter‐minfo interface. •affcnt is the number of lines affected, or 1 if not applica‐ ble. •putc is aputchar-like routine to which the characters are passed, one at a time. Theputproutine callstputs(str, 1, putchar). The output ofputp always goes tostdout, rather than thefiledes specified inse‐tupterm. Thevidputsroutine displays the string on the terminal in the video attribute modeattrs, which is any combination of the at‐ tributes listed incurses(3X). The characters are passed to theputchar-like routineputc. Thevidattrroutine is like thevidputsroutine, except that it outputs throughputchar. Thevid_attrandvid_putsroutines correspond to vidattr and vid‐ puts, respectively. They use a set of arguments for representing the video attributes plus color, i.e., •attrs of typeattr_tfor the attributes and •pair of typeshortfor the color-pair number. Thevid_attrandvid_putsroutines are designed to use the at‐ tribute constants with theWA_prefix. X/Open Curses reserves theopts argument for future use, saying that applications must provide a null pointer for that argument. As an extension, this implementation allowsopts to be used as a pointer toint, which overrides thepair (short) argument. Themvcurroutine provides low-level cursor motion. It takes ef‐ fect immediately (rather than at the next refresh). Whileputpandmvcurare low-level functions which do not use the high-level curses state, they are declared in<curses.h>because SystemV did this (seeHISTORY).Terminal Capability Functions Thetigetflag,tigetnumandtigetstrroutines return the value of the capability corresponding to theterminfocapname passed to them, such asxenl. Thecapname for each capability is given in the table column entitledcapname code in the capabilities section ofterminfo(5). These routines return special values to denote errors. Thetigetflagroutine returns-1ifcapname is not a boolean capability, or0if it is canceled or absent from the terminal description. Thetigetnumroutine returns-2ifcapname is not a numeric capability, or-1if it is canceled or absent from the terminal description. Thetigetstrroutine returns(char *)-1 ifcapname is not a string capability, or0if it is canceled or absent from the terminal description.Terminal Capability Names These null-terminated arrays contain • the short terminfo names (“codes”), • thetermcapnames (“names”), and • the long terminfo names (“fnames”) for each of the predefinedterminfovariables:const char *boolnames[],*boolcodes[],*boolfnames[]const char *numnames[],*numcodes[],*numfnames[]const char *strnames[],*strcodes[],*strfnames[]Releasing Memory Each successful call tosetuptermallocates memory to hold the terminal description. As a side-effect, it setscur_termto point to this memory. If an application callsdel_curterm(cur_term); the memory will be freed. The formatting functionstparmandtiparmextend the storage allo‐ cated bysetupterm: • the “static” terminfo variables [a-z]. Before ncurses 6.3, those were shared by all screens. With ncurses 6.3, those are allocated per screen. Seeterminfo(5) for details. • to improve performance, ncurses 6.3 caches the result of ana‐ lyzing terminfo strings for their parameter types. That is stored as a binary tree referenced from theTERMINALstruc‐ ture. The higher-levelinitscrandnewtermfunctions usesetupterm. Normally they do not free this memory, but it is possible to do that using thedelscreen(3X) function.

RETURN VALUE top

Routines that return an integer returnERRupon failure andOK (SVr4 only specifies “an integer value other thanERR”) upon suc‐ cessful completion, unless otherwise noted in the preceding rou‐ tine descriptions. Routines that return pointers always returnNULLon error. X/Open defines no error conditions. In this implementationdel_curterm returns an error if its terminal parameter is null.putpcallstputs, returning the same error-codes.restartterm returns an error if the associated call tosetuptermre‐ turns an error.setupterm returns an error if it cannot allocate enough memory, or create the initial windows (stdscr, curscr, newscr). Oth‐ er 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 thattputsignores the return value of the output functionputc.Compatibility macros This implementation provides a few macros for compatibility with systems before SVr4 (seeHISTORY). Those includecrmode,fixterm,gettmode,nocrmode,resetterm,saveterm, andsetterm. In SVr4, those are found in<curses.h>, but except forsetterm, are likewise macros. The one function,setterm, is mentioned in the manual page. The manual page notes that thesettermroutine was replaced bysetupterm, stating that the call:setupterm(term, 1, (int *)0) provides the same functionality assetterm(term), and is not rec‐ ommended for new programs. This implementation provides each of those symbols as macros for BSD compatibility,

HISTORY top

SVr2 introduced the terminfo feature. Its programming manual men‐ tioned these low-level functions:Function Description ──────────────────────────────────────────────────────────── fixterm restore tty to “in curses” state gettmode establish current tty modes mvcur low level cursor motion putp utility function that usestputsto send char‐ acters viaputchar. resetterm set tty modes to “out of curses” state resetty reset tty flags to stored value saveterm save current modes as “in curses” state savetty store current tty flags setterm establish terminal with given type setupterm establish terminal with given type tparm instantiate a string expression with parameters tputs apply padding information to a string vidattr likevidputs, but outputs throughputchar vidputs output a string to put terminal in a specified video attribute mode The programming manual also mentioned functions provided for term‐ cap compatibility (commenting that they “may go away at a later date”):Function Description ──────────────────────────────────────────────── tgetent look up termcap entry for givenname tgetflag get boolean entry for givenid tgetnum get numeric entry for givenid tgetstr get string entry for givenid tgoto apply parameters to given capability tputs apply padding to capability, calling a function to put characters Early terminfo programs obtained capability values from theTERMI‐NALstructure initialized bysetupterm. SVr3 extended terminfo by adding functions to retrieve capability values (like the termcap interface), and reusing tgoto and tputs:Function Description ─────────────────────────────────────────── tigetflag get boolean entry for givenid tigetnum get numeric entry for givenid tigetstr get string entry for givenid SVr3 also replaced several of the SVr2 terminfo functions which had no counterpart in the termcap interface, documenting them as obsolete:Function Replaced by ───────────────────────────── crmode cbreak fixterm reset_prog_mode gettmode N/A nocrmode nocbreak resetterm reset_shell_mode saveterm def_prog_mode setterm setupterm SVr3 kept themvcur,vidattrandvidputsfunctions, along withputp,tparmandtputs. The latter were needed to support padding, and handling functions such asvidattr(which used more than the two parameters supported bytgoto). SVr3 introduced the functions for switching between terminal de‐ scriptions, e.g.,set_curterm. Some of that was incremental im‐ provements to the SVr2 library: • TheTERMINALtype definition was introduced in SVr3.01, for thetermstructure provided in SVr2. • The various global variables such asboolnameswere mentioned in the programming manual at this point, though the variables were provided in SVr2. SVr4 added thevid_attrandvid_putsfunctions. There are other low-level functions declared in the curses header files on Unix systems, but none were documented. The functions marked “obsolete” remained in use by the Unixvi(1) editor.

PORTABILITY top

Legacy functions X/Open notes thatvidattrandvidputsmay be macros. The functionsettermis not described by X/Open and must be con‐ sidered non-portable. All other functions are as described by X/Open.Legacy datasetuptermcopies the terminal name to the arrayttytype. This is not part of X/Open Curses, but is assumed by some applications. 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 bytic -x, are not stored in the arrays described here.Output buffering Older versions ofncursesassumed that the file descriptor passed tosetuptermfrominitscrornewtermuses 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 System V curses), it was problematic becausencursesdid not allow a reliable way to cleanup on receiving SIGTSTP. The current version (ncurses6) uses output buffers managed direct‐ ly byncurses. 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 inncursesuse alternate versions of these functions using the more reliable buffering scheme.Function prototypes The X/Open Curses prototypes are based on the SVr4 curses header declarations, which were defined at the same time the C language was first standardized in the late 1980s. • X/Open Curses usesconstless effectively than a later design might, in some cases applying it needlessly to values are al‐ ready constant, and in most cases overlooking parameters which normally would useconst. Using constant parameters for func‐ tions which do not useconstmay prevent the program from com‐ piling. On the other hand,writable strings are an obsoles‐ cent feature. As an extension, this implementation can be configured to change the function prototypes to use theconstkeyword. The ncurses ABI 6 enables this feature by default. • X/Open Curses prototypestparmwith a fixed number of parame‐ ters, rather than a variable argument list. This implementation uses a variable argument list, but can be configured to use the fixed-parameter list. Portable applica‐ tions should provide 9 parameters after the format; zeroes are fine for this purpose. In response to review comments by Thomas E. Dickey, X/Open Curses Issue 7 proposed thetiparmfunction in mid-2009.Special TERM treatment If configured to use the terminal-driver, e.g., for the MinGW port, •setupterminterprets a missing/empty TERM variable as the spe‐ cial value “unknown”. •setuptermallows explicit use of the the windows console dri‐ ver by checking if $TERM is set to “#win32con” or an abbrevia‐ tion of that string.Other portability issues In System V Release 4,set_curtermhas anintreturn type and re‐ turnsOKorERR. We have chosen to implement the X/Open Curses semantics. In System V Release 4, the third argument oftputshas the typeint (*putc)(char). At least one implementation of X/Open Curses (Solaris) returns a value other thanOK/ERRfromtputs. That returns the length of the string, and does no error-checking. X/Open notes that after callingmvcur, 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. Bothncursesand System V Release 4 curses implementmvcurusing the SCREEN data allocated in eitherinitscrornewterm. So though it is documented as a terminfo function,mvcuris really a curses function which is not well specified. X/Open states that the old location must be given formvcur. This implementation allows the caller to use -1's for the old ordi‐ nates. In that case, the old location is unknown.

COLOPHON top

This page is part of thencurses (new curses) project. Informa‐ tion about the project can be found at ⟨https://www.gnu.org/software/ncurses/ncurses.html⟩. If you have a bug report for this manual page, send it to bug-ncurses-request@gnu.org. This page was obtained from the project's upstream Git mirror of the CVS repository ⟨https://github.com/mirror/ncurses.git⟩ on 2025-08-11. (At that time, the date of the most recent commit that was found in the repository was 2023-03-12.) If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up-to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgcurs_terminfo(3X)

HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface.

For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere.

Hosting byjambit GmbH.

ページ先頭