+ clarify error-returns from newwin (report by Ruslan Nabioullin).
-- sale, use or other dealings in this Software without prior written --
-- authorization. --
-------------------------------------------------------------------------------
--- $Id: NEWS,v 1.2172 2014/02/23 01:19:35 tom Exp $
+-- $Id: NEWS,v 1.2174 2014/03/01 23:17:47 tom Exp $
-------------------------------------------------------------------------------
This is a log of changes that ncurses has gone through since Zeyd started
Changes through 1.9.9e did not credit all contributions;
it is not possible to add this information.
+20140301
+ + clarify error-returns from newwin (report by Ruslan Nabioullin).
+
20140222
+ fix some compiler warnings in win_driver.c
+ updated notes for wsvt25 based on tack and vttest -TD
# use or other dealings in this Software without prior written #
# authorization. #
##############################################################################
-# $Id: dist.mk,v 1.973 2014/02/22 16:55:12 tom Exp $
+# $Id: dist.mk,v 1.974 2014/03/01 14:32:51 tom Exp $
# Makefile for creating ncurses distributions.
#
# This only needs to be used directly as a makefile by developers, but
# These define the major/minor/patch versions of ncurses.
NCURSES_MAJOR = 5
NCURSES_MINOR = 9
-NCURSES_PATCH = 20140222
+NCURSES_PATCH = 20140301
# We don't append the patch to the version, since this only applies to releases
VERSION = $(NCURSES_MAJOR).$(NCURSES_MINOR)
.\"***************************************************************************
-.\" Copyright (c) 1998-2012,2013 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2013,2014 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 *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_initscr.3x,v 1.19 2013/07/20 19:34:14 tom Exp $
+.\" $Id: curs_initscr.3x,v 1.20 2014/03/01 22:31:22 tom Exp $
.TH curs_initscr 3X ""
+.de bP
+.IP \(bu 4
+..
.ie \n(.g .ds `` \(lq
.el .ds `` ``
.ie \n(.g .ds '' \(rq
.br
.SH DESCRIPTION
\fBinitscr\fR is normally the first \fBcurses\fR routine to call when
-initializing a program. A few special routines sometimes need to be
-called before it; these are \fBslk_init\fR, \fBfilter\fR, \fBripoffline\fR,
-\fBuse_env\fR. For multiple-terminal applications, \fBnewterm\fR may be
-called before \fBinitscr\fR.
+initializing a program.
+A few special routines sometimes need to be called before it;
+these are \fBslk_init\fR, \fBfilter\fR, \fBripoffline\fR,
+\fBuse_env\fR.
+For multiple-terminal applications,
+\fBnewterm\fR may be called before \fBinitscr\fR.
.PP
The initscr code determines the terminal type and initializes all \fBcurses\fR
-data structures. \fBinitscr\fR also causes the first call to \fBrefresh\fR to
-clear the screen. If errors occur, \fBinitscr\fR writes an appropriate error
-message to standard error and exits; otherwise, a pointer is returned to
-\fBstdscr\fR.
+data structures.
+\fBinitscr\fR also causes the first call to \fBrefresh\fR to clear the screen.
+If errors occur, \fBinitscr\fR writes an appropriate error
+message to standard error and exits;
+otherwise, a pointer is returned to \fBstdscr\fR.
.PP
A program that outputs to more than one terminal should use the \fBnewterm\fR
-routine for each terminal instead of \fBinitscr\fR. A program that needs to
-inspect capabilities, so it can continue to run in a line-oriented mode if the
+routine for each terminal instead of \fBinitscr\fR.
+A program that needs to inspect capabilities,
+so it can continue to run in a line-oriented mode if the
terminal cannot support a screen-oriented program, would also use
-\fBnewterm\fR. The routine \fBnewterm\fR should be called once for each
-terminal. It returns a variable of type \fBSCREEN *\fR which should be saved
-as a reference to that terminal. The arguments are the \fItype\fR of the
-terminal to be used in place of \fB$TERM\fR, a file pointer for output to the
-terminal, and another file pointer for input from the terminal (if \fItype\fR
-is \fBNULL\fR, \fB$TERM\fR will be used). The program must also call
+\fBnewterm\fR.
+The routine \fBnewterm\fR should be called once for each terminal.
+It returns a variable of type \fBSCREEN *\fR which should be saved
+as a reference to that terminal.
+\fBnewterm\fP's arguments are
+.bP
+the \fItype\fR of the terminal to be used in place of \fB$TERM\fR,
+.bP
+a file pointer for output to the terminal, and
+.bP
+another file pointer for input from the terminal
+.PP
+If the \fItype\fR parameter is \fBNULL\fR, \fB$TERM\fR will be used.
+.PP
+The program must also call
\fBendwin\fR for each terminal being used before exiting from \fBcurses\fR.
If \fBnewterm\fR is called more than once for the same terminal, the first
terminal referred to must be the last one for which \fBendwin\fR is called.
.PP
A program should always call \fBendwin\fR before exiting or escaping from
-\fBcurses\fR mode temporarily. This routine restores tty modes, moves the
-cursor to the lower left-hand corner of the screen and resets the terminal into
-the proper non-visual mode. Calling \fBrefresh\fR or \fBdoupdate\fR after a
+\fBcurses\fR mode temporarily.
+This routine
+.bP
+restores tty modes,
+.bP
+moves the cursor to the lower left-hand corner of the screen and
+.bP
+resets the terminal into
+the proper non-visual mode.
+.PP
+Calling \fBrefresh\fR or \fBdoupdate\fR after a
temporary escape causes the program to resume visual mode.
.PP
The \fBisendwin\fR routine returns \fBTRUE\fR if \fBendwin\fR has been
-called without any subsequent calls to \fBwrefresh\fR, and \fBFALSE\fR
-otherwise.
+called without any subsequent calls to \fBwrefresh\fR,
+and \fBFALSE\fR otherwise.
.PP
-The \fBset_term\fR routine is used to switch between different
-terminals. The screen reference \fBnew\fR becomes the new current
-terminal. The previous terminal is returned by the routine. This is
-the only routine which manipulates \fBSCREEN\fR pointers; all other
-routines affect only the current terminal.
+The \fBset_term\fR routine is used to switch between different terminals.
+The screen reference \fBnew\fR becomes the new current terminal.
+The previous terminal is returned by the routine.
+This is the only routine which manipulates \fBSCREEN\fR pointers;
+all other routines affect only the current terminal.
.PP
The \fBdelscreen\fR routine frees storage associated with the
-\fBSCREEN\fR data structure. The \fBendwin\fR routine does not do
+\fBSCREEN\fR data structure.
+The \fBendwin\fR routine does not do
this, so \fBdelscreen\fR should be called after \fBendwin\fR if a
particular \fBSCREEN\fR is no longer needed.
.SH RETURN VALUE
.PP
X/Open defines no error conditions.
In this implementation
+.bP
\fBendwin\fP returns an error if the terminal was not initialized.
+.bP
+\fBnewterm\fP
+returns an error if it cannot allocate the data structures for the screen,
+or for the top-level windows within the screen,
+i.e.,
+\fBcurscr\fP, \fBnewscr\fP, or \fBstdscr\fP.
+.bP
+\fBset_term\fP
+returns no error.
.SH NOTES
Note that \fBinitscr\fR and \fBnewterm\fR may be macros.
.SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4. It
-specifies that portable applications must not call \fBinitscr\fR more than
-once.
+These functions are described in the XSI Curses standard, Issue 4.
+It specifies that portable applications must not
+call \fBinitscr\fR more than once.
.PP
Old versions of curses, e.g., BSD 4.4, may have returned a null pointer
from \fBinitscr\fR when an error is detected, rather than exiting.
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2010,2014 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 *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_window.3x,v 1.17 2010/12/04 18:38:55 tom Exp $
+.\" $Id: curs_window.3x,v 1.18 2014/03/01 23:36:38 tom Exp $
.TH curs_window 3X ""
.na
.hy 0
.SH SYNOPSIS
\fB#include <curses.h>\fR
.sp
-\fBWINDOW *newwin(int nlines, int ncols, int begin_y,\fR
- \fBint begin_x);\fR
+\fBWINDOW *newwin(\fR
+ \fBint nlines, int ncols,\fR
+ \fBint begin_y, int begin_x);\fR
.br
\fBint delwin(WINDOW *win);\fR
.br
\fBint mvwin(WINDOW *win, int y, int x);\fR
.br
-\fBWINDOW *subwin(WINDOW *orig, int nlines, int ncols,\fR
+\fBWINDOW *subwin(WINDOW *orig,\fR
+ \fBint nlines, int ncols,\fR
\fBint begin_y, int begin_x);\fR
.br
-\fBWINDOW *derwin(WINDOW *orig, int nlines, int ncols,\fR
+\fBWINDOW *derwin(WINDOW *orig,\fR
+ \fBint nlines, int ncols,\fR
\fBint begin_y, int begin_x);\fR
.br
\fBint mvderwin(WINDOW *win, int par_y, int par_x);\fR
.br
.SH DESCRIPTION
Calling \fBnewwin\fR creates and returns a pointer to a new window with the
-given number of lines and columns. The upper left-hand corner of the window is
-at line \fIbegin\fR_\fIy\fR, column \fIbegin\fR_\fIx\fR. If either
-\fInlines\fR or \fIncols\fR is zero, they default to \fBLINES \-\fR
-\fIbegin\fR_\fIy\fR and \fBCOLS \-\fR \fIbegin\fR_\fIx\fR. A new full-screen
-window is created by calling \fBnewwin(0,0,0,0)\fR.
+given number of lines and columns.
+The upper left-hand corner of the window is
+at
+.RS
+line \fIbegin\fR_\fIy\fR,
+.br
+column \fIbegin\fR_\fIx\fR
+.RE
+.PP
+If either
+\fInlines\fR or \fIncols\fR is zero, they default to
+.RS
+\fBLINES \-\fR \fIbegin\fR_\fIy\fR and
+.br
+\fBCOLS \-\fR \fIbegin\fR_\fIx\fR.
+.RE
+.PP
+A new full-screen window is created by calling \fBnewwin(0,0,0,0)\fR.
.PP
Calling \fBdelwin\fR deletes the named window, freeing all memory
associated with it (it does not actually erase the window's screen
-image). Subwindows must be deleted before the main window can be
-deleted.
+image).
+Subwindows must be deleted before the main window can be deleted.
.PP
Calling \fBmvwin\fR moves the window so that the upper left-hand
-corner is at position (\fIx\fR, \fIy\fR). If the move would cause the
-window to be off the screen, it is an error and the window is not
-moved. Moving subwindows is allowed, but should be avoided.
+corner is at position (\fIx\fR, \fIy\fR).
+If the move would cause the window to be off the screen,
+it is an error and the window is not moved.
+Moving subwindows is allowed, but should be avoided.
.PP
Calling \fBsubwin\fR creates and returns a pointer to a new window
-with the given number of lines, \fInlines\fR, and columns,
-\fIncols\fR. The window is at position (\fIbegin\fR_\fIy\fR,
-\fIbegin\fR_\fIx\fR) on the screen. (This position is relative to the
-screen, and not to the window \fIorig\fR.) The window is made in the
-middle of the window \fIorig\fR, so that changes made to one window
-will affect both windows. The subwindow shares memory with the window
-\fIorig\fR. When using this routine, it is necessary to call
+with the given number of lines, \fInlines\fR, and columns, \fIncols\fR.
+The window is at position (\fIbegin\fR_\fIy\fR,
+\fIbegin\fR_\fIx\fR) on the screen.
+The subwindow shares memory with the window \fIorig\fR,
+so that changes made to one window
+will affect both windows.
+When using this routine, it is necessary to call
\fBtouchwin\fR or \fBtouchline\fR on \fIorig\fR before calling
\fBwrefresh\fR on the subwindow.
.PP
Calling \fBderwin\fR is the same as calling \fBsubwin,\fR except that
\fIbegin\fR_\fIy\fR and \fIbegin\fR_\fIx\fR are relative to the origin
-of the window \fIorig\fR rather than the screen. There is no
-difference between the subwindows and the derived windows.
+of the window \fIorig\fR rather than the screen.
+There is no difference between the subwindows and the derived windows.
.PP
Calling \fBmvderwin\fR moves a derived window (or subwindow)
-inside its parent window. The screen-relative parameters of the
-window are not changed. This routine is used to display different
+inside its parent window.
+The screen-relative parameters of the window are not changed.
+This routine is used to display different
parts of the parent window at the same physical position on the
screen.
.PP
Calling \fBdupwin\fR creates an exact duplicate of the window \fIwin\fR.
.PP
Calling \fBwsyncup\fR touches all locations in ancestors of \fIwin\fR that are
-changed in \fIwin\fR. If \fBsyncok\fR is called with second argument
+changed in \fIwin\fR.
+If \fBsyncok\fR is called with second argument
\fBTRUE\fR then \fBwsyncup\fR is called automatically whenever there is a
change in the window.
.PP
The \fBwsyncdown\fR routine touches each location in \fIwin\fR that has been
-touched in any of its ancestor windows. This routine is called by
+touched in any of its ancestor windows.
+This routine is called by
\fBwrefresh\fR, so it should almost never be necessary to call it manually.
.PP
The routine \fBwcursyncup\fR updates the current cursor position of all the
.PP
X/Open defines no error conditions.
In this implementation
-.RS
.TP 5
\fBdelwin\fR
returns an error if the window pointer is null, or
if the window is the parent of another window.
+.TP 5
+\fBderwin\fP
+returns an error if the parent window pointer is null, or
+if any of its ordinates or dimensions is negative, or
+if the resulting window does not fit inside the parent window.
+.TP 5
+\fBdupwin\fP
+returns an error if the window pointer is null.
.IP
This implementation also maintains a list of windows,
and checks that the pointer passed to \fBdelwin\fP is one that
if the window is really a pad, or
if some part of the window would be placed off-screen.
.TP 5
+\fBnewwin\fP
+will fail if either of its beginning ordinates is negative, or
+if either the number of lines or columns is negative.
+.TP 5
\fBsyncok\fP
returns an error
if the window pointer is null.
-.RE
+.TP 5
+\fBsubwin\fP
+returns an error if the parent window pointer is null, or
+if any of its ordinates or dimensions is negative, or
+if the resulting window does not fit inside the parent window.
+.PP
+The functions which return a window pointer
+may also fail if there is insufficient memory for its data structures.
+Any of these functions will fail if the screen has not been initialized,
+i.e., with \fBinitscr\fP or \fBnewterm\fP.
.SH NOTES
If many small changes are made to the window, the \fBwsyncup\fR option could
degrade performance.
incompletely implemented, and not well tested.
.PP
The System V curses documentation is very unclear about what \fBwsyncup\fR
-and \fBwsyncdown\fR actually do. It seems to imply that they are only
+and \fBwsyncdown\fR actually do.
+It seems to imply that they are only
supposed to touch exactly those lines that are affected by ancestor changes.
The language here, and the behavior of the \fBcurses\fR implementation,
-is patterned on the XPG4 curses standard. The weaker XPG4 spec may result
-in slower updates.
+is patterned on the XPG4 curses standard.
+The weaker XPG4 spec may result in slower updates.
.SH PORTABILITY
The XSI Curses standard, Issue 4 describes these functions.
.SH SEE ALSO
-ncurses6 (5.9-20140222) unstable; urgency=low
+ncurses6 (5.9-20140301) unstable; urgency=low
* latest weekly patch
- -- Thomas E. Dickey <dickey@invisible-island.net> Sat, 22 Feb 2014 11:55:12 -0500
+ -- Thomas E. Dickey <dickey@invisible-island.net> Sat, 01 Mar 2014 09:32:51 -0500
ncurses6 (5.9-20131005) unstable; urgency=low
-ncurses6 (5.9-20140222) unstable; urgency=low
+ncurses6 (5.9-20140301) unstable; urgency=low
* latest weekly patch
- -- Thomas E. Dickey <dickey@invisible-island.net> Sat, 22 Feb 2014 11:55:12 -0500
+ -- Thomas E. Dickey <dickey@invisible-island.net> Sat, 01 Mar 2014 09:32:51 -0500
ncurses6 (5.9-20131005) unstable; urgency=low
-ncurses6 (5.9-20140222) unstable; urgency=low
+ncurses6 (5.9-20140301) unstable; urgency=low
* latest weekly patch
- -- Thomas E. Dickey <dickey@invisible-island.net> Sat, 22 Feb 2014 11:55:12 -0500
+ -- Thomas E. Dickey <dickey@invisible-island.net> Sat, 01 Mar 2014 09:32:51 -0500
ncurses6 (5.9-20120608) unstable; urgency=low
-; $Id: mingw-ncurses.nsi,v 1.28 2014/02/22 16:55:12 tom Exp $\r
+; $Id: mingw-ncurses.nsi,v 1.29 2014/03/01 14:32:51 tom Exp $\r
\r
; TODO add examples\r
; TODO bump ABI to 6\r
!define VERSION_MAJOR "5"\r
!define VERSION_MINOR "9"\r
!define VERSION_YYYY "2014"\r
-!define VERSION_MMDD "0222"\r
+!define VERSION_MMDD "0301"\r
!define VERSION_PATCH ${VERSION_YYYY}${VERSION_MMDD}\r
\r
!define MY_ABI "5"\r
Summary: shared libraries for terminal handling
Name: mingw32-ncurses6
Version: 5.9
-Release: 20140222
+Release: 20140301
License: X11
Group: Development/Libraries
Source: ncurses-%{version}-%{release}.tgz
Summary: shared libraries for terminal handling
Name: ncurses6
Version: 5.9
-Release: 20140222
+Release: 20140301
License: X11
Group: Development/Libraries
Source: ncurses-%{version}-%{release}.tgz
projects / ncurses.git / commitdiff