X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_getstr.3x;h=4a1cc89173f77ef38b7826c93cac90ea6171c091;hp=74c690d2f97346612d7a036c9d0ccbfc1cd34258;hb=81304798ee736c467839c779c9ca5dca48db7bea;hpb=17c5992a16be94247b83f2bbb9accdd9b7e7bb72 diff --git a/man/curs_getstr.3x b/man/curs_getstr.3x index 74c690d2..4a1cc891 100644 --- a/man/curs_getstr.3x +++ b/man/curs_getstr.3x @@ -1,5 +1,6 @@ .\"*************************************************************************** -.\" Copyright (c) 1998-2017,2018 Free Software Foundation, Inc. * +.\" Copyright 2018-2020,2021 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 * @@ -26,12 +27,16 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_getstr.3x,v 1.24 2018/07/28 21:34:56 tom Exp $ +.\" $Id: curs_getstr.3x,v 1.33 2021/05/22 21:36:35 tom Exp $ .TH curs_getstr 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` .ie \n(.g .ds '' \(rq .el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. .na .hy 0 .SH NAME @@ -48,42 +53,56 @@ .SH SYNOPSIS \fB#include \fR .sp -\fBint getstr(char *str);\fR +\fBint getstr(char *\fP\fIstr\fP\fB);\fR .br -\fBint getnstr(char *str, int n);\fR +\fBint getnstr(char *\fP\fIstr\fP\fB, int \fP\fIn\fP\fB);\fR .br -\fBint wgetstr(WINDOW *win, char *str);\fR +\fBint wgetstr(WINDOW *\fP\fIwin\fP\fB, char *\fP\fIstr\fP\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 *\fP\fIwin\fP\fB, char *\fP\fIstr\fP\fB, int \fP\fIn\fP\fB);\fR +.sp +\fBint mvgetstr(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, char *\fP\fIstr\fP\fB);\fR .br -\fBint mvwgetstr(WINDOW *win, int y, int x, char *str);\fR +\fBint mvwgetstr(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, char *\fP\fIstr\fP\fB);\fR .br -\fBint mvgetnstr(int y, int x, char *str, int n);\fR +\fBint mvgetnstr(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, char *\fP\fIstr\fP\fB, int \fP\fIn\fP\fB);\fR .br -\fBint mvwgetnstr(WINDOW *, int y, int x, char *str, int n);\fR +\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);\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 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\fR, +followed by a NUL. +.PP +The \fBgetnstr\fR function reads +from the \fIstdscr\fR default window. +The other functions, such as \fBwgetnstr\fP, +read from the window given as a parameter. .PP -\fBwgetnstr\fR reads at most \fIn\fR characters, thus preventing a possible +\fBgetnstr\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 -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\fR and \fBKEY_BACKSPACE\fR +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. In that case, @@ -131,7 +150,97 @@ string by those implementations was predictable but not useful .PP The functions \fBgetnstr\fR, \fBmvgetnstr\fR, and \fBmvwgetnstr\fR were present but not documented in SVr4. +.PP +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 +\*(``read at most \fIn\fP\-1 bytes\*('' +to allow for the terminating NUL. +As of 2018, some implementations do, some do not count it: +.bP +ncurses 6.1 and PDCurses do not count the NUL in the given limit, while +.bP +Solaris SVr4 and NetBSD curses count the NUL as part of the limit. +.bP +Solaris xcurses provides both: +its wide-character \fBwget_nstr\fP reserves a NUL, +but its \fBwgetnstr\fP does not count the NUL consistently. +.PP +In SVr4 curses, +a negative value of \fIn\fP tells \fBwgetnstr\fP to assume that the +caller's buffer is large enough to hold the result, +i.e., to act like \fBwgetstr\fP. +X/Open Curses does not mention this +(or anything related to negative or zero values of \fIn\fP), +however most implementations +use the feature, with different limits: +.bP +Solaris SVr4 curses and PDCurses limit the result to 255 bytes. +Other Unix systems than Solaris are likely to use the same limit. +.bP +Solaris xcurses limits the result to \fBLINE_MAX\fP bytes. +.bP +NetBSD 7 assumes no particular limit for the result from \fBwgetstr\fP. +However, it limits the \fBwgetnstr\fP parameter \fIn\fP to ensure +that it is greater than zero. +.IP +A comment in NetBSD's source code states that this is specified in SUSv2. +.bP +ncurses (before 6.2) assumes no particular limit for the result +from \fBwgetstr\fP, and treats the \fIn\fP parameter of \fBwgetnstr\fP +like SVr4 curses. +.bP +ncurses 6.2 uses \fBLINE_MAX\fP, +or a larger (system-dependent) value +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 pcurses 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_termattrs\fR(3X), \fBcurs_variables\fR(3X).