X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_terminfo.3x;h=9120a04b9a9820406ddb77b8edd25beb81665e9a;hp=098a094383050376491d28ee665525e693fb7742;hb=HEAD;hpb=0eb88fc5281804773e2a0c7a488a4452463535ce diff --git a/man/curs_terminfo.3x b/man/curs_terminfo.3x index 098a0943..580f29d8 100644 --- a/man/curs_terminfo.3x +++ b/man/curs_terminfo.3x @@ -1,5 +1,7 @@ +'\" t .\"*************************************************************************** -.\" Copyright (c) 1999 Free Software Foundation, Inc. * +.\" Copyright 2018-2023,2024 Thomas E. Dickey * +.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * .\" copy of this software and associated documentation files (the * @@ -26,238 +28,1058 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_terminfo.3x,v 1.12 1999/10/17 01:11:59 tom Exp $ -.TH curs_terminfo 3X "" -.ds n 5 +.\" $Id: curs_terminfo.3x,v 1.138 2024/05/25 21:02:40 tom Exp $ +.TH curs_terminfo 3X 2024-05-25 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls" +.ie \n(.g \{\ +.ds `` \(lq +.ds '' \(rq +.\} +.el \{\ +.ie t .ds `` `` +.el .ds `` "" +.ie t .ds '' '' +.el .ds '' "" +.\} +. +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +. .SH NAME -\fBsetupterm\fR, \fBsetterm\fR, -\fBset_curterm\fR, \fBdel_curterm\fR, \fBrestartterm\fR, \fBtparm\fR, -\fBtputs\fR, \fBputp\fR, \fBvidputs\fR, \fBvidattr\fR, \fBmvcur\fR, -\fBtigetflag\fR, \fBtigetnum\fR, \fBtigetstr\fR - \fBcurses\fR -interfaces to terminfo database +\fB\%del_curterm\fP, +\fB\%putp\fP, +\fB\%restartterm\fP, +\fB\%set_curterm\fP, +\fB\%setupterm\fP, +\fB\%tigetflag\fP, +\fB\%tigetnum\fP, +\fB\%tigetstr\fP, +\fB\%tiparm\fP, +\fB\%tiparm_s\fP, +\fB\%tiscan_s\fP, +\fB\%tparm\fP, +\fB\%tputs\fP, +\fB\%vid_attr\fP, +\fB\%vid_puts\fP, +\fB\%vidattr\fP, +\fB\%vidputs\fP \- +\fIcurses\fR interfaces to \fI\%term\%info\fR database .SH SYNOPSIS -\fB#include \fR -.br -\fB#include \fR - -\fBint setupterm(const char *term, int fildes, int *errret);\fR -.br -\fBint setterm(const char *term);\fR -.br -\fBTERMINAL *set_curterm(TERMINAL *nterm);\fR -.br -\fBint del_curterm(TERMINAL *oterm);\fR -.br -\fBint restartterm(const char *term, int fildes, int *errret);\fR -.br -\fBchar *tparm(const char *str, ...);\fR -.br -\fBint tputs(const char *str, int affcnt, int (*putc)(int));\fR -.br -\fBint putp(const char *str);\fR -.br -\fBint vidputs(chtype attrs, int (*putc)(char));\fR -.br -\fBint vidattr(chtype attrs);\fR -.br -\fBint mvcur(int oldrow, int oldcol, int newrow, int newcol);\fR -.br -\fBint tigetflag(const char *capname);\fR -.br -\fBint tigetnum(const char *capname);\fR -.br -\fBchar *tigetstr(const char *capname);\fR -.br +.nf +\fB#include +\fB#include +.PP +\fBTERMINAL *cur_term; +.PP +\fBconst char * const boolnames[]; +\fBconst char * const boolcodes[]; +\fBconst char * const boolfnames[]; +\fBconst char * const numnames[]; +\fBconst char * const numcodes[]; +\fBconst char * const numfnames[]; +\fBconst char * const strnames[]; +\fBconst char * const strcodes[]; +\fBconst char * const strfnames[]; +.PP +\fBint setupterm(const char *\fIterm\fP, int \fIfiledes\fP, int *\fIerrret\fP); +\fBTERMINAL *set_curterm(TERMINAL *\fInterm\fP); +\fBint del_curterm(TERMINAL *\fIoterm\fP); +\fBint restartterm(const char *\fIterm\fP, int \fIfiledes\fP, int *\fIerrret\fP); +.PP +\fBchar *tparm(const char *\fIstr\fP, \fR.\|.\|.\fP); + \fI/* or */ +\fBchar *tparm(const char *\fIstr\fP, long \fIp1\fP \fR.\|.\|.\fP \fBlong\fP \fIp9\fP); +.PP +\fBint tputs(const char *\fIstr\fP, int \fIaffcnt\fP, int (*\fIputc\fP)(int)); +\fBint putp(const char *\fIstr\fP); +.PP +\fBint vidputs(chtype \fIattrs\fP, int (*\fIputc\fP)(int)); +\fBint vidattr(chtype \fIattrs\fP); +\fBint vid_puts(attr_t \fIattrs\fP, short \fIpair\fP, void *\fIopts\fP, int (*\fIputc\fP)(int)); +\fBint vid_attr(attr_t \fIattrs\fP, short \fIpair\fP, void *\fIopts\fP); +.PP +\fBint tigetflag(const char *\fIcap-code\fP); +\fBint tigetnum(const char *\fIcap-code\fP); +\fBchar *tigetstr(const char *\fIcap-code\fP); +.PP +\fBchar *tiparm(const char *\fIstr\fP, \fR.\|.\|.\fP); +.PP +\fI/* extensions */ +\fBchar *tiparm_s(int \fIexpected\fP, int \fImask\fP, const char *\fIstr\fP, ...); +\fBint tiscan_s(int *\fIexpected\fP, int *\fImask\fP, const char *\fIstr\fP); +.PP +\fI/* deprecated */ +\fBint setterm(const char *\fIterm\fP); +.fi .SH DESCRIPTION -These low-level routines must be called by programs that have to deal -directly with the \fBterminfo\fR database to handle certain terminal -capabilities, such as programming function keys. For all other -functionality, \fBcurses\fR routines are more suitable and their use is -recommended. - -Initially, \fBsetupterm\fR should be called. Note that -\fBsetupterm\fR is automatically called by \fBinitscr\fR and -\fBnewterm\fR. This defines the set of terminal-dependent variables -[listed in \fBterminfo\fR(\*n)]. The \fBterminfo\fR variables -\fBlines\fR and \fBcolumns\fR are initialized by \fBsetupterm\fR as -follows: If \fBuse_env(FALSE)\fR has been called, values for -\fBlines\fR and \fBcolumns\fR specified in \fBterminfo\fR are used. -Otherwise, if the environment variables \fBLINES\fR and \fBCOLUMNS\fR -exist, 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 for \fBlines\fR and \fBcolumns\fR specified in the -\fBterminfo\fR database are used. - -The header files \fBcurses.h\fR and \fBterm.h\fR should be included (in this -order) to get the definitions for these strings, numbers, and flags. -Parameterized strings should be passed through \fBtparm\fR to instantiate them. -All \fBterminfo\fR strings [including the output of \fBtparm\fR] should be printed -with \fBtputs\fR or \fBputp\fR. Call the \fBreset_shell_mode\fR to restore the -tty modes before exiting [see \fBcurs_kernel\fR(3X)]. Programs which use -cursor addressing should output \fBenter_ca_mode\fR upon startup and should -output \fBexit_ca_mode\fR before exiting. Programs desiring shell escapes -should call - -\fBreset_shell_mode\fR and output \fBexit_ca_mode\fR before the shell -is called and should output \fBenter_ca_mode\fR and call -\fBreset_prog_mode\fR after returning from the shell. - -The \fBsetupterm\fR routine reads in the \fBterminfo\fR database, -initializing the \fBterminfo\fR structures, but does not set up the -output virtualization structures used by \fBcurses\fR. The terminal -type is the character string \fIterm\fR; if \fIterm\fR is null, the -environment variable \fBTERM\fR is used. -All output is to file descriptor \fBfildes\fR which is initialized for output. -If \fIerrret\fR is not null, -then \fBsetupterm\fR returns \fBOK\fR or -\fBERR\fR and stores a status value in the integer pointed to by -\fIerrret\fR. -A return value of \fBOK\fR combined with status of \fB1\fR in \fIerrret\fR +These low-level functions must be called by programs that deal directly +with the +.I \%term\%info +database to handle certain terminal capabilities, +such as programming function keys. +For all other functionality, +.I curses +functions are more suitable and their use is recommended. +.PP +None of these functions use +(or are aware of) +multibyte character strings such as UTF-8. +.bP +Capability names and codes use the POSIX portable character set. +.bP +Capability string values have no associated encoding; +they are strings of 8-bit characters. +.SS Initialization +Initially, +\fB\%setupterm\fP should be called. +The high-level +.I curses +functions \fB\%initscr\fP and \fB\%newterm\fP call \fB\%setupterm\fP to +initialize the low-level set of terminal-dependent variables listed in +\fB\%term_variables\fP(3X). +.PP +Applications can use the terminal capabilities either directly +(via header definitions), +or by special functions. +The header files +.I \%curses.h +and +.I \%term.h +should be included +(in that order) +to get the definitions for these strings, +numbers, +and flags. +.PP +The +.I \%term\%info +variables +.B \%lines +and +.B \%columns +are initialized by \fB\%setupterm\fP as follows. +.bP +If \fB\%use_env(FALSE)\fP has been called, +values for +.B \%lines +and +.B \%columns +specified in +.I \%term\%info +are used. +.bP +Otherwise, +if the environment variables +.I LINES +and +.I \%COLUMNS +exist, +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 for +.B \%lines +and +.B \%columns +specified in the +.I \%term\%info +database are used. +.PP +Parameterized strings should be passed through \fB\%tparm\fP to +instantiate them. +All +.I \%term\%info +strings +(including the output of \fB\%tparm\fP) +should be sent to the terminal device with \fB\%tputs\fP or +\fB\%putp\fP. +Call \fB\%reset_shell_mode\fP to restore the terminal modes before +exiting; +see \fB\%curs_kernel\fP(3X). +.PP +Programs that use +cursor addressing should +.bP +output \fB\%enter_ca_mode\fP upon startup and +.bP +output \fB\%exit_ca_mode\fP before exiting. +.PP +Programs that execute shell subprocesses should +.bP +call \fB\%reset_shell_mode\fP and +output \fB\%exit_ca_mode\fP before the shell +is called and +.bP +output \fB\%enter_ca_mode\fP and +call \fB\%reset_prog_mode\fP after returning from the shell. +.PP +\fB\%setupterm\fP reads in the +.I \%term\%info +database, +initializing the +.I \%term\%info +structures, +but does not set up the output virtualization structures used by +.IR curses . +Its parameters follow. +.RS 3 +.TP 5 +.I term +is the terminal type, +a character string. +If +.I term +is null, +the environment variable +.I TERM +is read. +.TP 5 +.I filedes +is the file descriptor used for getting and setting terminal I/O modes. +.IP +Higher-level applications use \fB\%newterm\fP(3X) to initialize the +terminal, +passing an output +.I stream +rather than a +.IR descriptor . +In +.IR curses , +the two are the same because \fB\%newterm\fP calls \fB\%setupterm\fP, +passing the file descriptor derived from its output stream parameter. +.TP 5 +.I errret +points to an optional location where an error status can be returned to +the caller. +If +.I errret +is not null, +then \fB\%setupterm\fP returns +.B OK +or +.B ERR +and stores a status value in the integer pointed to by +.IR errret . +A return value of +.B OK +combined with status of +.B 1 +in +.I errret is normal. -If \fBERR\fR is returned, examine \fIerrret\fR: +.IP +If +.B ERR +is returned, +examine +.I errret: .RS .TP 5 .B 1 -means that the terminal is hardcopy, cannot be used for curses applications. +means that the terminal is hardcopy, +and cannot be used for +.I curses +applications. +.IP +\fB\%setupterm\fP determines if the entry is a hardcopy type by +checking the +.B \%hardcopy +.RB ( hc ) +capability. .TP 5 .B 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. +having too little information for +.I curses +applications to run. +.IP +\fB\%setupterm\fP determines if the entry is a generic type by +checking the +.B \%generic_type +.RB ( gn ) +capability. .TP 5 -.B -1 -means that the \fBterminfo\fR database could not be found. +.B \-1 +means that the +.I \%term\%info +database could not be found. +.RE +.IP +If +.I errret +is null, +\fB\%setupterm\fP reports an error message upon finding an error and +exits. +Thus, +the simplest call is: +.RS +.IP +.EX +setupterm((char *)0, 1, (int *)0); +.EE .RE +.IP +which uses all the defaults and sends the output to +.BR stdout . +.RE +.\" ******************************************************************** +.SS "The Terminal State" +\fB\%setupterm\fP stores its information about the terminal in a +.I \%TERMINAL +structure pointed to by the global variable \fB\%cur_term\fP. +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. +.PP +If \fB\%setupterm\fP is 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, +\fB\%setupterm\fP allocates new storage for each set of terminal +capabilities. .PP -If \fIerrret\fR is -null, \fBsetupterm\fR prints an error message upon finding an error -and exits. Thus, the simplest call is: - - \fBsetupterm((char *)0, 1, (int *)0);\fR, - -which uses all the defaults and sends the output to \fBstdout\fR. - -The \fBsetterm\fR routine is being replaced by \fBsetupterm\fR. The call: - - \fBsetupterm(\fR\fIterm\fR\fB, 1, (int *)0)\fR - -provides the same functionality as \fBsetterm(\fR\fIterm\fR\fB)\fR. -The \fBsetterm\fR routine is included here for BSD compatibility, and -is not recommended for new programs. - -The \fBset_curterm\fR routine sets the variable \fBcur_term\fR to -\fInterm\fR, and makes all of the \fBterminfo\fR boolean, numeric, and -string variables use the values from \fInterm\fR. It returns the old value -of \fBcur_term\fR. - -The \fBdel_curterm\fR routine frees the space pointed to by -\fIoterm\fR and makes it available for further use. If \fIoterm\fR is -the same as \fBcur_term\fR, references to any of the \fBterminfo\fR -boolean, numeric, and string variables thereafter may refer to invalid -memory locations until another \fBsetupterm\fR has been called. - -The \fBrestartterm\fR routine is similar to \fBsetupterm\fR and \fBinitscr\fR, -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 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 \fBtparm\fR routine instantiates the string \fIstr\fR with -parameters \fIpi\fR. A pointer is returned to the result of \fIstr\fR +\fB\%set_curterm\fP sets \fB\%cur_term\fP to +.IR \%nterm , +and makes all of the +.I \%term\%info +Boolean, +numeric, +and string variables use the values from +.IR \%nterm . +It returns the old value of \fB\%cur_term\fP. +.PP +\fB\%del_curterm\fP frees the space pointed to by +.I \%oterm +and makes it available for further use. +If +.I \%oterm +is +the same as \fB\%cur_term\fP, +references to any of the +.I \%term\%info +Boolean, +numeric, +and string variables thereafter may refer to invalid memory locations +until another \fB\%setupterm\fP has been called. +.PP +\fB\%restartterm\fP is similar to \fB\%setupterm\fP and \fB\%initscr\fP, +except that it is called after restoring memory to a previous state +(for example, +when reloading a game saved as a core image dump). +\fB\%restartterm\fP 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, +\fB\%restartterm\fP saves various terminal state bits, +calls \fB\%setupterm\fP, +and then restores the bits. +.\" ******************************************************************** +.SS "Formatting Output" +\fB\%tparm\fP instantiates the string +.I str +with parameters +.IR pi . +A pointer is returned to the result of +.I str with the parameters applied. - -The \fBtputs\fR routine applies padding information to the string -\fIstr\fR and outputs it. The \fIstr\fR must be a terminfo string -variable or the return value from \fBtparm\fR, \fBtgetstr\fR, or -\fBtgoto\fR. \fIaffcnt\fR is the number of lines affected, or 1 if -not applicable. \fIputc\fR is a \fBputchar\fR-like routine to which -the characters are passed, one at a time. - -The \fBputp\fR routine calls \fBtputs(\fR\fIstr\fR\fB, 1, putchar)\fR. -Note that the output of \fBputp\fR always goes to \fBstdout\fR, not to -the \fIfildes\fR specified in \fBsetupterm\fR. - -The \fBvidputs\fR routine displays the string on the terminal in the -video attribute mode \fIattrs\fR, which is any combination of the -attributes listed in \fBcurses\fR(3X). The characters are passed to -the \fBputchar\fR-like routine \fIputc\fR. - -The \fBvidattr\fR routine is like the \fBvidputs\fR routine, except -that it outputs through \fBputchar\fR. - -The \fBmvcur\fR routine provides low-level cursor motion. It takes -effect immediately (rather than at the next refresh). - -The \fBtigetflag\fR, \fBtigetnum\fR and \fBtigetstr\fR routines return -the value of the capability corresponding to the \fBterminfo\fR -\fIcapname\fR passed to them, such as \fBxenl\fR. - -The \fBtigetflag\fR routine returns the value \fB-1\fR if -\fIcapname\fR is not a boolean capability, -or \fB0\fR if it is canceled or absent from the terminal description. - -The \fBtigetnum\fR routine returns the value \fB-2\fR if -\fIcapname\fR is not a numeric capability, -or \fB-1\fR if it is canceled or absent from the terminal description. - -The \fBtigetstr\fR routine returns the value \fB(char *)-1\fR -if \fIcapname\fR is not a string capability, -or \fB0\fR if it is canceled or absent from the terminal description. - -The \fIcapname\fR for each capability is given in the table column entitled -\fIcapname\fR code in the capabilities section of \fBterminfo\fR(\*n). - -\fBchar *boolnames\fR, \fB*boolcodes\fR, \fB*boolfnames\fR - -\fBchar *numnames\fR, \fB*numcodes\fR, \fB*numfnames\fR - -\fBchar *strnames\fR, \fB*strcodes\fR, \fB*strfnames\fR - -These null-terminated arrays contain the \fIcapnames\fR, the -\fBtermcap\fR codes, and the full C names, for each of the -\fBterminfo\fR variables. +Application developers should keep in mind these quirks of the +interface: +.bP +Although \fB\%tparm\fP's actual parameters may be integers or strings, +the prototype expects +.I long +(integer) values. +.bP +Aside from the +.B \%set_attributes\fP +.RB ( sgr ) +capability, +most terminal capabilities require no more than one or two parameters. +.bP +Padding information is ignored by \fB\%tparm\fP; +it is interpreted by \fB\%tputs\fP. +.bP +The capability string is null-terminated. +Use \*(``\e200\*('' where an ASCII NUL is needed in the output. +.PP +\fB\%tiparm\fP is a newer form of \fB\%tparm\fP which uses +.I \%stdarg.h +rather than a fixed-parameter list. +Its numeric parameters are +.IR int s +rather than +.IR long "s." +.PP +Both \fB\%tparm\fP and \fB\%tiparm\fP assume that the application passes +parameters consistent with the terminal description. +Two extensions are provided as alternatives to deal with untrusted data. +.bP +\fB\%tiparm_s\fP is an extension which is a safer formatting function +than \fB\%tparm\fR or \fB\%tiparm\fR, +because it allows the developer to tell the +.I curses +library how many parameters to expect in the parameter list, +and which may be string parameters. +.IP +The \fImask\fP parameter has one bit set for each of the parameters +(up to 9) +passed as +.I char +pointers rather than numbers. +.bP +The extension \fB\%tiscan_s\fP allows the application to inspect a +formatting capability to see what the +.I curses +library would assume. +.\" ******************************************************************** +.SS "Output Functions" +String capabilities can contain padding information, +a time delay +(accommodating performance limitations of hardware terminals) +expressed as \fB$<\fIn\fB>\fR, +where \fIn\fP is a nonnegative integral count of milliseconds. +If \fIn\fP exceeds 30,000 +(thirty seconds), +it is capped at that value. +.PP +\fB\%tputs\fP interprets time-delay information in the string +.I str +and outputs it, +executing the delays: +.bP +The +.I str +parameter must be a +.I \%term\%info +string variable or the return value of +.B \%tparm +or +.BR \%tiparm "." +.bP +.I affcnt +is the number of lines affected, +or +.B 1 +if not applicable. +.bP +.I putc +is a +.IR \%putchar -like +function to which the characters are passed, +one at a time. +.IP +If \fB\%tputs\fP processes a time-delay, +it uses the \fB\%delay_output\fP(3X) function, +routing any resulting padding characters through this function. +.PP +\fB\%putp\fR calls +.RB \%\*(`` tputs(\c +.IB str ", 1, putchar)\c" +\*(''. +The output of \fB\%putp\fP always goes to +.BR stdout , +rather than the +.I \%file\%des +specified in \fB\%setupterm\fP. +.PP +\fB\%vidputs\fP displays the string on the terminal in the video +attribute mode +.IR attrs , +which is any combination of the attributes listed in \fB\%curses\fP(3X). +The characters are passed to the +.IR \%putchar -like +function +.IR putc . +.PP +\fB\%vidattr\fP is like \fB\%vidputs\fP, +except that it outputs through \fI\%putchar\fP(3). +.PP +.B \%vid_attr +and +.B \%vid_puts +correspond to +.B \%vidattr +and +.BR \%vidputs , +respectively. +They use multiple parameters to represent the character attributes and +color; +namely, +.bP +.IR \%attrs , +of type +.IR \%attr_t , +for the attributes and +.bP +.IR pair , +of type +.IR short , +for the color pair number. +.PP +Use the attribute constants prefixed with +.RB \*(`` WA_ \*('' +with +.B \%vid_attr +and +.BR \%vid_puts . +.PP +X/Open Curses reserves the +.I opts +argument for future use, +saying that applications must provide a null pointer for that argument; +but see section \*(``EXTENSIONS\*('' below. +.PP +While \fB\%putp\fP is a low-level function that does not use high-level +.I curses +state, +.I \%ncurses +declares it in +.I \%curses.h +because System\ V did this +(see section \*(``HISTORY\*('' below). +.\" ******************************************************************** +.SS "Terminal Capability Functions" +\fB\%tigetflag\fP, +\fB\%tigetnum\fP, +and \fB\%tigetstr\fP return the value of the capability corresponding to +the +.I \%term\%info +.IR cap-code , +such as +.BR xenl , +passed to them. +The +.I cap-code +for each capability is given in the table column entitled +.I cap-code +code in the capabilities section of \fB\%terminfo\fP(5). +.PP +These functions return special values to denote errors. +.PP +\fB\%tigetflag\fP returns +.TP +.B \-1 +if +.I cap-code +is not a Boolean capability, +or +.TP +.B 0 +if it is canceled or absent from the terminal description. +.PP +\fB\%tigetnum\fP returns +.TP +.B \-2 +if +.I cap-code +is not a numeric capability, +or +.TP +.B \-1 +if it is canceled or absent from the terminal description. +.PP +\fB\%tigetstr\fP returns +.TP +.B "(char *)\-1" +if +.I cap-code +is not a string capability, +or +.TP +.B 0 +if it is canceled or absent from the terminal description. +.\" ******************************************************************** +.SS "Terminal Capability Names" +These null-terminated arrays contain +.bP +the short \fI\%term\%info\fP names (\*(``codes\*(''), +.bP +the \fItermcap\fP names (\*(``names\*(''), +and +.bP +the long \fI\%term\%info\fP names (\*(``fnames\*('') +.PP +for each of the predefined +.I \%term\%info +variables: +.PP +.RS +.nf +\fBconst char *boolnames[]\fP, \fB*boolcodes[]\fP, \fB*boolfnames[]\fP +\fBconst char *numnames[]\fP, \fB*numcodes[]\fP, \fB*numfnames[]\fP +\fBconst char *strnames[]\fP, \fB*strcodes[]\fP, \fB*strfnames[]\fP +.fi +.RE +.\" ******************************************************************** +.SS "Releasing Memory" +Each successful call to \fB\%setupterm\fP allocates memory to hold the +terminal description. +As a side effect, +it sets \fB\%cur_term\fP to point to this memory. +If an application calls +.IP +.EX +del_curterm(cur_term); +.EE +.PP +the memory will be freed. +.PP +The formatting functions \fB\%tparm\fP and \fB\%tiparm\fP extend the +storage allocated by \fB\%setupterm\fP as follows. +.bP +They add the \*(``static\*('' +.I \%term\%info +variables [a-z]. +Before +.I \%ncurses +6.3, +those were shared by all screens. +With +.I \%ncurses +6.3, +those are allocated per screen. +See \fB\%terminfo\fP(5). +.bP +To improve performance, +.I \%ncurses +6.3 caches the result of analyzing +.I \%term\%info +strings for their parameter types. +That is stored as a binary tree referenced from the +.I \%TERMINAL +structure. +.PP +The higher-level \fB\%initscr\fP and \fB\%newterm\fP functions use +\fB\%setupterm\fP. +Normally they do not free this memory, +but it is possible to do that using the \fB\%delscreen\fP(3X) function. +.\" ******************************************************************** .SH RETURN VALUE -Routines that return an integer return \fBERR\fR upon failure and \fBOK\fR -(SVr4 only specifies "an integer value other than \fBERR\fR") upon successful -completion, unless otherwise noted in the preceding routine descriptions. - -Routines that return pointers always return \fBNULL\fR on error. +X/Open Curses defines no failure conditions. +In +.IR \%ncurses , +.TP 5 +.B del_curtem +fails if its terminal parameter is null. +.TP 5 +.B putp +calls \fB\%tputs\fP, +returning the same error codes. +.TP 5 +.B restartterm +fails if the associated call to \fB\%setupterm\fP returns +.BR ERR "." +.TP 5 +.B setupterm +fails if it cannot allocate enough memory, +or create the initial windows +.RB ( \%stdscr , +.BR \%curscr , +and +.BR \%newscr ) +Other error conditions are documented above. +.TP 5 +.B tparm +returns a null pointer if the capability would require unexpected +parameters; +that is, +too many, +too few, +or incorrect types +(strings where integers are expected, +or vice versa). +.TP 5 +.B tputs +fails if the string parameter is null. +It does not detect I/O errors: +X/Open Curses states that \fB\%tputs\fP ignores the return value +of the output function \fI\%putc\fP. +.\" ******************************************************************** .SH NOTES -The \fBsetupterm\fR routine should be used in place of \fBsetterm\fR. -It may be useful when you want to test for terminal capabilities without -committing to the allocation of storage involved in \fBinitscr\fR. - -Note that \fBvidattr\fR and \fBvidputs\fR may be macros. +The +.B \%vid_attr +function in +.I \%ncurses +is a special case. +It was originally implemented based on a draft of X/Open Curses, +as a macro, +before other parts of the +.I \%ncurses +wide-character API were developed, +and unlike the other wide-character functions, +is also provided in the non-wide-character configuration. +.\" ******************************************************************** +.SH EXTENSIONS +The functions marked as extensions were designed for +.IR \%ncurses , +and are not found in SVr4 +.IR curses , +4.4BSD +.IR curses , +or any other previous +.I curses +implementation. +.PP +.I \%ncurses +allows +.I opts +to be a pointer to +.IR int , +which overrides the +.I pair +.RI ( short ) +argument. +.\" ******************************************************************** .SH PORTABILITY -The function \fBsetterm\fR 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, \fBset_curterm\fR has an \fBint\fR return type and -returns \fBOK\fR or \fBERR\fR. We have chosen to implement the XSI Curses -semantics. - -In System V Release 4, the third argument of \fBtputs\fR has the type -\fBint (*putc)(char)\fR. - -The XSI Curses standard prototypes \fBtparm\fR with a fixed number of parameters, +\fB\%setterm\fP is not described by X/Open and must be considered +non-portable. +All other functions are as described by X/Open. +.SS "Compatibility Macros" +This implementation provides a few macros for compatibility with systems +before SVr4 +(see section \*(``HISTORY\*('' below). +They include +\fB\%Bcrmode\fP, +\fB\%Bfixterm\fP, +\fB\%Bgettmode\fP, +\fB\%Bnocrmode\fP, +\fB\%Bresetterm\fP, +\fB\%Bsaveterm\fP, +and +\fB\%Bsetterm\fP. +.PP +In SVr4, +these are found in +.IR \%curses.h , +but except for \fB\%setterm\fP, +are likewise macros. +The one function, +\fB\%setterm\fP, +is mentioned in the manual page. +It further notes that \fB\%setterm\fP was replaced by \fB\%setupterm\fP, +stating that the call +.RS +.EX +setupterm(\fIterm\fP, 1, (int *)0) +.EE +.RE +provides the same functionality as \fB\%setterm(\fIterm\fB)\fR, +discouraging the latter for new programs. +.I \%ncurses +implements each of these symbols as macros for BSD +.I curses +compatibility. +.SS "Legacy Data" +\fB\%setupterm\fP copies the terminal name to the array \fB\%ttytype\fP. +This is not part of X/Open Curses, +but is assumed by some applications. +.PP +Other implementions may not declare the capability name arrays. +Some provide them without declaring them. +X/Open Curses does not specify them. +.PP +Extended terminal capability names, +as defined by +.RB \%\*(`` "@TIC@ \-x" \*('', +are not stored in the arrays described here. +.SS "Output Buffering" +Older versions of \fI\%ncurses\fP assumed that the file descriptor +passed to \fB\%setupterm\fP from \fB\%initscr\fP or \fB\%newterm\fP uses +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 +.IR curses ), +it was problematic because +.I \%ncurses +did not allow a reliable way to clean up on receiving +.BR SIGTSTP . +.PP +The current version (ncurses6) +uses output buffers managed directly by +.IR \%ncurses . +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 in +.I \%ncurses +employ alternate versions of these functions using the more reliable +buffering scheme. +.SS "Function Prototypes" +The X/Open Curses prototypes are based on the SVr4 +.I curses +header declarations, +which were defined at the same time the C language was first +standardized in the late 1980s. +.bP +X/Open Curses uses +.I \%const +less effectively than a later design might, +sometimes applying it needlessly to values that are already constant, +and in most cases overlooking parameters that normally would use +.IR \%const . +Passing +.IR \%const -qualified +parameters to functions that do not declare them +.I \%const +may prevent the program from compiling. +On the other hand, +\*(``writable strings\*('' are an obsolescent feature. +.IP +As an extension, +this implementation can be configured to change the function prototypes +to use the +.I \%const +keyword. +The +.I \%ncurses +ABI 6 enables this feature by default. +.bP +X/Open Curses prototypes \fB\%tparm\fP with a fixed number of +parameters, rather than a variable argument list. - -XSI notes that after calling \fBmvcur\fR, 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 System V Release 4 curses implement \fBmvcur\fR using -the SCREEN data allocated in either \fBinitscr\fR or \fBnewterm\fR. -So though it is documented as a terminfo function, -\fBmvcur\fR is really a curses function which is not well specified. +.IP +This implementation uses a variable argument list, +but can be configured to use the fixed-parameter list. +Portable applications should provide nine parameters after the format; +zeroes are fine for this purpose. +.IP +In response to review comments by Thomas E. Dickey, +X/Open Curses Issue 7 proposed the \fB\%tiparm\fP function in mid-2009. +.IP +While \fB\%tiparm\fP is always provided in \fI\%ncurses\fP, +the older form is only available as a build-time configuration option. +If not specially configured, +\fB\%tparm\fP is the same as \fB\%tiparm\fP. +.PP +Both forms of \fB\%tparm\fP have drawbacks: +.bP +Most of the calls to \fB\%tparm\fP use only one or two parameters. +Passing nine on each call is awkward. +.IP +Using +.I long +for the numeric parameter type is a workaround to make the parameter use +the same amount of stack as a pointer. +That approach dates back to the mid-1980s, +before C was standardized. +Since then, +there is a standard +(and pointers are not required to fit in a +.IR long ). +.bP +Providing the right number of parameters for a variadic function +such as \fB\%tiparm\fP can be a problem, +in particular for string parameters. +However, +only a few +.I \%term\%info +capabilities use string parameters +(for instance, +the ones used for programmable function keys). +.IP +The \fI\%ncurses\fP library checks usage of these capabilities, +and returns +.B ERR +if the capability mishandles string parameters. +But it cannot check if a calling program provides strings in the right +places for the \fB\%tparm\fP calls. +.IP +The \fB\%@TPUT@\fR(1) program checks its use of these capabilities with +a table, +so that it calls \fB\%tparm\fP correctly. +.SS "Special \fITERM\fP treatment" +If configured to use the terminal driver, +.\" XXX: as opposed to the Unix terminal driver, termio(s)? +as with the MinGW port, +.bP +\fB\%setupterm\fP interprets a missing/empty \fITERM\fP variable as the +special value \*(``unknown\*(''. +.IP +SVr4 +.I curses +uses the special value \*(``dumb\*(''. +.IP +The difference between the two is that the former uses the +.B \%generic_type +.RB ( gn ) +.I \%term\%info +capability, +while the latter does not. +A generic terminal is unsuitable for full-screen applications. +.bP +\fB\%setupterm\fP allows explicit use of the +the windows console driver by checking if \fB$TERM\fP is set to +\*(``#win32con\*('' or an abbreviation of that string. +.SS "Other Portability Issues" +In SVr4, +\fB\%set_curterm\fP returns an +.IR int , +.B OK +or +.BR ERR . +We have chosen to implement the X/Open Curses semantics. +.PP +In SVr4, +the third argument of \fB\%tputs\fP has the type +.RB \*(`` "int (*putc)(char)" \*(''. +.PP +At least one implementation of X/Open Curses (Solaris) returns a value +other than +.B OK +or +.B ERR +from \fB\%tputs\fP. +It instead returns the length of the string, +and does no error checking. +.\" ******************************************************************** +.SH HISTORY +SVr2 (1984) introduced the +.I \%term\%info +feature. +Its programming manual mentioned the following low-level functions. +.PP +.TS +lB lB +lB lx. +Function Description +_ +fixterm restore terminal to \*(``in \fIcurses\fP\*('' state +gettmode establish current terminal modes +mvcur low level cursor motion +putp use \fBtputs\fP to send characters via \fIputchar\fP +resetterm set terminal modes to \*(``out of \fIcurses\fP\*(''\ + state +resetty reset terminal flags to stored value +saveterm save current modes as \*(``in \fIcurses\fP\*('' state +savetty store current terminal flags +setterm establish terminal with given type +setupterm establish terminal with given type +tparm interpolate parameters into string capability +tputs apply padding information to a string +vidattr like \fBvidputs\fP, but output through \fIputchar\fP +vidputs T{ +write string to terminal, applying specified attributes +T} +.TE +.PP +The programming manual also mentioned +functions provided for +.I termcap +compatibility +(commenting that they \*(``may go away at a later date\*(''). +.PP +.TS +lB lB +lB lx. +Function Description +_ +tgetent look up \fItermcap\fP entry for given \fIname\fP +tgetflag get Boolean entry for given \fIid\fP +tgetnum get numeric entry for given \fIid\fP +tgetstr get string entry for given \fIid\fP +tgoto apply parameters to given capability +tputs T{ +write characters via a function parameter, applying padding +T} +.TE +.PP +Early +.I \%term\%info +programs obtained capability values from the +.I \%TERMINAL +structure initialized by \fB\%setupterm\fP. +.PP +SVr3 (1987) extended +.I \%term\%info +by adding functions to retrieve capability values +(like the +.I termcap +interface), +and reusing \fB\%tgoto\fP and \fB\%tputs\fP. +.PP +.TS +lB lB +lB lx. +Function Description +_ +tigetflag get Boolean entry for given \fIid\fP +tigetnum get numeric entry for given \fIid\fP +tigetstr get string entry for given \fIid\fP +.TE +.PP +SVr3 also replaced several of the SVr2 +.I \%term\%info +functions that had no counterpart in the +.I termcap +interface, +documenting them as obsolete. +.PP +.TS +lB lB +l lx. +Function Replaced by +_ +crmode cbreak +fixterm reset_prog_mode +gettmode \fIn/a\fP +nocrmode nocbreak +resetterm reset_shell_mode +saveterm def_prog_mode +setterm setupterm +.TE +.PP +SVr3 kept the \fB\%mvcur\fP, +\fB\%vidattr\fP, +and \fB\%vidputs\fP functions, +along with \fB\%putp\fP, +\fB\%tparm\fP, +and \fB\%tputs\fP. +The latter were needed to support padding, +and to handle capabilities accessed by functions such as \fB\%vidattr\fP +(which used more than the two parameters supported by \fB\%tgoto\fP). +.PP +SVr3 introduced the functions for switching between terminal +descriptions; +for example, +\fB\%set_curterm\fP. +Some changes reflected incremental improvements to the SVr2 library. +.bP +The +.I \%TERMINAL +type definition was introduced in SVr3.01, +for the +.I term +structure provided in SVr2. +.bP +Various global variables such as \fB\%boolnames\fP were mentioned +in the programming manual at this point, +though the variables had been provided in SVr2. +.PP +SVr4 (1989) added the \fB\%vid_attr\fP and \fB\%vid_puts\fP functions. +.PP +Other low-level functions are declared in the +.I curses +header files of Unix systems, +but none are documented. +Those noted as \*(``obsolete\*('' by SVr3 remained in use by System\ V's +\fIvi\fP(1) editor. .SH SEE ALSO -\fBcurses\fR(3X), \fBcurs_initscr\fR(3X), \fBcurs_kernel\fR(3X), \fBcurs_termcap\fR(3X), -\fBputc\fR(3S), \fBterminfo\fR(\*n) -.\"# -.\"# The following sets edit modes for GNU EMACS -.\"# Local Variables: -.\"# mode:nroff -.\"# fill-column:79 -.\"# End: +\fB\%curses\fP(3X), +\fB\%curs_initscr\fP(3X), +\fB\%curs_kernel\fP(3X), +\fB\%curs_memleaks\fP(3X), +\fB\%curs_termcap\fP(3X), +\fB\%curs_variables\fP(3X), +\fB\%putc\fP(3), +\fB\%term_variables\fP(3X), +\fB\%terminfo\fP(5)