.\"***************************************************************************
-.\" Copyright (c) 1998-2017,2018 Free Software Foundation, Inc. *
+.\" Copyright 2018-2021,2022 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 $
+.\" $Id: curs_getstr.3x,v 1.36 2022/02/12 20:07:29 tom Exp $
.TH curs_getstr 3X ""
.ie \n(.g .ds `` \(lq
.el .ds `` ``
.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
+\fBgetstr\fP,
+\fBgetnstr\fP,
+\fBwgetstr\fP,
+\fBwgetnstr\fP,
+\fBmvgetstr\fP,
+\fBmvgetnstr\fP,
+\fBmvwgetstr\fP,
+\fBmvwgetnstr\fP \- accept character strings from \fBcurses\fP terminal keyboard
.ad
.hy
.SH SYNOPSIS
-\fB#include <curses.h>\fR
+\fB#include <curses.h>\fP
.sp
-\fBint getstr(char *str);\fR
+\fBint getstr(char *\fIstr\fB);\fR
.br
-\fBint getnstr(char *str, int n);\fR
+\fBint getnstr(char *\fIstr\fB, int \fIn\fB);\fR
.br
-\fBint wgetstr(WINDOW *win, char *str);\fR
+\fBint wgetstr(WINDOW *\fIwin\fB, char *\fIstr\fB);\fR
.br
-\fBint wgetnstr(WINDOW *win, char *str, int n);\fR
-.br
-\fBint mvgetstr(int y, int x, char *str);\fR
+\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 *win, int y, int x, char *str);\fR
+\fBint mvwgetstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, char *\fIstr\fB);\fR
.br
-\fBint mvgetnstr(int y, int x, char *str, int n);\fR
+\fBint mvgetnstr(int \fIy\fB, int \fIx\fB, char *\fIstr\fB, int \fIn\fB);\fR
.br
-\fBint mvwgetnstr(WINDOW *, int y, int x, char *str, int n);\fR
+\fBint mvwgetnstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, char *\fIstr\fB, int \fIn\fB);\fR
.br
.SH DESCRIPTION
-The function \fBgetstr\fR is equivalent to a series of calls to \fBgetch\fR,
+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\fR,
+area pointed to by the character pointer \fIstr\fP,
followed by a NUL.
.PP
-\fBwgetnstr\fR reads at most \fIn\fR characters, thus preventing a possible
+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 \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.
+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 erase 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\fR is currently on.
+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).
.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
+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.
.PP
X/Open defines no error conditions.
\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.
+Note that \fBgetstr\fP, \fBmvgetstr\fP, and \fBmvwgetstr\fP may be macros.
.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.
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:
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.
+.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 ncurses (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.
+.IP
+Since 1995, ncurses has provided signal handlers for INTR and QUIT
+(e.g., \fB^C\fP or \fB^\\\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,
+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).
+\fBcurses\fP(3X),
+\fBcurs_getch\fP(3X),
+\fBcurs_termattrs\fP(3X),
+\fBcurs_variables\fP(3X).
projects / ncurses.git / blobdiff