.\"***************************************************************************
-.\" 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 *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_getstr.3x,v 1.48 2023/09/30 21:38:11 tom Exp $
-.TH curs_getstr 3X 2023-09-30 "ncurses 6.4" "Library calls"
-.ie \n(.g .ds `` \(lq
-.el .ds `` ``
-.ie \n(.g .ds '' \(rq
-.el .ds '' ''
+.\" $Id: curs_getstr.3x,v 1.58 2024/04/20 19:18:18 tom Exp $
+.TH curs_getstr 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
.ie n .IP \(bu 4
.el .IP \(bu 2
\fB\%mvwgetnstr\fP \-
accept character strings from \fIcurses\fR terminal keyboard
.SH SYNOPSIS
-\fB#include <curses.h>\fP
-.sp
-\fBint getstr(char *\fIstr\fB);\fR
-.br
-\fBint getnstr(char *\fIstr\fB, int \fIn\fB);\fR
-.br
-\fBint wgetstr(WINDOW *\fIwin\fB, char *\fIstr\fB);\fR
-.br
-\fBint wgetnstr(WINDOW *\fIwin\fB, char *\fIstr\fB, int \fIn\fB);\fR
-.sp
-\fBint mvgetstr(int \fIy\fB, int \fIx\fB, char *\fIstr\fB);\fR
-.br
-\fBint mvwgetstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, char *\fIstr\fB);\fR
-.br
-\fBint mvgetnstr(int \fIy\fB, int \fIx\fB, char *\fIstr\fB, int \fIn\fB);\fR
-.br
-\fBint mvwgetnstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, char *\fIstr\fB, int \fIn\fB);\fR
+.nf
+\fB#include <curses.h>
+.PP
+\fBint getstr(char *\fIstr\fP);
+\fBint getnstr(char *\fIstr\fP, int \fIn\fP);
+\fBint wgetstr(WINDOW *\fIwin\fP, char *\fIstr\fP);
+\fBint wgetnstr(WINDOW *\fIwin\fP, char *\fIstr\fP, int \fIn\fP);
+.PP
+\fBint mvgetstr(int \fIy\fP, int \fIx\fP, char *\fIstr\fP);
+\fBint mvwgetstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, char *\fIstr\fP);
+\fBint mvgetnstr(int \fIy\fP, int \fIx\fP, char *\fIstr\fP, int \fIn\fP);
+\fBint mvwgetnstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, char *\fIstr\fP, int \fIn\fP);
+.fi
.SH DESCRIPTION
The function
\fBwgetnstr\fP
\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
All of these functions return the integer \fBOK\fP upon successful completion.
(SVr4 specifies only \*(``an integer value other than \fBERR\fP\*('')
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
+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 PORTABILITY
These functions are described in The Single Unix Specification, Version 2.
No error conditions are defined.
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
.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
-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,
-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,
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;
-it is not necessary with ncurses.
+it is not necessary with \fI\%ncurses\fP.
.IP
-Since 1995, ncurses has provided signal handlers for INTR and QUIT
-(e.g., \fB^C\fP or \fB^\\\fP).
+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
-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
+\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),
projects / ncurses.git / blobdiff