ncurses 6.4 - patch 20230729

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

diff --git a/man/curs_getstr.3x b/man/curs_getstr.3x
index 948f1db34e9784c8a815d738f6ad469f33a39492..4901a0255389d6d4ff6fa98898281c032e8a5f25 100644 (file)
--- a/man/curs_getstr.3x
+++ b/man/curs_getstr.3x
@@ -27,8 +27,8 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"

-.\" $Id: curs_getstr.3x,v 1.40 2023/07/01 15:43:20 tom Exp $
-.TH curs_getstr 3X 2023-07-01 "ncurses 6.4" "Library calls"
+.\" $Id: curs_getstr.3x,v 1.41 2023/07/29 16:32:52 tom Exp $
+.TH curs_getstr 3X 2023-07-29 "ncurses 6.4" "Library calls"

 .ie \n(.g .ds `` \(lq
 .el       .ds `` ``
 .ie \n(.g .ds '' \(rq
 .ie \n(.g .ds `` \(lq
 .el       .ds `` ``
 .ie \n(.g .ds '' \(rq


@@ -69,27 +69,28 @@
 .br
 \fBint mvwgetnstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, char *\fIstr\fB, int \fIn\fB);\fR
 .SH DESCRIPTION
 .br
 \fBint mvwgetnstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, char *\fIstr\fB, int \fIn\fB);\fR
 .SH DESCRIPTION

-The function \fBgetstr\fP is equivalent to a series of calls to \fBgetch\fP,
-until a newline or carriage return is received (the terminating character is
-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\fP,
-followed by a NUL.
-.PP
-The \fBgetnstr\fP function reads
-from the \fIstdscr\fP default window.
-The other functions, such as \fBwgetnstr\fP,
-read from the window given as a parameter.
-.PP
-\fBgetnstr\fP reads at most \fIn\fP 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 function
+\fBwgetnstr\fP
+is equivalent to a series of calls to
+\fBwgetch\fP(3X),
+until a newline or carriage return terminates the series:
+.bP
+The terminating character is not included in the returned string.
+.bP
+In all instances, the end of the string is terminated
+by a NUL.
+.bP
+The function stores the result in the area pointed to
+by the \fIstr\fP parameter.
+.bP
+The function reads at most \fIn\fP characters,
+thus preventing a possible overflow of the input buffer.
+.IP
+Any attempt to enter more characters
+(other than the terminating newline or carriage return)
+causes a beep.
+.IP
+Function keys also cause a beep and are ignored.

 .PP
 The user's \fIerase\fP and \fIkill\fP characters are interpreted:
 .bP
 .PP
 The user's \fIerase\fP and \fIkill\fP characters are interpreted:
 .bP


@@ -98,26 +99,72 @@ at the end of the buffer, moving the cursor to the left.
 .IP
 If \fIkeypad\fP mode is on for the window,
 \fBKEY_LEFT\fP and \fBKEY_BACKSPACE\fP
 .IP
 If \fIkeypad\fP mode is on for the window,
 \fBKEY_LEFT\fP and \fBKEY_BACKSPACE\fP

-are both considered equivalent to the user's erase character.
+are both considered equivalent to the user's \fIerase\fP character.

 .bP
 The \fIkill\fP character (e.g., \fB^U\fP) erases the entire buffer,
 leaving the cursor at the beginning of the buffer.
 .PP
 Characters input are echoed only if \fBecho\fP is currently on.
 In that case,
 .bP
 The \fIkill\fP character (e.g., \fB^U\fP) erases the entire buffer,
 leaving the cursor at the beginning of the buffer.
 .PP
 Characters input are echoed only if \fBecho\fP is currently on.
 In that case,

-backspace is echoed as deletion of the previous character (typically a left
-motion).
+backspace is echoed as deletion of the previous character
+(typically a left motion).
+.PP
+The
+\fBgetnstr\fP,
+\fBmvgetnstr\fP,
+\fBmvwgetnstr\fP, and
+\fBwgetnstr\fP
+functions are identical
+to the
+\fBgetstr\fP,
+\fBmvgetstr\fP,
+\fBmvwgetstr\fP, and
+\fBwgetstr\fP
+functions, respectively,
+except that the
+\fB*n*\fP
+versions read at most
+\fIn\fP
+characters, letting the application prevent overflow of the
+input buffer.
+.SH NOTES
+Any of these functions other than
+\fBwgetnstr\fP
+may be macros.
+.PP
+Using
+\fBgetstr\fP,
+\fBmvgetstr\fP,
+\fBmvwgetstr\fP, or
+\fBwgetstr\fP
+to read a line that
+overflows the array pointed to by
+\fBstr\fP
+causes undefined
+results.
+The use of
+\fBgetnstr\fP,
+\fBmvgetnstr\fP,
+\fBmvwgetnstr\fP, or
+\fBwgetnstr\fP,
+respectively, is recommended.

 .SH RETURN VALUE
 .SH RETURN VALUE

-All routines return the integer \fBERR\fP upon failure and an \fBOK\fP (SVr4
-specifies only \*(``an integer value other than \fBERR\fP\*('') upon successful
-completion.
+All of these functions return the integer \fBOK\fP upon successful completion.
+(SVr4 specifies only \*(``an integer value other than \fBERR\fP\*('')
+If unsuccessful, they return \fBERR\fP.

 .PP
 X/Open defines no error conditions.
 .PP
 In this implementation,
 these functions return an error
 .PP
 X/Open defines no error conditions.
 .PP
 In this implementation,
 these functions return an error

+.bP

 if the window pointer is null, or
 if the window pointer is null, or

+.bP

 if its timeout expires without having any data.
 if its timeout expires without having any data.

+.bP
+if the associated call to
+\fBwgetch\fP
+failed.

 .PP
 This implementation provides an extension as well.
 If a \fBSIGWINCH\fP interrupts the function, it will return \fBKEY_RESIZE\fP
 .PP
 This implementation provides an extension as well.
 If a \fBSIGWINCH\fP interrupts the function, it will return \fBKEY_RESIZE\fP


@@ -126,12 +173,10 @@ rather than \fBOK\fP or \fBERR\fP.
 Functions with a \*(``mv\*('' prefix first perform a cursor movement using
 \fBwmove\fP, and return an error if the position is outside the window,
 or if the window pointer is null.
 Functions with a \*(``mv\*('' prefix first perform a cursor movement using
 \fBwmove\fP, and return an error if the position is outside the window,
 or if the window pointer is null.

-.SH NOTES
-Note that \fBgetstr\fP, \fBmvgetstr\fP, and \fBmvwgetstr\fP may be macros.

 .SH PORTABILITY
 .SH PORTABILITY

-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 Single Unix Specification, Version 2.
+No error conditions are defined.
+.PP

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


@@ -156,7 +201,7 @@ 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.
 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:
+As of 2018, some implementations count it, some do not:

 .bP
 ncurses 6.1 and PDCurses do not count the NUL in the given limit, while
 .bP
 .bP
 ncurses 6.1 and PDCurses do not count the NUL in the given limit, while
 .bP