.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2002,2003 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.7 1998/03/11 21:12:53 juergen Exp $
+.\" $Id: curs_getstr.3x,v 1.12 2003/05/10 20:33:49 jmc Exp $
.TH curs_getstr 3X ""
.SH NAME
-\fBgetstr\fR, \fBwgetstr\fR, \fBmvgetstr\fR,
-\fBmvwgetstr\fR, \fBwgetnstr\fR - accept character strings from
-\fBcurses\fR terminal keyboard
+\fBgetstr\fR,
+\fBgetnstr\fR,
+\fBwgetstr\fR,
+\fBwgetnstr\fR,
+\fBmvgetstr\fR,
+\fBmvgetnstr\fR,
+\fBmvwgetstr\fR,
+\fBmvwgetnstr\fR - accept character strings from \fBcurses\fR terminal keyboard
.SH SYNOPSIS
\fB#include <curses.h>\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 mvwgetnstr(WINDOW *, int y, int x, char *str, int n);\fR
.br
-\fBint wgetnstr(WINDOW *win, char *str, int n);\fR
-.br
.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
.SH NOTES
Note that \fBgetstr\fR, \fBmvgetstr\fR, and \fBmvwgetstr\fR may be macros.
.SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4. They read
-single-byte characters only. The standard specifies that they return \fBERR\fR
-on failure, but the single error condition \fBEOVERFLOW\fR associated with
-extended-level conformance is not yet returned (the XSI curses support for
-multi-byte characters is not yet present).
+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 ERR if the window pointer is null,
+or if the lower-level \fBwgetch\fR call returns an ERR.
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" without
+keys, "home" key, "clear" key, \fIetc\fR.) 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).