X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_terminfo.3x.html;h=51e41701dab1f8120617499df0508d1d12cba2d6;hp=8a53cbca02647006654e829d041d1a128a7e1542;hb=ca276baf720e3a44721b9e18955d3f546955c6c8;hpb=b1f61d9f3aa244512045a6b02e759825d7049d34 diff --git a/doc/html/man/curs_terminfo.3x.html b/doc/html/man/curs_terminfo.3x.html index 8a53cbca..51e41701 100644 --- a/doc/html/man/curs_terminfo.3x.html +++ b/doc/html/man/curs_terminfo.3x.html @@ -1,291 +1,335 @@ + + +
++curs_terminfo(3x) curs_terminfo(3x) + + +
- setupterm, setterm, set_curterm, del_curterm, restartterm, - tparm, tputs, putp, vidputs, vidattr, mvcur, tigetflag, - tigetnum, tigetstr - curses interfaces to terminfo - database + 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
- #include <curses.h> - #include <term.h> - - int setupterm(const char *term, int fildes, int *errret); - int setterm(const char *term); - TERMINAL *set_curterm(TERMINAL *nterm); - int del_curterm(TERMINAL *oterm); - int restartterm(const char *term, int fildes, int - *errret); - char *tparm(const char *str, ...); - int tputs(const char *str, int affcnt, int (*putc)(int)); - int putp(const char *str); - int vidputs(chtype attrs, int (*putc)(char)); - int vidattr(chtype attrs); - int mvcur(int oldrow, int oldcol, int newrow, int newcol); - int tigetflag(const char *capname); - int tigetnum(const char *capname); - char *tigetstr(const char *capname); + #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(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);
These low-level routines must be called by programs that - have to deal directly with the terminfo database to handle + have to deal directly with the terminfo database to handle certain terminal capabilities, such as programming func- - tion keys. For all other functionality, curses routines + tion 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. + Initially, setupterm should be called. Note that se- + tupterm is automatically called by initscr and newterm. This defines 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 terminfo are used. Otherwise, if the - environment variables LINES and COLUMNS exist, their val- - ues 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 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, + [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 terminfo are used. + + Otherwise, if the environment variables LINES and + COLUMNS exist, their values are used. If these en- + vironment 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 for lines and columns speci- + fied 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 [including 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(3x)]. - 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 + passed through tparm to instantiate them. All terminfo + strings [including 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(3x)]. Pro- + grams which use cursor addressing should output en- + ter_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 ter- - minal 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 + reset_shell_mode and output exit_ca_mode before the shell + is called and should output enter_ca_mode and call re- + set_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 ter- + minal 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 er- + rret. 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 + 0 means that the terminal could not be found, or + that it is a generic type, having too little information for curses applications to run. - -1 means that the terminfo database could not be + -1 means that the terminfo database could not be found. - If errret is null, setupterm prints an error message upon + 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);, + setupterm((char *)0, 1, (int *)0);, - which uses all the defaults and sends the output to std- - out. + which uses all the defaults and sends the output to std- + out. - The setterm routine is being replaced by setupterm. The + The setterm routine is being replaced by setupterm. The call: - setupterm(term, 1, (int *)0) + setupterm(term, 1, (int *)0) - provides the same functionality as setterm(term). The - setterm routine is included here for BSD compatibility, + provides the same functionality as setterm(term). The + setterm 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. + 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. - 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 invalid memory locations until another setupterm + 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 re- + fer to invalid 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 previous state (for example, when reloading a game - saved as a core image dump). It assumes that the windows + The restartterm routine is similar to setupterm and + initscr, except that it is called after restoring memory + to a previous 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 mem- - ory 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. + ory was saved, but the terminal type and baud rate may be + different. Accordingly, it saves various tty state bits, + calls setupterm, 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 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 variable or the return value from tparm, tgetstr, - or tgoto. affcnt is the number of lines affected, or 1 if - not applicable. putc is a putchar-like routine to which + The tputs routine applies padding information to the + string str and outputs it. The str must be a terminfo + string variable or the return value from tparm, tgetstr, + or tgoto. affcnt is the number of lines affected, or 1 if + not applicable. 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(3x). 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 mvcur routine provides low-level cursor motion. It - takes effect immediately (rather than at the next - refresh). - - 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 + 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(3x). 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, applications 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 re- + fresh). + + 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 tigetnum routine returns the value -2 if capname is + not a numeric capability, or -1 if it is canceled or ab- + sent 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 tigetstr routine returns the value (char *)-1 if cap- + name 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 col- - umn entitled capname code in the capabilities section of - terminfo(5). + The capname for each capability is given in the table col- + umn entitled capname code in the capabilities section of + terminfo(5). - char *boolnames, *boolcodes, *boolfnames + char *boolnames[], *boolcodes[], *boolfnames[] - char *numnames, *numcodes, *numfnames + char *numnames[], *numcodes[], *numfnames[] - char *strnames, *strcodes, *strfnames + char *strnames[], *strcodes[], *strfnames[] - These null-terminated arrays contain the capnames, the - termcap codes, and the full C names, for each of the ter- - minfo variables. + These null-terminated arrays contain the capnames, the + termcap codes, and the full C names, for each of the ter- + minfo variables.
- 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 + 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. + Routines that return pointers always return NULL on error. + + X/Open defines no error conditions. In this implementa- + tion + + del_curterm + returns an error if its terminal parameter is + null. + + restartterm + returns an error if the associated call to se- + tupterm 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 + documented above.
- The setupterm routine should be used in place of setterm. - It may be useful when you want to test for terminal capa- - bilities without committing to the allocation of storage - involved in initscr. + The setupterm routine should be used in place of setterm. + It may be useful when you want to test for terminal capa- + bilities without committing to the allocation of storage + involved in initscr. - Note that vidattr and vidputs may be macros. + Note that vidattr and vidputs may be macros.
- The function setterm is not described in the XSI Curses - standard and must be considered non-portable. All other + 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 + setupterm copies the terminal name to the array ttytype. + This is not part of X/Open Curses, but is assumed by some + applications. + + 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). + 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 num- - ber of parameters, rather than a variable argument list. + The XSI Curses standard prototypes tparm with a fixed num- + ber of parameters, rather than a variable argument list. + This implementation uses a variable argument list. + Portable applications should provide 9 parameters after + the format; zeroes are fine for this purpose. - XSI notes that after calling mvcur, the curses state may + XSI notes that after calling mvcur, the curses state may not match the actual terminal state, and that an applica- tion should touch and refresh the window before resuming normal curses calls. Both ncurses and System V Release 4 - curses implement mvcur using the SCREEN data allocated in - either initscr or newterm. So though it is documented as - a terminfo function, mvcur is really a curses function + curses implement mvcur using the SCREEN data allocated in + either initscr or newterm. So though it is documented as + a terminfo function, mvcur is really a curses function which is not well specified. + XSI states that the old location must be given for mvcur. + This implementation allows the caller to use -1's for the + old ordinates. In that case, the old location is unknown. --
- curses(3x), curs_initscr(3x), curs_kernel(3x), curs_term- - cap(3x), putc(3S), terminfo(5) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + Extended terminal capability names, e.g., as defined by + tic -x, are not stored in the arrays described in this + section. ++
+ curses(3x), curs_initscr(3x), curs_kernel(3x), curs_term- + cap(3x), putc(3), terminfo(5) + curs_terminfo(3x)