X-Git-Url: http://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=man%2Fcurs_getstr.3x;h=80a1c1ab80d20a6c3a6030d98b4986bd415d0959;hb=3183ac61c6bf0a75ee65dc8cbebf54f7c143df46;hp=d9bed5958976a9ba009629519844dae38261614d;hpb=47d2fb4537d9ad5bb14f4810561a327930ca4280;p=ncurses.git diff --git a/man/curs_getstr.3x b/man/curs_getstr.3x index d9bed595..80a1c1ab 100644 --- a/man/curs_getstr.3x +++ b/man/curs_getstr.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018-2019,2020 Thomas E. Dickey * +.\" 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 * @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_getstr.3x,v 1.29 2020/02/02 23:34:34 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 `` `` @@ -40,67 +40,77 @@ .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 \fR +\fB#include \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. @@ -118,27 +128,27 @@ 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. +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 @@ -187,7 +197,50 @@ 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). 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).