.\"***************************************************************************
-.\" Copyright (c) 1998,2000 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2017,2018 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.9 2000/07/01 17:39:31 tom Exp $
+.\" $Id: curs_getstr.3x,v 1.24 2018/07/28 21:34:56 tom Exp $
.TH curs_getstr 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
+.na
+.hy 0
.SH NAME
\fBgetstr\fR,
\fBgetnstr\fR,
\fBmvgetstr\fR,
\fBmvgetnstr\fR,
\fBmvwgetstr\fR,
-\fBmvwgetnstr\fR - accept character strings from \fBcurses\fR terminal keyboard
+\fBmvwgetnstr\fR \- accept character strings from \fBcurses\fR terminal keyboard
+.ad
+.hy
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
+.sp
\fBint getstr(char *str);\fR
.br
\fBint getnstr(char *str, int n);\fR
.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). The resulting value is placed in the
+not included in the returned string).
+The resulting value is placed in the
area pointed to by the character pointer \fIstr\fR.
-
+.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
+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.
-
-The user's erase and kill characters are interpreted. If keypad
+.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.
-
-Characters input are echoed only if \fBecho\fR is currently on. In that case,
+.PP
+Characters input are echoed only if \fBecho\fR 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
+specifies only \*(``an integer value other than \fBERR\fR\*('') upon successful
completion.
+.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.
+.PP
+This implementation provides an extension as well.
+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.
.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 \fBERR\fP if the window pointer is null,
+or if the lower-level \fBwgetch\fR(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" without
-giving details. It lied. In fact, the `character' value appended to the
+the SVr4.0 documentation claimed that \*(``special keys\*(''
+(such as function 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).
-
+.PP
The functions \fBgetnstr\fR, \fBmvgetnstr\fR, and \fBmvwgetnstr\fR were
present but not documented in SVr4.
.SH SEE ALSO
-\fBcurses\fR(3X), \fBcurs_getch\fR(3X).
-.\"#
-.\"# The following sets edit modes for GNU EMACS
-.\"# Local Variables:
-.\"# mode:nroff
-.\"# fill-column:79
-.\"# End:
+\fBcurses\fR(3X),
+\fBcurs_getch\fR(3X),
+\fBcurs_variables\fR(3X).
projects / ncurses.git / blobdiff