ncurses 6.2 - patch 20201003

[ncurses.git] / man / curs_getstr.3x

diff --git a/man/curs_getstr.3x b/man/curs_getstr.3x
index 5f1601301f5bda484efde918f9d9bfeaa7fdf15f..d9bed5958976a9ba009629519844dae38261614d 100644 (file)
--- a/man/curs_getstr.3x
+++ b/man/curs_getstr.3x
@@ -1,5 +1,6 @@
 .\"***************************************************************************
 .\"***************************************************************************

-.\" Copyright (c) 1998-2010,2017 Free Software Foundation, Inc.              *
+.\" Copyright 2018-2019,2020 Thomas E. Dickey                                *
+.\" Copyright 1998-2010,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            *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
 .\" copy of this software and associated documentation files (the            *


@@ -26,12 +27,16 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"

-.\" $Id: curs_getstr.3x,v 1.22 2017/05/30 21:08:31 tom Exp $
+.\" $Id: curs_getstr.3x,v 1.29 2020/02/02 23:34:34 tom Exp $

 .TH curs_getstr 3X ""
 .ie \n(.g .ds `` \(lq
 .el       .ds `` ``
 .ie \n(.g .ds '' \(rq
 .el       .ds '' ''
 .TH curs_getstr 3X ""
 .ie \n(.g .ds `` \(lq
 .el       .ds `` ``
 .ie \n(.g .ds '' \(rq
 .el       .ds '' ''

+.de bP
+.ie n  .IP \(bu 4
+.el    .IP \(bu 2
+..

 .na
 .hy 0
 .SH NAME
 .na
 .hy 0
 .SH NAME


@@ -67,20 +72,30 @@
 .SH DESCRIPTION
 The function \fBgetstr\fR is equivalent to a series of calls to \fBgetch\fR,
 until a newline or carriage return is received (the terminating character is
 .SH DESCRIPTION
 The function \fBgetstr\fR is equivalent to a series of calls to \fBgetch\fR,
 until a newline or carriage return is received (the terminating character is

-not included in the returned string).  The resulting value is placed in the
-area pointed to by the character pointer \fIstr\fR.
+not included in the returned string).
+.\" X/Open says also until EOf
+.\" X/Open says then an EOS is added to the result
+.\" X/Open doesn't mention n<0
+The resulting value is placed in the
+area pointed to by the character pointer \fIstr\fR,
+followed by a NUL.

 .PP
 \fBwgetnstr\fR reads at most \fIn\fR characters, thus preventing a possible
 .PP
 \fBwgetnstr\fR reads at most \fIn\fR characters, thus preventing a possible

-overflow of the input buffer.  Any attempt to enter more characters (other
-than the terminating newline or carriage return) causes a beep.  Function
-keys also cause a beep and are ignored.  The \fBgetnstr\fR function reads
+overflow of the input buffer.
+Any attempt to enter more characters (other
+than the terminating newline or carriage return) causes a beep.
+Function
+keys also cause a beep and are ignored.
+The \fBgetnstr\fR function reads

 from the \fIstdscr\fR default window.
 .PP
 from the \fIstdscr\fR default window.
 .PP

-The user's erase and kill characters are interpreted.  If keypad
+The user's erase and kill characters are interpreted.
+If keypad

 mode is on for the window, \fBKEY_LEFT\fR and \fBKEY_BACKSPACE\fR
 are both considered equivalent to the user's kill character.
 .PP
 mode is on for the window, \fBKEY_LEFT\fR and \fBKEY_BACKSPACE\fR
 are both considered equivalent to the user's kill character.
 .PP

-Characters input are echoed only if \fBecho\fR is currently on.  In that case,
+Characters input are echoed only if \fBecho\fR is currently on.
+In that case,

 backspace is echoed as deletion of the previous character (typically a left
 motion).
 .SH RETURN VALUE
 backspace is echoed as deletion of the previous character (typically a left
 motion).
 .SH RETURN VALUE


@@ -108,8 +123,8 @@ Note that \fBgetstr\fR, \fBmvgetstr\fR, and \fBmvwgetstr\fR may be macros.
 These functions are described in the XSI Curses standard, Issue 4.
 They read single-byte characters only.
 The standard does not define any error conditions.
 These functions are described in the XSI Curses standard, Issue 4.
 They read single-byte characters only.
 The standard does not define any error conditions.

-This implementation returns ERR if the window pointer is null,
-or if the lower-level \fBwgetch\fR(3X) call returns an ERR.
+This implementation returns \fBERR\fP if the window pointer is null,
+or if the lower-level \fBwgetch\fR(3X) call returns an \fBERR\fP.

 .PP
 SVr3 and early SVr4 curses implementations did not reject function keys;
 the SVr4.0 documentation claimed that \*(``special keys\*(''
 .PP
 SVr3 and early SVr4 curses implementations did not reject function keys;
 the SVr4.0 documentation claimed that \*(``special keys\*(''


@@ -125,6 +140,53 @@ string by those implementations was predictable but not useful
 .PP
 The functions \fBgetnstr\fR, \fBmvgetnstr\fR, and \fBmvwgetnstr\fR were
 present but not documented in SVr4.
 .PP
 The functions \fBgetnstr\fR, \fBmvgetnstr\fR, and \fBmvwgetnstr\fR were
 present but not documented in SVr4.

+.PP
+X/Open Curses, Issue 5 (2007) stated that these functions
+\*(``read at most \fIn\fP bytes\*(''
+but did not state whether the terminating NUL is counted in that limit.
+X/Open Curses, Issue 7 (2009) changed that to say they
+\*(``read at most \fIn\fP\-1 bytes\*(''
+to allow for the terminating NUL.
+As of 2018, some implementations do, some do not count it:
+.bP
+ncurses 6.1 and PDCurses do not count the NUL in the given limit, while
+.bP
+Solaris SVr4 and NetBSD curses count the NUL as part of the limit.
+.bP
+Solaris xcurses provides both:
+its wide-character \fBwget_nstr\fP reserves a NUL,
+but its \fBwgetnstr\fP does not count the NUL consistently.
+.PP
+In SVr4 curses,
+a negative value of \fIn\fP tells \fBwgetnstr\fP to assume that the
+caller's buffer is large enough to hold the result,
+i.e., to act like \fBwgetstr\fP.
+X/Open Curses does not mention this
+(or anything related to negative or zero values of \fIn\fP),
+however most implementations
+use the feature, with different limits:
+.bP
+Solaris SVr4 curses and PDCurses limit the result to 255 bytes.
+Other Unix systems than Solaris are likely to use the same limit.
+.bP
+Solaris xcurses limits the result to \fBLINE_MAX\fP bytes.
+.bP
+NetBSD 7 assumes no particular limit for the result from \fBwgetstr\fP.
+However, it limits the \fBwgetnstr\fP parameter \fIn\fP to ensure
+that it is greater than zero.
+.IP
+A comment in NetBSD's source code states that this is specified in SUSv2.
+.bP
+ncurses (before 6.2) assumes no particular limit for the result
+from \fBwgetstr\fP, and treats the \fIn\fP parameter of \fBwgetnstr\fP
+like SVr4 curses.
+.bP
+ncurses 6.2 uses \fBLINE_MAX\fP,
+or a larger (system-dependent) value
+which the \fBsysconf\fP function may provide.
+If neither \fBLINE_MAX\fP or \fBsysconf\fP is available,
+ncurses uses the POSIX value for \fBLINE_MAX\fP (a 2048 byte limit).
+In either case, it reserves a byte for the terminating NUL.

 .SH SEE ALSO
 \fBcurses\fR(3X),
 \fBcurs_getch\fR(3X),
 .SH SEE ALSO
 \fBcurses\fR(3X),
 \fBcurs_getch\fR(3X),