ncurses 6.5 - patch 20240525

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

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

-.\" Copyright 2018-2022,2023 Thomas E. Dickey                                *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey                                *

 .\" Copyright 1998-2010,2017 Free Software Foundation, Inc.                  *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
 .\" Copyright 1998-2010,2017 Free Software Foundation, Inc.                  *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *


@@ -27,8 +27,8 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"

-.\" $Id: curs_getstr.3x,v 1.51 2023/11/25 14:29:54 tom Exp $
-.TH curs_getstr 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: curs_getstr.3x,v 1.61 2024/05/25 20:10:58 tom Exp $
+.TH curs_getstr 3X 2024-05-25 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"

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


@@ -135,7 +135,8 @@ If unsuccessful, they return \fBERR\fP.
 X/Open defines no error conditions.
 .PP
 In this implementation,
 X/Open defines no error conditions.
 .PP
 In this implementation,

-these functions return an error
+these functions return
+.B ERR

 .bP
 if the window pointer is null,
 .bP
 .bP
 if the window pointer is null,
 .bP


@@ -149,9 +150,11 @@ This implementation provides an extension as well.
 If a \fBSIGWINCH\fP interrupts the function, it will return \fBKEY_RESIZE\fP
 rather than \fBOK\fP or \fBERR\fP.
 .PP
 If a \fBSIGWINCH\fP interrupts the function, it will return \fBKEY_RESIZE\fP
 rather than \fBOK\fP or \fBERR\fP.
 .PP

-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 prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.

 .SH NOTES
 Any of these functions other than
 \fBwgetnstr\fP
 .SH NOTES
 Any of these functions other than
 \fBwgetnstr\fP


@@ -197,13 +200,13 @@ present but not documented in SVr4.
 .PP
 X/Open Curses, Issue 5 (2007) stated that these functions
 \*(``read at most \fIn\fP bytes\*(''
 .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.
+but did not state whether the terminating NUL counted toward 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 count it, some do not:
 .bP
 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 count it, some do not:
 .bP

-ncurses 6.1 and PDCurses do not count the NUL in the given limit, while
+\fI\%ncurses\fP 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
 .bP
 Solaris SVr4 and NetBSD curses count the NUL as part of the limit.
 .bP


@@ -231,15 +234,15 @@ that it is greater than zero.
 .IP
 A comment in NetBSD's source code states that this is specified in SUSv2.
 .bP
 .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
+\fI\%ncurses\fP (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
 from \fBwgetstr\fP, and treats the \fIn\fP parameter of \fBwgetnstr\fP
 like SVr4 curses.
 .bP

-ncurses 6.2 uses \fBLINE_MAX\fP,
+\fI\%ncurses\fP 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,
 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).
+\fI\%ncurses\fP uses the POSIX value for \fBLINE_MAX\fP (a 2048 byte limit).

 In either case, it reserves a byte for the terminating NUL.
 .PP
 Although \fBgetnstr\fP is equivalent to a series of calls to \fBgetch\fP,
 In either case, it reserves a byte for the terminating NUL.
 .PP
 Although \fBgetnstr\fP is equivalent to a series of calls to \fBgetch\fP,


@@ -269,21 +272,30 @@ They may take the \fIcbreak\fP
 mode set by the caller into account when deciding whether to handle
 echoing within \fBgetnstr\fP or as a side-effect of the \fBgetch\fP calls.
 .bP
 mode set by the caller into account when deciding whether to handle
 echoing within \fBgetnstr\fP or as a side-effect of the \fBgetch\fP calls.
 .bP

-The original ncurses (as \fIpcurses\fP in 1986) set \fBnoraw\fP and \fBcbreak\fP
-when accepting input for \fBgetnstr\fP.
+The original \fI\%ncurses\fP
+(as \fIpcurses\fP in 1986)
+set \fBnoraw\fP and \fBcbreak\fP when accepting input for \fBgetnstr\fP.

 That may have been done to make function- and cursor-keys work;
 That may have been done to make function- and cursor-keys work;

-it is not necessary with ncurses.
+it is not necessary with \fI\%ncurses\fP.

 .IP
 .IP

-Since 1995, ncurses has provided signal handlers for INTR and QUIT
+Since 1995,
+\fI\%ncurses\fP has provided signal handlers for INTR and QUIT

 (e.g., \fB^C\fP or \fB^\e\fP).
 With the \fBnoraw\fP and \fBcbreak\fP settings,
 those may catch a signal and stop the program,
 where other implementations allow one to enter those characters in the buffer.
 .bP
 (e.g., \fB^C\fP or \fB^\e\fP).
 With the \fBnoraw\fP and \fBcbreak\fP settings,
 those may catch a signal and stop the program,
 where other implementations allow one to enter those characters in the buffer.
 .bP

-Starting in 2021 (ncurses 6.3), \fBgetnstr\fP sets \fBraw\fP,
+Starting in 2021
+(\fI\%ncurses\fP 6.3),
+\fBgetnstr\fP sets \fBraw\fP,

 rather than \fBnoraw\fP and \fBcbreak\fP for better compatibility with
 SVr4-curses, e.g., allowing one to enter a \fB^C\fP into the buffer.
 .SH SEE ALSO
 rather than \fBnoraw\fP and \fBcbreak\fP for better compatibility with
 SVr4-curses, e.g., allowing one to enter a \fB^C\fP into the buffer.
 .SH SEE ALSO

+\fB\%curs_get_wstr\fP(3X) describes comparable functions of the
+.I \%ncurses
+library in its wide-character configuration
+.RI ( \%ncursesw ).
+.PP

 \fB\%curses\fP(3X),
 \fB\%curs_getch\fP(3X),
 \fB\%curs_termattrs\fP(3X),
 \fB\%curses\fP(3X),
 \fB\%curs_getch\fP(3X),
 \fB\%curs_termattrs\fP(3X),