+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.
+.\" ********************************************************************
projects / ncurses.git / blobdiff