X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=man%2Fcurs_getstr.3x;h=4a49352a146cdf6de9b3b1ca4ce1bee33f1def33;hb=HEAD;hp=b66480330a21098a5bfc94df053a5cb72f71c353;hpb=d1a029866f6d84087781eaa81de19949d8533426;p=ncurses.git diff --git a/man/curs_getstr.3x b/man/curs_getstr.3x index b6648033..27b9c951 100644 --- a/man/curs_getstr.3x +++ b/man/curs_getstr.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 2018-2023,2024 Thomas E. Dickey * .\" Copyright 1998-2010,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,47 +27,47 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_getstr.3x,v 1.42 2023/08/05 12:14:30 tom Exp $ -.TH curs_getstr 3X 2023-08-05 "ncurses 6.4" "Library calls" -.ie \n(.g .ds `` \(lq -.el .ds `` `` -.ie \n(.g .ds '' \(rq -.el .ds '' '' +.\" $Id: curs_getstr.3x,v 1.63 2024/06/01 22:29:08 tom Exp $ +.TH curs_getstr 3X 2024-06-01 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls" +.ie \n(.g \{\ +.ds `` \(lq +.ds '' \(rq +.\} +.el \{\ +.ie t .ds `` `` +.el .ds `` "" +.ie t .ds '' '' +.el .ds '' "" +.\} +. .de bP .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 \fP -.sp -\fBint getstr(char *\fIstr\fB);\fR -.br -\fBint getnstr(char *\fIstr\fB, int \fIn\fB);\fR -.br -\fBint wgetstr(WINDOW *\fIwin\fB, char *\fIstr\fB);\fR -.br -\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 *\fIwin\fB, int \fIy\fB, int \fIx\fB, char *\fIstr\fB);\fR -.br -\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 +.nf +\fB#include +.PP +\fBint getstr(char *\fIstr\fP); +\fBint getnstr(char *\fIstr\fP, int \fIn\fP); +\fBint wgetstr(WINDOW *\fIwin\fP, char *\fIstr\fP); +\fBint wgetnstr(WINDOW *\fIwin\fP, char *\fIstr\fP, int \fIn\fP); +.PP +\fBint mvgetstr(int \fIy\fP, int \fIx\fP, char *\fIstr\fP); +\fBint mvwgetstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, char *\fIstr\fP); +\fBint mvgetnstr(int \fIy\fP, int \fIx\fP, char *\fIstr\fP, int \fIn\fP); +\fBint mvwgetnstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, char *\fIstr\fP, int \fIn\fP); +.fi .SH DESCRIPTION The function \fBwgetnstr\fP @@ -127,27 +127,6 @@ 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 of these functions return the integer \fBOK\fP upon successful completion. (SVr4 specifies only \*(``an integer value other than \fBERR\fP\*('') @@ -156,7 +135,8 @@ If unsuccessful, they return \fBERR\fP. X/Open defines no error conditions. .PP In this implementation, -these functions return an error +these functions return +.B ERR .bP if the window pointer is null, .bP @@ -170,9 +150,32 @@ 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. +Functions prefixed with \*(``mv\*('' first perform cursor movement and +fail if the position +.RI ( y , +.IR x ) +is outside the window boundaries. +.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 PORTABILITY These functions are described in The Single Unix Specification, Version 2. No error conditions are defined. @@ -197,13 +200,13 @@ 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. +but did not state whether the terminating NUL counted toward 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 count it, some do not: .bP -ncurses 6.1 and PDCurses do not count the NUL in the given limit, while +\fI\%ncurses\fP 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 @@ -231,15 +234,15 @@ 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 +\fI\%ncurses\fP (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, +\fI\%ncurses\fP 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). +\fI\%ncurses\fP 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, @@ -269,22 +272,31 @@ 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. +The original \fI\%ncurses\fP +(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. +it is not necessary with \fI\%ncurses\fP. .IP -Since 1995, ncurses has provided signal handlers for INTR and QUIT -(e.g., \fB^C\fP or \fB^\\\fP). +Since 1995, +\fI\%ncurses\fP has provided signal handlers for INTR and QUIT +(e.g., \fB^C\fP or \fB^\e\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, +Starting in 2021 +(\fI\%ncurses\fP 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\fP(3X), -\fBcurs_getch\fP(3X), -\fBcurs_termattrs\fP(3X), -\fBcurs_variables\fP(3X). +\fB\%curs_get_wstr\fP(3X) describes comparable functions of the +.I \%ncurses +library in its wide-character configuration +.RI \%( ncursesw ). +.PP +\fB\%curses\fP(3X), +\fB\%curs_getch\fP(3X), +\fB\%curs_termattrs\fP(3X), +\fB\%curs_variables\fP(3X)