X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_terminfo.3x;h=10d1fa78b6b4227983fef4822000a52611938b54;hp=c6eac6e3053607a94816e52219b5a99005f29271;hb=HEAD;hpb=c55d387cebf1cee4757ca2c2ef4fbeae59ee4175 diff --git a/man/curs_terminfo.3x b/man/curs_terminfo.3x index c6eac6e3..10d1fa78 100644 --- a/man/curs_terminfo.3x +++ b/man/curs_terminfo.3x @@ -1,5 +1,7 @@ +'\" t .\"*************************************************************************** -.\" Copyright (c) 1999-2018,2020 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,615 +28,1115 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_terminfo.3x,v 1.63 2020/01/18 23:55:46 tom Exp $ -.TH curs_terminfo 3X "" -.ie \n(.g .ds `` \(lq -.el .ds `` `` -.ie \n(.g .ds '' \(rq -.el .ds '' '' +.\" $Id: curs_terminfo.3x,v 1.136 2024/04/14 00:14:40 tom Exp $ +.TH curs_terminfo 3X 2024-04-13 "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\fR, -\fBmvcur\fR, -\fBputp\fR, -\fBrestartterm\fR, -\fBset_curterm\fR, -\fBsetterm\fR, -\fBsetupterm\fR, -\fBtigetflag\fR, -\fBtigetnum\fR, -\fBtigetstr\fR, -\fBtiparm\fR, -\fBtparm\fR, -\fBtputs\fR, -\fBvid_attr\fR, -\fBvid_puts\fR, -\fBvidattr\fR, -\fBvidputs\fR \- \fBcurses\fR interfaces to terminfo database -.ad -.hy +\fB\%del_curterm\fP, +\fB\%mvcur\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 \fR -.br -\fB#include \fR -.sp -\fBTERMINAL *cur_term;\fR -.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 *\fR\fIterm\fR\fB, int \fR\fIfiledes\fR\fB, int *\fR\fIerrret\fR\fB);\fR -.br -\fBint setterm(const char *\fR\fIterm\fR\fB);\fR -.br -\fBTERMINAL *set_curterm(TERMINAL *\fR\fInterm\fR\fB);\fR -.br -\fBint del_curterm(TERMINAL *\fR\fIoterm\fR\fB);\fR -.br -\fBint restartterm(const char *\fR\fIterm\fR\fB, int \fR\fIfiledes\fR\fB, int *\fR\fIerrret\fR\fB);\fR -.sp -\fBchar *tparm(const char *\fR\fIstr\fR\fB, ...);\fR -.br -\fBint tputs(const char *\fR\fIstr\fR\fB, int \fR\fIaffcnt\fR\fB, int (*\fR\fIputc\fR\fB)(int));\fR -.br -\fBint putp(const char *\fR\fIstr\fR\fB);\fR -.sp -\fBint vidputs(chtype \fR\fIattrs\fR\fB, int (*\fR\fIputc\fR\fB)(int));\fR -.br -\fBint vidattr(chtype \fR\fIattrs\fR\fB);\fR -.br -\fBint vid_puts(attr_t \fR\fIattrs\fR\fB, short \fR\fIpair\fR\fB, void *\fR\fIopts\fR\fB, int (*\fR\fIputc\fR\fB)(int));\fR -.br -\fBint vid_attr(attr_t \fR\fIattrs\fR\fB, short \fR\fIpair\fR\fB, void *\fR\fIopts\fR\fB);\fR -.sp -\fBint mvcur(int \fR\fIoldrow\fR\fB, int \fR\fIoldcol\fR\fB, int \fR\fInewrow\fR, int \fR\fInewcol\fR\fB);\fR -.sp -\fBint tigetflag(const char *\fR\fIcapname\fR\fB);\fR -.br -\fBint tigetnum(const char *\fR\fIcapname\fR\fB);\fR -.br -\fBchar *tigetstr(const char *\fR\fIcapname\fR\fB);\fR -.sp -\fBchar *tiparm(const char *\fR\fIstr\fR\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 mvcur(int \fIoldrow\fP, int \fIoldcol\fP, int \fInewrow\fP, int \fInewcol\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. -.SS Initialization +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 -Initially, \fBsetupterm\fR should be called. -The high-level curses functions \fBinitscr\fR and -\fBnewterm\fR call \fBsetupterm\fP to initialize the -low-level set of terminal-dependent variables -[listed in \fBterminfo\fR(\*n)]. +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), +Applications can use the terminal capabilities either directly +(via header definitions), or by special functions. -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. +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\fR variables -\fBlines\fR and \fBcolumns\fR are initialized by \fBsetupterm\fR 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)\fR has been called, values for -\fBlines\fR and \fBcolumns\fR specified in \fBterminfo\fR 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\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 +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\fR and \fBcolumns\fR specified in the -\fBterminfo\fR database are used. -.PP -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 \fBreset_shell_mode\fR to restore the -tty modes before exiting [see \fBcurs_kernel\fR(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\fR upon startup and +output \fB\%enter_ca_mode\fP upon startup and .bP -output \fBexit_ca_mode\fR 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\fR and -output \fBexit_ca_mode\fR 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\fR and -call \fBreset_prog_mode\fR 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\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. -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\fR is null, the environment variable \fBTERM\fR 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 -is the file descriptor used for all output. +.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 -\fIerrret\fP +.I errret points to an optional location where an error status can be returned to the caller. -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 +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\fR is returned, examine \fIerrret\fR: +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\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\fR database could not be found. +means that the +.I \%term\%info +database could not be found. .RE .IP -If \fIerrret\fR is -null, \fBsetupterm\fR prints an error message upon finding an error -and exits. -Thus, the simplest call is: -.sp - \fBsetupterm((char *)0, 1, (int *)0);\fR, -.sp -which uses all the defaults and sends the output to \fBstdout\fR. +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 -.PP -The \fBsetterm\fR routine was replaced by \fBsetupterm\fR. The call: -.sp - \fBsetupterm(\fR\fIterm\fR\fB, 1, (int *)0)\fR -.sp -provides the same functionality as \fBsetterm(\fR\fIterm\fR\fB)\fR. -The \fBsetterm\fR routine is provided for BSD compatibility, and -is not recommended for new programs. -.\" *************************************************************************** -.SS The Terminal State -.PP -The \fBsetupterm\fR routine stores its information about the terminal -in a \fBTERMINAL\fP structure pointed to by the global variable \fBcur_term\fP. +.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), +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\fR routine sets \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. -.PP -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. -.PP -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). -\fBrestartterm\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 +\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 -The \fBtparm\fR routine instantiates the string \fIstr\fR with -parameters \fIpi\fR. A pointer is returned to the result of \fIstr\fR +\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. -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 \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 -\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. -.\" *************************************************************************** -.SS Output Functions +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 -The \fBtputs\fR routine applies padding information to the string -\fIstr\fR and outputs it: +\fB\%tputs\fP interprets time-delay information in the string +.I str +and outputs it, +executing the delays: .bP -The \fIstr\fR parameter must be a terminfo string -variable or the return value from -\fBtparm\fR, \fBtiparm\fP, \fBtgetstr\fR, or \fBtgoto\fR. +The +.I str +parameter must be a +.I \%term\%info +string variable or the return value of +\fB\%tparm\fP, +\fB\%tiparm\fP, +\fB\%tgetstr\fP, +or \fB\%tgoto\fP. .IP -The \fBtgetstr\fP and \fBtgoto\fP functions are part of the \fItermcap\fP +The \fB\%tgetstr\fP and \fB\%tgoto\fP functions are part of the +.I termcap interface, -which happens to share this function name with the \fIterminfo\fP interface. +which happens to share these function names with the +.I \%term\%info +API. .bP -\fIaffcnt\fR is the number of lines affected, or 1 if -not applicable. +.I affcnt +is the number of lines affected, +or +.B 1 +if not applicable. .bP -\fIputc\fR is a \fBputchar\fR-like routine to which -the characters are passed, one at a time. +.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(\fR\fIstr\fR\fB, 1, putchar)\fR. -The output of \fBputp\fR always goes to \fBstdout\fR, rather than -the \fIfiledes\fR specified in \fBsetupterm\fR. +\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\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. +\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\fR routine is like the \fBvidputs\fR routine, except -that it outputs through \fBputchar\fR. +\fB\%vidattr\fP is like \fB\%vidputs\fP, +except that it outputs through \fI\%putchar\fP(3). .PP -The \fBvid_attr\fR and \fBvid_puts\fR 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\fR and \fBvid_puts\fR routines -are designed to use the attribute constants with the \fIWA_\fR 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. +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 -The \fBmvcur\fR routine provides low-level cursor motion. -It takes -effect immediately (rather than at the next refresh). -.\" *************************************************************************** -.SS Terminal Capability Functions +\fB\%mvcur\fP 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, +\fB\%mvcur\fP uses an output file descriptor derived from +the output stream parameter of \fB\%newterm\fP(3X). .PP -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 \fIcapname\fR for each capability is given in the table column entitled -\fIcapname\fR code in the capabilities section of \fBterminfo\fR(\*n). +While \fB\%putp\fP and \fB\%mvcur\fP are low-level functions that do not +use high-level +.I curses +state, +.I \%ncurses +declares them 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 routines return special values to denote errors. +These functions return special values to denote errors. .PP -The \fBtigetflag\fR routine returns +\fB\%tigetflag\fP returns .TP -\fB\-1\fR -if \fIcapname\fR is not a boolean capability, +.B \-1 +if +.I cap-code +is not a Boolean capability, or .TP -\fB0\fR +.B 0 if it is canceled or absent from the terminal description. .PP -The \fBtigetnum\fR routine returns +\fB\%tigetnum\fP returns .TP -\fB\-2\fR -if \fIcapname\fR is not a numeric capability, or +.B \-2 +if +.I cap-code +is not a numeric capability, +or .TP -\fB\-1\fR +.B \-1 if it is canceled or absent from the terminal description. .PP -The \fBtigetstr\fR routine returns +\fB\%tigetstr\fP returns .TP -\fB(char *)\-1\fR -if \fIcapname\fR is not a string capability, +.B "(char *)\-1" +if +.I cap-code +is not a string capability, or .TP -\fB0\fR +.B 0 if it is canceled or absent from the terminal description. -.\" *************************************************************************** -.SS Terminal Capability Names -.PP +.\" ******************************************************************** +.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\fR 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\fR variables: -.sp .RS -\fBconst char *boolnames[]\fR, \fB*boolcodes[]\fR, \fB*boolfnames[]\fR -.br -\fBconst char *numnames[]\fR, \fB*numcodes[]\fR, \fB*numfnames[]\fR -.br -\fBconst char *strnames[]\fR, \fB*strcodes[]\fR, \fB*strfnames[]\fR +.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 -.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. +.\" ******************************************************************** +.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 -Routines that return pointers always return \fBNULL\fR on error. +the memory will be freed. .PP -X/Open defines no error conditions. -In this implementation -.RS 3 +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 +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 an error. .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 -\fBtputs\fP -returns an error if the string parameter is null. +.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 states that \fBtputs\fP ignores the return value -of the output function \fIputc\fP. +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 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 an error 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. +.PP +X/Open Curses notes that after calling \fB\%mvcur\fP, +the +.I curses +state may not match the actual terminal state, +and that an application should touch and refresh the window before +resuming normal +.I curses +calls. +Both +.I \%ncurses +and SVr4 +.I curses +implement \fB\%mvcur\fP using the +.I SCREEN +data allocated in either \fB\%initscr\fP or \fB\%newterm\fP. +So though it is documented as a +.I \%term\%info +function, +\fB\%mvcur\fP is really a +.I curses +function that is not well specified. +.PP +X/Open Curses states that the old location must be given for +\fB\%mvcur\fP to accommodate terminals that lack absolute cursor +positioning. +.\" X/Open Curses Issue 7, p. 161 +.I \%ncurses +allows the caller to use \-1 for either or both old coordinates. +The \-1 tells +.I \%ncurses +that the old location is unknown, +and that it must use only absolute motion, +as with the +.B \%cursor_address +.RB ( cup ) +capability, +rather than the least costly combination of absolute and relative +motion. +.\" ******************************************************************** .SH HISTORY +SVr2 (1984) introduced the +.I \%term\%info +feature. +Its programming manual mentioned the following low-level functions. .PP -SVr2 introduced the terminfo feature. -Its programming manual mentioned these low-level functions: .TS -l l -_ _ -l l. -\fBFunction\fR \fBDescription\fR -fixterm restore tty to \*(``in curses\*('' state -gettmode establish current tty modes +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 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\fR \fBDescription\fR -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\fR. +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 -SVr3 extended terminfo by adding functions to retrieve capability values -(like the termcap interface), -and reusing tgoto and tputs: .TS -l l -_ _ -l l. -\fBFunction\fR \fBDescription\fR -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\fR \fBReplaced by\fP -crmode cbreak -fixterm reset_prog_mode -gettmode N/A -nocrmode nocbreak -resetterm reset_shell_mode -saveterm def_prog_mode -setterm setupterm +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 \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. -The various global variables such as \fBboolnames\fP were mentioned -in the programming manual at this point. -.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 editor. -.SH PORTABILITY -.SS Legacy functions -.PP -X/Open notes that \fBvidattr\fR and \fBvidputs\fR may be macros. -.PP -The function \fBsetterm\fR is not described by X/Open and must -be considered non-portable. -All other functions are as described by X/Open. -.SS Legacy data -.PP -\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. -.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 -.PP -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. -.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 -.PP -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. +descriptions; +for example, +\fB\%set_curterm\fP. +Some changes reflected incremental improvements to the SVr2 library. .bP -X/Open Curses prototypes \fBtparm\fR 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. -.SS Special TERM treatment -.PP -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\*(''. +The +.I \%TERMINAL +type definition was introduced in SVr3.01, +for the +.I term +structure provided in SVr2. .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 +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 -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 X/Open Curses -semantics. +SVr4 (1989) added the \fB\%vid_attr\fP and \fB\%vid_puts\fP functions. .PP -In System V Release 4, the third argument of \fBtputs\fR has the type -\fBint (*putc)(char)\fR. -.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\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 \fBncurses\fP 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. -.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\fR(3X), -\fBcurs_initscr\fR(3X), -\fBcurs_kernel\fR(3X), -\fBcurs_termcap\fR(3X), -\fBcurs_variables\fR(3X), -\fBterm_variables\fR(3X), -\fBputc\fR(3), -\fBterminfo\fR(\*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)