X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=man%2Fcurs_terminfo.3x;h=00ae1349db0ad0a8cec0b1c1064a852e20178675;hb=HEAD;hp=22ed0777b15d9e08df27bb61d501968a24cda187;hpb=a47b9e53836434777854387fa6f09f2137ec2111;p=ncurses.git diff --git a/man/curs_terminfo.3x b/man/curs_terminfo.3x index 22ed0777..2c373f6f 100644 --- a/man/curs_terminfo.3x +++ b/man/curs_terminfo.3x @@ -1,6 +1,6 @@ '\" t .\"*************************************************************************** -.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" 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 * @@ -28,755 +28,1059 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_terminfo.3x,v 1.95 2023/08/19 20:37:54 tom Exp $ -.TH curs_terminfo 3X 2023-08-19 "ncurses 6.4" "Library calls" -.ie \n(.g .ds `` \(lq -.el .ds `` `` -.ie \n(.g .ds '' \(rq -.el .ds '' '' +.\" $Id: curs_terminfo.3x,v 1.142 2024/06/08 23:05:52 tom Exp $ +.TH curs_terminfo 3X 2024-06-08 "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 .. -.ds n 5 -.na -.hy 0 +. .SH NAME -\fBdel_curterm\fP, -\fBmvcur\fP, -\fBputp\fP, -\fBrestartterm\fP, -\fBset_curterm\fP, -\fBsetupterm\fP, -\fBtigetflag\fP, -\fBtigetnum\fP, -\fBtigetstr\fP, -\fBtiparm\fP, -\fBtiparm_s\fP, -\fBtiscan_s\fP, -\fBtparm\fP, -\fBtputs\fP, -\fBvid_attr\fP, -\fBvid_puts\fP, -\fBvidattr\fP, -\fBvidputs\fP \- \fBcurses\fP interfaces to terminfo database -.ad -.hy +\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 .nf -\fB#include \fP -\fB#include \fP -.sp -\fBTERMINAL *cur_term;\fP -.sp -\fBconst char * const boolnames[];\fP -\fBconst char * const boolcodes[];\fP -\fBconst char * const boolfnames[];\fP -\fBconst char * const numnames[];\fP -\fBconst char * const numcodes[];\fP -\fBconst char * const numfnames[];\fP -\fBconst char * const strnames[];\fP -\fBconst char * const strcodes[];\fP -\fBconst char * const strfnames[];\fP -.sp -\fBint setupterm(const char *\fIterm\fB, int \fIfiledes\fB, int *\fIerrret\fB);\fR -.br -\fBTERMINAL *set_curterm(TERMINAL *\fInterm\fB);\fR -.br -\fBint del_curterm(TERMINAL *\fIoterm\fB);\fR -.br -\fBint restartterm(const char *\fIterm\fB, int \fIfiledes\fB, int *\fIerrret\fB);\fR -.sp -\fBchar *tparm(const char *\fIstr\fB, ...);\fR -.br - \fIor\fP -.br -\fBchar *tparm(const char *\fIstr\fB, long \fIp1 ... \fBlong \fIp9\fB);\fR -.sp -\fBint tputs(const char *\fIstr\fB, int \fIaffcnt\fB, int (*\fIputc\fB)(int));\fR -.br -\fBint putp(const char *\fIstr\fB);\fR -.sp -\fBint vidputs(chtype \fIattrs\fB, int (*\fIputc\fB)(int));\fR -.br -\fBint vidattr(chtype \fIattrs\fB);\fR -.br -\fBint vid_puts(attr_t \fIattrs\fB, short \fIpair\fB, void *\fIopts\fB, int (*\fIputc\fB)(int));\fR -.br -\fBint vid_attr(attr_t \fIattrs\fB, short \fIpair\fB, void *\fIopts\fB);\fR -.sp -\fBint mvcur(int \fIoldrow\fB, int \fIoldcol\fB, int \fInewrow\fR, int \fInewcol\fB);\fR -.sp -\fBint tigetflag(const char *\fIcapname\fB);\fR -.br -\fBint tigetnum(const char *\fIcapname\fB);\fR -.br -\fBchar *tigetstr(const char *\fIcapname\fB);\fR -.sp -\fBchar *tiparm(const char *\fIstr\fB, ...);\fR -.sp -/* extensions */ -.br -\fBchar *tiparm_s(int \fIexpected\fB, int \fImask\fB, const char *\fIstr\fB, ...);\fR -.br -\fBint tiscan_s(int *\fIexpected\fB, int *\fImask\fB, const char *\fIstr\fB);\fR -.br +\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\fP database to handle certain terminal -capabilities, such as programming function keys. -For all other -functionality, \fBcurses\fP routines are more suitable and their use is -recommended. +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: +None of these functions use +(or are aware of) +multibyte character strings such as UTF-8. .bP -capability names use the POSIX portable character set +Capability names and codes use the POSIX portable character set. .bP -capability string values have no associated encoding; +Capability string values have no associated encoding; they are strings of 8-bit characters. .SS Initialization -Initially, \fBsetupterm\fP should be called. -The high-level curses functions \fBinitscr\fP and -\fBnewterm\fP call \fBsetupterm\fP to initialize the -low-level set of terminal-dependent variables -[listed in \fBterminfo\fP(\*n)]. -.PP -Applications can use the -terminal capabilities either directly (via header definitions), +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 \fBcurses.h\fP and \fBterm.h\fP should be included (in this -order) to get the definitions for these strings, numbers, and flags. +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 \fBterminfo\fP variables -\fBlines\fP and \fBcolumns\fP are initialized by \fBsetupterm\fP as -follows: +The +.I \%term\%info +variables +.B \%lines +and +.B \%columns +are initialized by \fB\%setupterm\fP as follows. .bP -If \fBuse_env(FALSE)\fP has been called, values for -\fBlines\fP and \fBcolumns\fP specified in \fBterminfo\fP are used. +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 \fBLINES\fP and \fBCOLUMNS\fP -exist, their values are used. -If these environment variables do not -exist and the program is running in a window, the current window size +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 \fBlines\fP and \fBcolumns\fP specified in the -\fBterminfo\fP database are used. -.PP -Parameterized strings should be passed through \fBtparm\fP to instantiate them. -All \fBterminfo\fP strings -(including the output of \fBtparm\fP) -should be printed -with \fBtputs\fP or \fBputp\fP. -Call \fBreset_shell_mode\fP to restore the -tty modes before exiting [see \fBcurs_kernel\fP(3X)]. -.PP -Programs which use +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 \fBenter_ca_mode\fP upon startup and +output \fB\%enter_ca_mode\fP upon startup and .bP -output \fBexit_ca_mode\fP before exiting. +output \fB\%exit_ca_mode\fP before exiting. .PP -Programs which execute shell subprocesses should +Programs that execute shell subprocesses should .bP -call \fBreset_shell_mode\fP and -output \fBexit_ca_mode\fP before the shell +call \fB\%reset_shell_mode\fP and +output \fB\%exit_ca_mode\fP before the shell is called and .bP -output \fBenter_ca_mode\fP and -call \fBreset_prog_mode\fP after returning from the shell. +output \fB\%enter_ca_mode\fP and +call \fB\%reset_prog_mode\fP after returning from the shell. .PP -The \fBsetupterm\fP routine reads in the \fBterminfo\fP database, -initializing the \fBterminfo\fP structures, but does not set up the -output virtualization structures used by \fBcurses\fP. -These are its parameters: +\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 -\fIterm\fP -is the terminal type, a character string. -If \fIterm\fP is null, the environment variable \fBTERM\fP is used. +.I term +is the terminal type, +a character string. +If +.I term +is null, +the environment variable +.I TERM +is read. .TP 5 -\fIfiledes\fP +.I filedes is the file descriptor used for getting and setting terminal I/O modes. .IP -Higher-level applications use \fBnewterm\fP(3X) for initializing the terminal, -passing an output \fIstream\fP rather than a \fIdescriptor\fP. -In curses, the two are the same because \fBnewterm\fP calls \fBsetupterm\fP, +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 -\fIerrret\fP +.I errret points to an optional location where an error status can be returned to the caller. -If \fIerrret\fP is not null, -then \fBsetupterm\fP returns \fBOK\fP or -\fBERR\fP and stores a status value in the integer pointed to by -\fIerrret\fP. -A return value of \fBOK\fP combined with status of \fB1\fP in \fIerrret\fP +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. .IP -If \fBERR\fP is returned, examine \fIerrret\fP: +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 -\fBsetupterm\fP determines if the entry is a hardcopy type by -checking the \fBhc\fP (\fBhardcopy\fP) capability. +\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 -\fBsetupterm\fP determines if the entry is a generic type by -checking the \fBgn\fP (\fBgeneric_type\fP) capability. +\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\fP database could not be found. +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 -If \fIerrret\fP is -null, \fBsetupterm\fP prints an error message upon finding an error -and exits. -Thus, the simplest call is: -.sp - \fBsetupterm((char *)0, 1, (int *)0);\fP, -.sp -which uses all the defaults and sends the output to \fBstdout\fP. +which uses all the defaults and sends the output to +.BR stdout . .RE -.\" *************************************************************************** -.SS The Terminal State -The \fBsetupterm\fP routine stores its information about the terminal -in a \fBTERMINAL\fP structure pointed to by the global variable \fBcur_term\fP. +.\" ******************************************************************** +.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), +or decides that the terminal is unsuitable +(hardcopy or generic), it discards this information, making it not available to applications. .PP -If \fBsetupterm\fP is called repeatedly for the same terminal type, +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, -\fBsetupterm\fP allocates new storage for each set of terminal capabilities. -.PP -The \fBset_curterm\fP routine sets \fBcur_term\fP to -\fInterm\fP, and makes all of the \fBterminfo\fP boolean, numeric, and -string variables use the values from \fInterm\fP. -It returns the old value of \fBcur_term\fP. -.PP -The \fBdel_curterm\fP routine frees the space pointed to by -\fIoterm\fP and makes it available for further use. -If \fIoterm\fP is -the same as \fBcur_term\fP, references to any of the \fBterminfo\fP -boolean, numeric, and string variables thereafter may refer to invalid -memory locations until another \fBsetupterm\fP has been called. -.PP -The \fBrestartterm\fP routine is similar to \fBsetupterm\fP and \fBinitscr\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). -\fBrestartterm\fP assumes that the windows and the input and output options -are the same as when memory was saved, +\fB\%setupterm\fP allocates new storage for each set of terminal +capabilities. +.PP +\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, \fBrestartterm\fP saves various tty state bits, -calls \fBsetupterm\fP, and then restores the bits. -.\" *************************************************************************** -.SS Formatting Output -The \fBtparm\fP routine instantiates the string \fIstr\fP with -parameters \fIpi\fP. A pointer is returned to the result of \fIstr\fP +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. -Application developers should keep in mind these quirks of the interface: +Application developers should keep in mind these quirks of the +interface: .bP -Although \fBtparm\fP's actual parameters may be integers or strings, -the prototype expects \fBlong\fP (integer) values. +Although \fB\%tparm\fP's actual parameters may be integers or strings, +the prototype expects +.I long +(integer) values. .bP -Aside from the \fBset_attributes\fP (\fBsgr\fP) capability, +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 \fBtparm\fP; -it is interpreted by \fBtputs\fP. +Padding information is ignored by \fB\%tparm\fP; +it is interpreted by \fB\%tputs\fP. .bP The capability string is null-terminated. -Use \*(``\\200\*('' where an ASCII NUL is needed in the output. +Use \*(``\e200\*('' where an ASCII NUL is needed in the output. .PP -\fBtiparm\fP is a newer form of \fBtparm\fP which uses \fI\fP +\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 integers (int) rather than longs. +Its numeric parameters are +.IR int s +rather than +.IR long "s." .PP -Both \fBtparm\fP and \fBtiparm\fP assume that the application passes +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: +Two extensions are provided as alternatives to deal with untrusted data. .bP -\fBtiparm_s\fP is an extension which is a safer formatting function -than \fBtparm\fR or \fBtiparm\fR, -because it allows the developer to tell the curses +\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) which will be passed as char* rather than numbers. -.bP -The extension \fBtiscan_s\fP allows the application -to inspect a formatting capability to see what the curses library would assume. -.\" *************************************************************************** -.SS Output Functions -The \fBtputs\fP routine applies padding information -(i.e., by interpreting marker embedded in the terminfo capability -such as \*(``$<5>\*('' as 5 milliseconds) -to the string -\fIstr\fP and outputs it: -.bP -The \fIstr\fP parameter must be a terminfo string -variable or the return value from -\fBtparm\fP, \fBtiparm\fP, \fBtgetstr\fP, or \fBtgoto\fP. -.IP -The \fBtgetstr\fP and \fBtgoto\fP functions are part of the \fItermcap\fP -interface, -which happens to share this function name with the \fIterminfo\fP interface. +(up to 9) +passed as +.I char +pointers rather than numbers. .bP -\fIaffcnt\fP is the number of lines affected, or 1 if -not applicable. +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 -\fIputc\fP is a \fBputchar\fP-like routine to which -the characters are passed, one at a time. +.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 -The \fBputp\fR routine calls \fBtputs(\fIstr\fB, 1, putchar)\fR. -The output of \fBputp\fP always goes to \fBstdout\fP, rather than -the \fIfiledes\fP specified in \fBsetupterm\fP. +\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 -The \fBvidputs\fP routine displays the string on the terminal in the -video attribute mode \fIattrs\fP, which is any combination of the -attributes listed in \fBcurses\fP(3X). -The characters are passed to -the \fBputchar\fP-like routine \fIputc\fP. +\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 -The \fBvidattr\fP routine is like the \fBvidputs\fP routine, except -that it outputs through \fBputchar\fP. +\fB\%vidattr\fP is like \fB\%vidputs\fP, +except that it outputs through \fI\%putchar\fP(3). .PP -The \fBvid_attr\fP and \fBvid_puts\fP routines correspond -to vidattr and vidputs, respectively. -They use a set of arguments for representing the video attributes plus color, -i.e., +.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 -\fIattrs\fP of type \fBattr_t\fP for the attributes and +.IR \%attrs , +of type +.IR \%attr_t , +for the attributes and .bP -\fIpair\fP of type \fBshort\fP for the color-pair number. +.IR pair , +of type +.IR short , +for the color pair number. .PP -The \fBvid_attr\fP and \fBvid_puts\fP routines -are designed to use the attribute constants with the \fBWA_\fP prefix. +Use the attribute constants prefixed with +.RB \*(`` WA_ \*('' +with +.B \%vid_attr +and +.BR \%vid_puts . .PP -X/Open Curses reserves the \fIopts\fP argument for future use, -saying that applications must provide a null pointer for that argument. -As an extension, -this implementation allows \fIopts\fP to be used as a pointer to \fBint\fP, -which overrides the \fIpair\fP (\fBshort\fP) argument. -.PP -The \fBmvcur\fP routine provides low-level cursor motion. -It takes effect immediately (rather than at the next refresh). -Unlike the other low-level output functions, -which either write to the standard output or pass an output function parameter, -\fBmvcur\fP uses an output file descriptor derived from -the output stream parameter of \fBnewterm\fP(3X). -.PP -While \fBputp\fP and \fBmvcur\fP are low-level functions which -do not use the high-level curses state, -they are declared in \fB\fP because SystemV did this -(see \fIHISTORY\fP). -.\" *************************************************************************** -.SS Terminal Capability Functions -The \fBtigetflag\fP, \fBtigetnum\fP and \fBtigetstr\fP routines return -the value of the capability corresponding to the \fBterminfo\fP -\fIcapname\fP passed to them, such as \fBxenl\fP. -The \fIcapname\fP for each capability is given in the table column entitled -\fIcapname\fP code in the capabilities section of \fBterminfo\fP(\*n). -.PP -These routines return special values to denote errors. -.PP -The \fBtigetflag\fP routine returns +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 -\fB\-1\fP -if \fIcapname\fP is not a boolean capability, +.B \-1 +if +.I cap-code +is not a Boolean capability, or .TP -\fB0\fP +.B 0 if it is canceled or absent from the terminal description. .PP -The \fBtigetnum\fP routine returns +\fB\%tigetnum\fP returns .TP -\fB\-2\fP -if \fIcapname\fP is not a numeric capability, or +.B \-2 +if +.I cap-code +is not a numeric capability, +or .TP -\fB\-1\fP +.B \-1 if it is canceled or absent from the terminal description. .PP -The \fBtigetstr\fP routine returns +\fB\%tigetstr\fP returns .TP -\fB(char *)\-1\fP -if \fIcapname\fP is not a string capability, +.B "(char *)\-1" +if +.I cap-code +is not a string capability, or .TP -\fB0\fP +.B 0 if it is canceled or absent from the terminal description. -.\" *************************************************************************** -.SS Terminal Capability Names +.\" ******************************************************************** +.SS "Terminal Capability Names" These null-terminated arrays contain .bP -the short terminfo names (\*(``codes\*(''), +the short \fI\%term\%info\fP names (\*(``codes\*(''), .bP -the \fBtermcap\fP names (\*(``names\*(''), and +the \fItermcap\fP names (\*(``names\*(''), +and .bP -the long terminfo names (\*(``fnames\*('') +the long \fI\%term\%info\fP names (\*(``fnames\*('') +.PP +for each of the predefined +.I \%term\%info +variables: .PP -for each of the predefined \fBterminfo\fP variables: -.sp .RS +.nf \fBconst char *boolnames[]\fP, \fB*boolcodes[]\fP, \fB*boolfnames[]\fP -.br \fBconst char *numnames[]\fP, \fB*numcodes[]\fP, \fB*numfnames[]\fP -.br \fBconst char *strnames[]\fP, \fB*strcodes[]\fP, \fB*strfnames[]\fP +.fi .RE -.\" *************************************************************************** -.SS Releasing Memory -Each successful call to \fBsetupterm\fP allocates memory to hold the terminal -description. -As a side-effect, it sets \fBcur_term\fP to point to this memory. +.\" ******************************************************************** +.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 -.sp - \fBdel_curterm(cur_term);\fP -.sp +.IP +.EX +del_curterm(cur_term); +.EE +.PP the memory will be freed. .PP -The formatting functions \fBtparm\fP and \fBtiparm\fP extend the storage -allocated by \fBsetupterm\fP: +The formatting functions \fB\%tparm\fP and \fB\%tiparm\fP extend the +storage allocated by \fB\%setupterm\fP as follows. .bP -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. -See \fBterminfo\fP(\*n) for details. +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, ncurses 6.3 caches the result of analyzing terminfo +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 \fBTERMINAL\fP structure. +That is stored as a binary tree referenced from the +.I \%TERMINAL +structure. .PP -The higher-level \fBinitscr\fP and \fBnewterm\fP functions use \fBsetupterm\fP. -Normally they do not free this memory, but it is possible to do that using -the \fBdelscreen\fP(3X) function. -.\" *************************************************************************** +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\fP upon failure and \fBOK\fP -(SVr4 only specifies \*(``an integer value other than \fBERR\fP\*('') -upon successful completion, -unless otherwise noted in the preceding routine descriptions. -.PP -Routines that return pointers always return \fBNULL\fP on error. -.PP -X/Open defines no error conditions. -In this implementation -.RS 3 +X/Open Curses defines no failure conditions. +In +.IR \%ncurses , .TP 5 -\fBdel_curterm\fP -returns an error -if its terminal parameter is null. +.B del_curtem +fails if its terminal parameter is null. .TP 5 -\fBputp\fP -calls \fBtputs\fP, returning the same error-codes. +.B putp +calls \fB\%tputs\fP, +returning the same error codes. .TP 5 -\fBrestartterm\fP -returns an error -if the associated call to \fBsetupterm\fP returns an error. +.B restartterm +fails if the associated call to \fB\%setupterm\fP returns +.BR ERR "." .TP 5 -\fBsetupterm\fP -returns an error -if it cannot allocate enough memory, or -create the initial windows (stdscr, curscr, newscr). +.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 -\fBtparm\fP -returns a null if the capability would require unexpected parameters, -e.g., too many, too few, or incorrect types -(strings where integers are expected, or vice versa). +.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 -\fBtputs\fP -returns an error if the string parameter is null. +.B tputs +fails if the string parameter is null. It does not detect I/O errors: -X/Open states that \fBtputs\fP ignores the return value -of the output function \fIputc\fP. -.RE -.\" *************************************************************************** -.SS Compatibility macros +X/Open Curses states that \fB\%tputs\fP ignores the return value +of the output function \fI\%putc\fP. +.\" ******************************************************************** +.SH NOTES +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 +\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 \fIHISTORY\fP). -Those include -\fBcrmode\fP, -\fBfixterm\fP, -\fBgettmode\fP, -\fBnocrmode\fP, -\fBresetterm\fP, -\fBsaveterm\fP, and -\fBsetterm\fP. -.PP -In SVr4, those are found in \fB\fP, -but except for \fBsetterm\fP, are likewise macros. -The one function, \fBsetterm\fP, is mentioned in the manual page. -The manual page notes that the \fBsetterm\fP routine -was replaced by \fBsetupterm\fP, stating that the call: -.sp - \fBsetupterm(\fIterm\fB, 1, (int *)0)\fR -.sp -provides the same functionality as \fBsetterm(\fIterm\fB)\fR, -and is not recommended for new programs. -This implementation provides each of those symbols -as macros for BSD compatibility, -.\" *************************************************************************** +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. +.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 introduced the terminfo feature. -Its programming manual mentioned these low-level functions: +SVr2 (1984) introduced the +.I \%term\%info +feature. +Its programming manual mentioned the following low-level functions. .PP .TS -l l. -\fBFunction\fP \fBDescription\fP +lB lB +lB lx. +Function Description _ -fixterm restore tty to \*(``in curses\*('' state -gettmode establish current tty modes +fixterm restore terminal to \*(``in \fIcurses\fP\*('' state +gettmode establish current terminal modes mvcur low level cursor motion -putp T{ -utility function that uses \fBtputs\fP to send characters via \fBputchar\fP. -T} -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 +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 instantiate a string expression with parameters +tparm interpolate parameters into string capability tputs apply padding information to a string -vidattr like \fBvidputs\fP, but outputs through \fBputchar\fP +vidattr like \fBvidputs\fP, but output through \fIputchar\fP vidputs T{ -output a string to put terminal in a specified video attribute mode +write string to terminal, applying specified attributes T} .TE .PP The programming manual also mentioned -functions provided for termcap compatibility -(commenting that they \*(``may go away at a later date\*(''): +functions provided for +.I termcap +compatibility +(commenting that they \*(``may go away at a later date\*(''). .PP .TS -l l -_ _ -l l. -\fBFunction\fP \fBDescription\fP -tgetent look up termcap entry for given \fIname\fP -tgetflag get boolean entry for given \fIid\fP +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{ -apply padding to capability, calling a function to put characters +write characters via a function parameter, applying padding T} .TE .PP -Early terminfo programs obtained capability values from the -\fBTERMINAL\fP structure initialized by \fBsetupterm\fP. +Early +.I \%term\%info +programs obtained capability values from the +.I \%TERMINAL +structure initialized by \fB\%setupterm\fP. .PP -SVr3 extended terminfo by adding functions to retrieve capability values -(like the termcap interface), -and reusing tgoto and tputs: +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 +.ne 4v .TS -l l -_ _ -l l. -\fBFunction\fP \fBDescription\fP -tigetflag get boolean entry for given \fIid\fP +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 terminfo functions -which had no counterpart in the termcap interface, -documenting them as obsolete: +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 -l l -_ _ -l l. -\fBFunction\fP \fBReplaced by\fP +lB lB +l lx. +Function Replaced by +_ crmode cbreak fixterm reset_prog_mode -gettmode N/A +gettmode \fIn/a\fP nocrmode nocbreak resetterm reset_shell_mode saveterm def_prog_mode setterm setupterm .TE .PP -SVr3 kept the \fBmvcur\fP, \fBvidattr\fP and \fBvidputs\fP functions, -along with \fBputp\fP, \fBtparm\fP and \fBtputs\fP. +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 handling functions such as \fBvidattr\fP -(which used more than the two parameters supported by \fBtgoto\fP). +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, e.g., \fBset_curterm\fP. -Some of that was incremental improvements to the SVr2 library: +descriptions; +for example, +\fB\%set_curterm\fP. +Some changes reflected incremental improvements to the SVr2 library. .bP -The \fBTERMINAL\fP type definition was introduced in SVr3.01, -for the \fBterm\fP structure provided in SVr2. +The +.I \%TERMINAL +type definition was introduced in SVr3.01, +for the +.I term +structure provided in SVr2. .bP -The various global variables such as \fBboolnames\fP were mentioned +Various global variables such as \fB\%boolnames\fP were mentioned in the programming manual at this point, -though the variables were provided in SVr2. -.PP -SVr4 added the \fBvid_attr\fP and \fBvid_puts\fP functions. -.PP -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 Unix \fBvi\fP(1) editor. -.SH PORTABILITY -.SS Extensions -The functions marked as extensions were designed for \fBncurses\fP(3X), -and are not found in SVr4 curses, 4.4BSD curses, -or any other previous version of curses. -.SS Legacy functions -X/Open notes that \fBvidattr\fP and \fBvidputs\fP may be macros. -.PP -The function \fBsetterm\fP is not described by X/Open and must -be considered non-portable. -All other functions are as described by X/Open. -.SS Legacy data -\fBsetupterm\fP copies the terminal name to the array \fBttytype\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 does not specify them. +though the variables had been provided in SVr2. .PP -Extended terminal capability names, e.g., as defined by \fB@TIC@\ \-x\fP, -are not stored in the arrays described here. -.SS Output buffering -Older versions of \fBncurses\fP assumed that the file descriptor passed to -\fBsetupterm\fP from \fBinitscr\fP or \fBnewterm\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 curses), -it was problematic because \fBncurses\fP -did not allow a reliable way to cleanup on receiving SIGTSTP. +SVr4 (1989) added the \fB\%vid_attr\fP and \fB\%vid_puts\fP functions. .PP -The current version (ncurses6) -uses output buffers managed directly by \fBncurses\fP. -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 \fBncurses\fP use -alternate versions of these functions -using the more reliable buffering scheme. -.SS 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. -.bP -X/Open Curses uses \fBconst\fP less effectively than a later design might, -in some cases applying it needlessly to values are already constant, -and in most cases overlooking parameters which normally would use \fBconst\fP. -Using constant parameters for functions which do not use \fBconst\fP -may prevent the program from compiling. -On the other hand, \fIwritable strings\fP are an obsolescent feature. -.IP -As an extension, this implementation can be configured to change the -function prototypes to use the \fBconst\fP keyword. -The ncurses ABI 6 enables this feature by default. -.bP -X/Open Curses prototypes \fBtparm\fP with a fixed number of parameters, -rather than a variable argument list. -.IP -This implementation uses a variable argument list, but can be -configured to use the fixed-parameter list. -Portable applications should provide 9 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 \fBtiparm\fP function in mid-2009. -.IP -While \fBtiparm\fP is always provided in ncurses, -the older form is only available as a build-time configuration option. -If not specially configured, \fBtparm\fP is the same as \fBtiparm\fP. -.PP -Both forms of \fBtparm\fP have drawbacks: -.bP -Most of the calls to \fBtparm\fP use only one or two parameters. -Passing nine on each call is awkward. -.IP -Using \fBlong\fP 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 long). -.bP -Providing the right number of parameters for a variadic function -such as \fBtiparm\fP can be a problem, in particular for string parameters. -However, only a few terminfo capabilities use string parameters -(e.g., the ones used for programmable function keys). -.IP -The ncurses library checks usage of these capabilities, -and returns an error if the capability mishandles string parameters. -But it cannot check if a calling program provides strings in the right -places for the \fBtparm\fP calls. -.IP -The \fB@TPUT@\fR(1) program checks its use of these capabilities with a table, -so that it calls \fBtparm\fP correctly. -.SS Special TERM treatment -If configured to use the terminal-driver, -e.g., for the MinGW port, -.bP -\fBsetupterm\fP interprets a missing/empty TERM variable as the -special value \*(``unknown\*(''. -.IP -SVr4 curses uses the -special value \*(``dumb\*(''. -.IP -The difference between the two is that -the former uses the \fBgn\fP (\fBgeneric_type\fR) terminfo capability, -while the latter does not. -A generic terminal is unsuitable for full-screen applications. -.bP -\fBsetupterm\fP allows explicit use of the -the windows console driver by checking if $TERM is set to -\*(``#win32con\*('' or an abbreviation of that string. -.SS Other portability issues -In System V Release 4, \fBset_curterm\fP has an \fBint\fP return type and -returns \fBOK\fP or \fBERR\fP. We have chosen to implement the X/Open Curses -semantics. -.PP -In System V Release 4, the third argument of \fBtputs\fP has the type -\fBint (*putc)(char)\fP. -.PP -At least one implementation of X/Open Curses (Solaris) returns a value -other than \fBOK\fP/\fBERR\fP from \fBtputs\fP. -That returns the length of the string, and does no error-checking. -.PP -X/Open notes that after calling \fBmvcur\fP, 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 \fBncurses\fP and System V Release 4 curses implement \fBmvcur\fP using -the SCREEN data allocated in either \fBinitscr\fP or \fBnewterm\fP. -So though it is documented as a terminfo function, -\fBmvcur\fP is really a curses function which is not well specified. -.PP -X/Open states that the old location must be given for \fBmvcur\fP. -This implementation allows the caller to use \-1's for the old ordinates. -In that case, the old location is unknown. +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\fP(3X), -\fBcurs_initscr\fP(3X), -\fBcurs_kernel\fP(3X), -\fBcurs_memleaks\fP(3X), -\fBcurs_termcap\fP(3X), -\fBcurs_variables\fP(3X), -\fBterm_variables\fP(3X), -\fBputc\fP(3), -\fBterminfo\fP(\*n) +\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)