.\"***************************************************************************
-.\" Copyright (c) 1998-2017,2018 Free Software Foundation, Inc. *
+.\" 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 *
.\" copy of this software and associated documentation files (the *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_getstr.3x,v 1.26 2018/09/01 20:34:52 tom Exp $
-.TH curs_getstr 3X ""
-.ie \n(.g .ds `` \(lq
-.el .ds `` ``
-.ie \n(.g .ds '' \(rq
-.el .ds '' ''
+.\" $Id: curs_getstr.3x,v 1.56 2024/04/13 22:14:06 tom Exp $
+.TH curs_getstr 3X 2024-04-13 "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
..
-.na
-.hy 0
.SH NAME
-\fBgetstr\fR,
-\fBgetnstr\fR,
-\fBwgetstr\fR,
-\fBwgetnstr\fR,
-\fBmvgetstr\fR,
-\fBmvgetnstr\fR,
-\fBmvwgetstr\fR,
-\fBmvwgetnstr\fR \- accept character strings from \fBcurses\fR terminal keyboard
-.ad
-.hy
+\fB\%getstr\fP,
+\fB\%getnstr\fP,
+\fB\%wgetstr\fP,
+\fB\%wgetnstr\fP,
+\fB\%mvgetstr\fP,
+\fB\%mvgetnstr\fP,
+\fB\%mvwgetstr\fP,
+\fB\%mvwgetnstr\fP \-
+accept character strings from \fIcurses\fR terminal keyboard
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBint getstr(char *str);\fR
-.br
-\fBint getnstr(char *str, int n);\fR
-.br
-\fBint wgetstr(WINDOW *win, char *str);\fR
-.br
-\fBint wgetnstr(WINDOW *win, char *str, int n);\fR
-.br
-\fBint mvgetstr(int y, int x, char *str);\fR
-.br
-\fBint mvwgetstr(WINDOW *win, int y, int x, char *str);\fR
-.br
-\fBint mvgetnstr(int y, int x, char *str, int n);\fR
-.br
-\fBint mvwgetnstr(WINDOW *, int y, int x, char *str, int n);\fR
-.br
+.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 \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).
-.\" 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
-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
-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
-Characters input are echoed only if \fBecho\fR is currently on.
+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
+The \fIerase\fP character (e.g., \fB^H\fP) erases the character
+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
+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,
-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 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
-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
-if the window pointer is null, or
-if its timeout expires without having any data.
+.bP
+if the window pointer is null,
+.bP
+if its timeout expires without having any data, or
+.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
\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\fR, \fBmvgetstr\fR, and \fBmvwgetstr\fR may be macros.
+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 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\fR(3X) call returns an \fBERR\fP.
+or if the lower-level \fBwgetch\fP(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\*(''
(such as function keys,
\*(``home\*('' key,
\*(``clear\*('' key,
-\fIetc\fR.) are \*(``interpreted\*('',
+\fIetc\fP.) are \*(``interpreted\*('',
without giving details.
It lied.
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).
.PP
-The functions \fBgetnstr\fR, \fBmvgetnstr\fR, and \fBmvwgetnstr\fR were
+The functions \fBgetnstr\fP, \fBmvgetnstr\fP, and \fBmvwgetnstr\fP were
present but not documented in SVr4.
.PP
-X/Open Curses issue 5 (2007) stated that these functions
+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
+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
+\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,
+it also makes changes to the curses modes to allow simple editing of
+the input buffer:
+.bP
+\fBgetnstr\fP saves the current value of the \fBnl\fP, \fBecho\fP,
+\fBraw\fP and \fBcbreak\fP modes, and sets
+\fBnl\fP,
+\fBnoecho\fP,
+\fBnoraw\fP, and
+\fBcbreak\fP.
+.IP
+\fBgetnstr\fP handles the echoing of characters,
+rather than relying on the caller to set an appropriate mode.
+.bP
+It also obtains the \fIerase\fP and \fIkill\fP characters
+from \fBerasechar\fP and \fBkillchar\fP, respectively.
+.bP
+On return, \fBgetnstr\fP restores the modes to their previous values.
+.PP
+Other implementations differ in their treatment of special characters:
+.bP
+While they may set the \fIecho\fP mode,
+other implementations do not modify the \fIraw\fP mode,
+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
+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 \fI\%ncurses\fP.
+.IP
+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
+(\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
-\fBcurses\fR(3X),
-\fBcurs_getch\fR(3X),
-\fBcurs_variables\fR(3X).
+\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\%curs_variables\fP(3X)
projects / ncurses.git / blobdiff