.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_terminfo.3x,v 1.130 2024/02/24 20:04:09 tom Exp $
-.TH curs_terminfo 3X 2024-02-24 "ncurses 6.4" "Library calls"
+.\" $Id: curs_terminfo.3x,v 1.138 2024/05/25 21:02:40 tom Exp $
+.TH curs_terminfo 3X 2024-05-25 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.
.SH NAME
\fB\%del_curterm\fP,
-\fB\%mvcur\fP,
\fB\%putp\fP,
\fB\%restartterm\fP,
\fB\%set_curterm\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);
.I \%term\%info
structures,
but does not set up the output virtualization structures used by
-.I curses.
+.IR curses .
Its parameters follow.
.RS 3
.TP 5
passing an output
.I stream
rather than a
-.I descriptor.
+.IR descriptor .
In
-.I curses,
+.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
or
.B ERR
and stores a status value in the integer pointed to by
-.I errret.
+.IR errret .
A return value of
.B OK
combined with status of
capabilities.
.PP
\fB\%set_curterm\fP sets \fB\%cur_term\fP to
-.I \%nterm,
+.IR \%nterm ,
and makes all of the
.I \%term\%info
Boolean,
numeric,
and string variables use the values from
-.I \%nterm.
+.IR \%nterm .
It returns the old value of \fB\%cur_term\fP.
.PP
\fB\%del_curterm\fP frees the space pointed to by
\fB\%tparm\fP instantiates the string
.I str
with parameters
-.I pi.
+.IR pi .
A pointer is returned to the result of
.I str
with the parameters applied.
Its numeric parameters are
.IR int s
rather than
-.IR long s.
+.IR long "s."
.PP
Both \fB\%tparm\fP and \fB\%tiparm\fP assume that the application passes
parameters consistent with the terminal description.
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 \fB\%tgetstr\fP and \fB\%tgoto\fP functions are part of the
-.I termcap
-interface,
-which happens to share these function names with the
-.I \%term\%info
-API.
+.B \%tparm
+or
+.BR \%tiparm "."
.bP
.I affcnt
is the number of lines affected,
.PP
\fB\%vidputs\fP displays the string on the terminal in the video
attribute mode
-.I attrs,
+.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
-.I putc.
+.IR putc .
.PP
\fB\%vidattr\fP is like \fB\%vidputs\fP,
except that it outputs through \fI\%putchar\fP(3).
color;
namely,
.bP
-.I \%attrs,
+.IR \%attrs ,
of type
-.I \%attr_t,
+.IR \%attr_t ,
for the attributes and
.bP
-.I pair,
+.IR pair ,
of type
-.I short,
+.IR short ,
for the color pair number.
.PP
Use the attribute constants prefixed with
saying that applications must provide a null pointer for that argument;
but see section \*(``EXTENSIONS\*('' below.
.PP
-\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
-While \fB\%putp\fP and \fB\%mvcur\fP are low-level functions that do not
-use high-level
+While \fB\%putp\fP is a low-level function that does not use high-level
.I curses
state,
.I \%ncurses
-declares them in
+declares it in
.I \%curses.h
because System\ V did this
(see section \*(``HISTORY\*('' below).
and \fB\%tigetstr\fP return the value of the capability corresponding to
the
.I \%term\%info
-.I cap-code,
+.IR cap-code ,
such as
.BR xenl ,
passed to them.
.SH RETURN VALUE
X/Open Curses defines no failure conditions.
In
-.I \%ncurses,
+.IR \%ncurses ,
.TP 5
.B del_curtem
fails if its terminal parameter is null.
returning the same error codes.
.TP 5
.B restartterm
-fails if the associated call to \fB\%setupterm\fP returns an error.
+fails if the associated call to \fB\%setupterm\fP returns
+.BR ERR "."
.TP 5
.B setupterm
fails if it cannot allocate enough memory,
.\" ********************************************************************
.SH EXTENSIONS
The functions marked as extensions were designed for
-.I \%ncurses,
+.IR \%ncurses ,
and are not found in SVr4
.IR curses ,
4.4BSD
allows
.I opts
to be a pointer to
-.I int,
+.IR int ,
which overrides the
.I pair
.RI ( short )
.PP
Other implementions may not declare the capability name arrays.
Some provide them without declaring them.
-X/Open does not specify them.
+X/Open Curses does not specify them.
.PP
Extended terminal capability names,
as defined by
.PP
The current version (ncurses6)
uses output buffers managed directly by
-.I \%ncurses.
+.IR \%ncurses .
Some of the low-level functions described in this manual page write
to the standard output.
They are not signal-safe.
X/Open Curses uses
.I \%const
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
-.I \%const.
-Using constant parameters for functions which do not use
+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,
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.
+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
.SS "Other Portability Issues"
In SVr4,
\fB\%set_curterm\fP returns an
-.I int,
+.IR int ,
.B OK
or
.BR 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 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
projects / ncurses.git / blobdiff