.\"***************************************************************************
-.\" Copyright 2018-2020,2021 Thomas E. Dickey *
+.\" Copyright 2018-2022,2023 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.35 2021/12/25 20:14:56 tom Exp $
-.TH curs_getstr 3X ""
+.\" $Id: curs_getstr.3x,v 1.46 2023/09/16 23:34:43 tom Exp $
+.TH curs_getstr 3X 2023-09-16 "ncurses 6.4" "Library calls"
.ie \n(.g .ds `` \(lq
.el .ds `` ``
.ie \n(.g .ds '' \(rq
.ie n .IP \(bu 4
.el .IP \(bu 2
..
-.na
-.hy 0
.SH NAME
-\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
+\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>\fP
.sp
-\fBint getstr(char *\fP\fIstr\fP\fB);\fP
+\fBint getstr(char *\fIstr\fB);\fR
.br
-\fBint getnstr(char *\fP\fIstr\fP\fB, int \fP\fIn\fP\fB);\fP
+\fBint getnstr(char *\fIstr\fB, int \fIn\fB);\fR
.br
-\fBint wgetstr(WINDOW *\fP\fIwin\fP\fB, char *\fP\fIstr\fP\fB);\fP
+\fBint wgetstr(WINDOW *\fIwin\fB, char *\fIstr\fB);\fR
.br
-\fBint wgetnstr(WINDOW *\fP\fIwin\fP\fB, char *\fP\fIstr\fP\fB, int \fP\fIn\fP\fB);\fP
+\fBint wgetnstr(WINDOW *\fIwin\fB, char *\fIstr\fB, int \fIn\fB);\fR
.sp
-\fBint mvgetstr(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, char *\fP\fIstr\fP\fB);\fP
-.br
-\fBint mvwgetstr(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, char *\fP\fIstr\fP\fB);\fP
+\fBint mvgetstr(int \fIy\fB, int \fIx\fB, char *\fIstr\fB);\fR
.br
-\fBint mvgetnstr(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, char *\fP\fIstr\fP\fB, int \fP\fIn\fP\fB);\fP
+\fBint mvwgetstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, char *\fIstr\fB);\fR
.br
-\fBint mvwgetnstr(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, char *\fP\fIstr\fP\fB, int \fP\fIn\fP\fB);\fP
+\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
.SH DESCRIPTION
-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\fP,
-followed by a NUL.
-.PP
-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 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
.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.
+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 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 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.
+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
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.
-.SH NOTES
-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.
+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\fP(3X) call returns an \fBERR\fP.
.PP
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
.bP
projects / ncurses.git / blobdiff