ncurses 5.9 - patch 20140301
authorThomas E. Dickey <dickey@invisible-island.net>
Sun, 2 Mar 2014 01:49:38 +0000 (01:49 +0000)
committerThomas E. Dickey <dickey@invisible-island.net>
Sun, 2 Mar 2014 01:49:38 +0000 (01:49 +0000)
+ clarify error-returns from newwin (report by Ruslan Nabioullin).

NEWS
dist.mk
man/curs_initscr.3x
man/curs_window.3x
package/debian-mingw/changelog
package/debian-mingw64/changelog
package/debian/changelog
package/mingw-ncurses.nsi
package/mingw-ncurses.spec
package/ncurses.spec

diff --git a/NEWS b/NEWS
index e7cbd9bf1c56a5a901404d629bed5d462efab679..ba4d91d23d560f345283053962101795d822c8bb 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -25,7 +25,7 @@
 -- 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
@@ -45,6 +45,9 @@ See the AUTHORS file for the corresponding full names.
 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
diff --git a/dist.mk b/dist.mk
index 11db597de4c90f7c9658d9329e6e7be6b8f84530..134dce39f6bf5698aa07fab476873086841cc06a 100644 (file)
--- a/dist.mk
+++ b/dist.mk
@@ -25,7 +25,7 @@
 # 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
@@ -37,7 +37,7 @@ SHELL = /bin/sh
 # 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)
index 0dceb973d1e6e3eadab24aaae6511cbf2ced0cf2..073f258e8769a2e341252d6e370a58604456fb0f 100644 (file)
@@ -1,5 +1,5 @@
 .\"***************************************************************************
-.\" 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
@@ -113,13 +138,23 @@ Routines that return pointers always return \fBNULL\fR on error.
 .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.
index 9ef41ff523d185087150ba174dc80c8d7d3ae94c..ec811d367ec2cbbb54a73a9392b66eee6bd5cf03 100644 (file)
@@ -1,5 +1,5 @@
 .\"***************************************************************************
-.\" 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            *
@@ -26,7 +26,7 @@
 .\" 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
@@ -135,11 +155,18 @@ Routines that return pointers return \fBNULL\fR on error.
 .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
@@ -156,10 +183,23 @@ if the window pointer is null, or
 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.
@@ -171,11 +211,12 @@ The subwindow functions (\fIsubwin\fR, \fIderwin\fR, \fImvderwin\fR,
 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
index bda20d7c9b43d6434e01efc88345bfe83534f9c8..fe1ff2f2dc07526f20eb40611d1255f37ecbe516 100644 (file)
@@ -1,8 +1,8 @@
-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
 
index bda20d7c9b43d6434e01efc88345bfe83534f9c8..fe1ff2f2dc07526f20eb40611d1255f37ecbe516 100644 (file)
@@ -1,8 +1,8 @@
-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
 
index 019318ddf19aa595d60be6e634e982a2f8397e3c..e0705e82184b95b68ff2a36378d65a49baa1d32a 100644 (file)
@@ -1,8 +1,8 @@
-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
 
index 81463c7d3606e1513398a94550b808d45408394c..51907df3831a619a0078e6fe9a7454fe460e29d1 100644 (file)
@@ -1,4 +1,4 @@
-; $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
@@ -10,7 +10,7 @@
 !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
index 2e86c17f368eb8c145599ffe7607ac4eb19c173f..a1116fd282d93453a77aa62f31abbee896d85a64 100644 (file)
@@ -3,7 +3,7 @@
 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
index d786d6e3818bcb781565ae30226f941cd7e8d51a..b06a6450d826e3a398678d93a1f1955e0350dea3 100644 (file)
@@ -1,7 +1,7 @@
 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