Diffstat (limited to 'man/curs_getstr.3x')
1 files changed, 87 insertions, 17 deletions
diff --git a/man/curs_getstr.3x b/man/curs_getstr.3x
index e548cf145c25..818dc9035a0e 100644
@@ -1,5 +1,5 @@
-.\" Copyright (c) 1998-2005,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 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,8 +26,16 @@
.\" authorization. *
-.\" $Id: curs_getstr.3x,v 1.19 2010/12/04 18:36:44 tom Exp $
+.\" $Id: curs_getstr.3x,v 1.28 2019/07/20 19:14:56 tom Exp $
.TH curs_getstr 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
+.ie n .IP \(bu 4
+.el .IP \(bu 2
@@ -63,25 +71,35 @@
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.
\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.
+keys also cause a beep and are ignored.
+The \fBgetnstr\fR function reads
from the \fIstdscr\fR default window.
-The user's erase and kill characters are interpreted. If keypad
+The user's erase and kill characters are interpreted.
mode is on for the window, \fBKEY_LEFT\fR and \fBKEY_BACKSPACE\fR
are both considered equivalent to the user's kill character.
-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
.SH RETURN VALUE
All routines return the integer \fBERR\fR upon failure and an \fBOK\fR (SVr4
-specifies only "an integer value other than \fBERR\fR") upon successful
+specifies only \*(``an integer value other than \fBERR\fR\*('') upon successful
X/Open defines no error conditions.
@@ -92,10 +110,10 @@ if the window pointer is null, or
if its timeout expires without having any data.
This implementation provides an extension as well.
-If a SIGWINCH interrupts the function, it will return \fBKEY_RESIZE\fP
+If a \fBSIGWINCH\fP interrupts the function, it will return \fBKEY_RESIZE\fP
rather than \fBOK\fP or \fBERR\fP.
-Functions with a "mv" prefix first perform a cursor movement using
+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.
@@ -104,18 +122,70 @@ 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.
-This implementation returns ERR if the window pointer is null,
-or if the lower-level \fBwgetch\fR 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.
SVr3 and early SVr4 curses implementations did not reject function keys;
-the SVr4.0 documentation claimed that "special keys" (such as function
-keys, "home" key, "clear" key, \fIetc\fR.) are "interpreted", without
-giving details. It lied. In fact, the `character' value appended to the
+the SVr4.0 documentation claimed that \*(``special keys\*(''
+(such as function keys,
+\fIetc\fR.) are \*(``interpreted\*('',
+without giving details.
+In fact, the \*(``character\*('' value appended to the
string by those implementations was predictable but not useful
(being, in fact, the low-order eight bits of the key's KEY_ value).
The functions \fBgetnstr\fR, \fBmvgetnstr\fR, and \fBmvwgetnstr\fR were
present but not documented in SVr4.
+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:
+ncurses 6.1 and PDCurses do not count the NUL in the given limit, while
+Solaris SVr4 and NetBSD curses count the NUL as part of the limit.
+Solaris xcurses provides both:
+its wide-character \fBwget_nstr\fP reserves a NUL,
+but its \fBwgetnstr\fP does not count the NUL consistently.
+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:
+Solaris SVr4 curses and PDCurses limit the result to 255 bytes.
+Other Unix systems than Solaris are likely to use the same limit.
+Solaris xcurses limits the result to \fBLINE_MAX\fP bytes.
+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.
+A comment in NetBSD's source code states that this is specified in SUSv2.
+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.
+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