bug-ncurses
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[PATCH 044/177] man/curs_get_wstr.3x: Align with man/curs_getstr.3x.


From: G. Branden Robinson
Subject: [PATCH 044/177] man/curs_get_wstr.3x: Align with man/curs_getstr.3x.
Date: Mon, 13 Jan 2025 11:21:30 -0600

* Define `ha` string in document preamble; we'll need it.
* Parallelize "DESCRIPTION", "RETURN VALUE", "NOTES", and "PORTABILITY"
  sections, where applicable, with getstr(3X).

* man/man_db.renames.in: Add getstr.3x.
* man/manhtml.aliases: Add getstr(3X).
---
 man/curs_get_wstr.3x  | 345 ++++++++++++++++++++++++++++--------------
 man/man_db.renames.in |   1 +
 man/manhtml.aliases   |   1 +
 3 files changed, 232 insertions(+), 115 deletions(-)

diff --git a/man/curs_get_wstr.3x b/man/curs_get_wstr.3x
index 3cc1d0cfa..08d3f3c20 100644
--- a/man/curs_get_wstr.3x
+++ b/man/curs_get_wstr.3x
@@ -32,12 +32,14 @@
 .ie \n(.g \{\
 .ds `` \(lq
 .ds '' \(rq
+.ds ^  \(ha
 .\}
 .el \{\
 .ie t .ds `` ``
 .el   .ds `` ""
 .ie t .ds '' ''
 .el   .ds '' ""
+.ds       ^  ^
 .\}
 .
 .de bP
@@ -70,84 +72,103 @@ .SH SYNOPSIS
       int \fIn\fP);
 .fi
 .SH DESCRIPTION
+.B \%wget_wstr
+populates a user-supplied wide-character string buffer
+.I wstr
+by repeatedly calling \fBwget_wch\fP(3X)
+with the
+.I win
+argument
+until a line feed or carriage return character is input.
 The function
-\fBwgetn_wstr\fP
-is equivalent to a series of calls to
-\fBwget_wch\fP(3X)
-until a newline or carriage return terminates the series:
 .bP
-The terminating character is not included in the returned string.
+does not copy the terminating character to
+.IR wstr ";"
 .bP
-An end-of-file condition is represented by \fBWEOF\fP,
-as defined in \fB<wchar.h>\fP.
+populates
+.I wstr
+with
+.I WEOF
+(as defined in
+.IR \%wchar.h )
+if an end-of-file condition occurs on the input;
 .bP
-In all instances, the end of the string is terminated
-by a null \fBwchar_t\fP.
+always terminates the string with a null wide character
+(after any
+.IR WEOF );
 .bP
-The function stores the result in the area pointed to
-by the \fIwstr\fP parameter.
+interprets the screen's erase and kill characters
+(see \fB\%erasechar\fP(3X) and \fB\%killchar\fP(3X));
 .bP
-The function reads at most \fIn\fP characters,
-thus preventing a possible overflow of the input buffer.
-.IP
-Any attempt to enter more characters
-(other than the terminating newline or carriage return)
-causes a beep.
-.IP
-Function keys also cause a beep and are ignored.
+recognizes function keys only if the screen's keypad option is enabled
+(see \fB\%keypad\fP(3X));
+.bP
+treats the function keys
+.B \%KEY_LEFT
+and
+.B \%KEY_BACKSPACE
+the same as the erase character;
+and
+.bP
+discards function key inputs other than those treated as the erase
+character,
+calling \fBbeep\fP(3X).
 .PP
-The user's \fIerase\fP and \fIkill\fP characters are interpreted:
+The erase character replaces the character at the end of the buffer with
+a null wide character,
+while the kill character does the same for the entire buffer.
+.PP
+If the screen's echo option is enabled
+(see \fBecho\fP(3X)),
+.B \%wget_wstr
+updates
+.I win
+with \fB\%wadd_wch\fP(3X).
+Further,
 .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 \fIerase\fP 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\fP is currently on.
-In that case,
-backspace is echoed as deletion of the previous character
-(typically a left motion).
-.PP
-The
-\fBgetn_wstr\fP,
-\fBmvgetn_wstr\fP,
-\fBmvwgetn_wstr\fP, and
-\fBwgetn_wstr\fP
-functions are identical
-to the
-\fBget_wstr\fP,
-\fBmvget_wstr\fP,
-\fBmvwget_wstr\fP, and
-\fBwget_wstr\fP
-functions, respectively,
-except that the
-\fB*n_*\fP
-versions read at most
-\fIn\fP
-characters, letting the application prevent overflow of the
-input buffer.
-.SH RETURN VALUE
-All of these functions return the integer \fBOK\fP upon successful completion.
-If unsuccessful, they return \fBERR\fP.
+the erase character
+and its function key synonyms
+move the cursor to the left,
+and
+.bP
+the kill character returns the cursor to where it was located when
+.B \%wget_wstr
+was called.
 .PP
-X/Open defines no error conditions.
+.B \%wgetn_wstr
+is similar,
+but reads at most
+.I n
+wide characters,
+aiding the application to avoid overrunning the buffer to which
+.I wstr
+points.
+An attempt to input more than
+.I n
+wide characters
+(other than the terminating line feed or carriage return)
+is ignored with a beep.
 .PP
-In this implementation,
-these functions return
+\fB\%ncurses\fP(3X) describes the variants of these functions.
+.SH RETURN VALUE
+These functions return
+.B OK
+on success and
 .B ERR
+on failure.
+.PP
+In
+.IR \%ncurses ","
+they return
+.B ERR
+if
 .bP
-if the window pointer is null,
-.bP
-if its timeout expires without having any data, or
+.I win
+is
+.IR NULL ","
+or
 .bP
-if the associated call to
-\fBwget_wch\fP
-failed.
+if an internal \fB\%wget_wch\fP(3X) call fails.
 .PP
 Functions prefixed with \*(``mv\*('' first perform cursor movement and
 fail if the position
@@ -155,74 +176,168 @@ .SH RETURN VALUE
 .IR x )
 is outside the window boundaries.
 .SH NOTES
-Any of these functions other than
-\fBwgetn_wstr\fP
-may be macros.
-.PP
-Using
-\fBget_wstr\fP,
-\fBmvget_wstr\fP,
-\fBmvwget_wstr\fP, or
-\fBwget_wstr\fP
-to read a line that
-overflows the array pointed to by
-\fBwstr\fP
-causes undefined
-results.
-The use of
-\fBgetn_wstr\fP,
-\fBmvgetn_wstr\fP,
-\fBmvwgetn_wstr\fP, or
-\fBwgetn_wstr\fP,
-respectively, is recommended.
-.PP
-These functions cannot return \fBKEY_\fP values because there
-is no way to distinguish a \fBKEY_\fP value from a valid \fBwchar_t\fP value.
+All of these functions except
+.B \%wgetn_wstr
+may be implemented as macros.
+.PP
+Reading input that overruns the buffer pointed to by
+.I wstr
+causes undefined results.
+Use the
+.BR n -infixed
+functions,
+and allocate sufficient storage for
+.I wstr
+\(em at least
+.IR n +1
+times
+.BR sizeof(wchar_t) "."
+.PP
+These functions cannot store a
+.B KEY_
+value in
+.I wstr
+because there is no way to distinguish it
+from a valid
+.I \%wchar_t
+value.
+.PP
+While these functions conceptually implement
+a series of calls to
+.BR \%wget_wch ","
+they also temporarily change properties of the
+.I curses
+screen to permit simple editing of the input buffer.
+Each function saves the screen's state,
+calls \fBnl\fP(3X),
+and,
+if the screen was in canonical (\*(``cooked\*('') mode,
+\fB\%cbreak\fP(3X).
+Before returning,
+it restores the saved screen state.
+Other implementations differ in detail,
+affecting which control characters they can accept in the buffer;
+see section \*(``PORTABILITY\*('' below.
+.PP
+Unlike \fBgetstr\fP(3X) and related functions of
+.IR \%ncurses 's
+non-wide API,
+these functions do not return
+.B \%KEY_RESIZE
+if a
+.I \%SIGWINCH
+event interrupts the function.
 .SH PORTABILITY
 X/Open Curses Issue\ 4 describes these functions.
 It specifies no error conditions for them.
 .PP
-This implementation returns \fBERR\fP if the window pointer is null,
-or if the lower-level \fBwget_wch\fP call returns an \fBERR\fP.
-In the latter case,
-an \fBERR\fP return without other data is treated as an end-of-file condition,
-and the returned array contains a \fBWEOF\fP followed by a null \fBwchar_t\fP.
-.PP
-X/Open curses documented these functions to pass an array of \fBwchar_t\fP
-in 1997, but that was an error because of this part of the description:
+Issue\ 4 documented these functions as passing an array of
+.IR wchar_t ","
+but that was an error,
+conflicting with the following language in the standard.
 .RS
 .PP
-The effect of \fBget_wstr\fP is as though a series of calls to
-\fBget_wch\fP were made, until a newline character, end-of-line character, or
-end-of-file character is processed.
+The effect of
+.IR \%get_wstr "()"
+is as though a series of calls to
+.IR \%get_wch "()"
+were made,
+until a newline character,
+end-of-line character,
+or end-of-file character is processed.
+.\" X/Open Curses Issue 4, Version 2, p. 96.
 .RE
 .PP
-The latter function \fIget_wch\fP can return a negative value,
-while \fBwchar_t\fP is a unsigned type.
-All of the vendors implement this using \fBwint_t\fP, following the standard.
+.I \%get_wch
+can return a negative value
+.RI ( WEOF ),
+but
+.I \%wchar_t
+is a unsigned type.
+All of the vendors implement these functions using
+.IR \%wint_t ","
+following the Issue\ 7 standard.
 .PP
-X/Open Curses Issue\ 7 (2009) is unclear regarding whether
-the terminating \fInull \fBwchar_t\fR
-value is counted in the length parameter \fIn\fP.
-X/Open Curses Issue\ 7 revised the corresponding description
-of \fBwgetnstr\fP to address this issue.
-The unrevised description of \fBwget_nwstr\fP can be interpreted either way.
-This implementation counts the terminator in the length.
+X/Open Curses Issue\ 7 is unclear whether the terminating null wide character
+counts toward the length paramter
+.IR n "."
+A similar issue affected
+.I \%wgetnstr
+in Issue\ 4,
+Version\ 2;
+Issue\ 7 revised that function's description to address the issue,
+but not that of
+.IR \%wget_nwstr ","
+leaving it ambiguous.
+.I \%ncurses
+counts the terminator in the length.
 .PP
-X/Open Curses does not specify what happens if the length \fIn\fP is negative.
+X/Open Curses does not specify what happens if the length
+.I n
+is negative.
 .bP
-For analogy with \fBwgetnstr\fP,
-\fI\%ncurses\fP 6.2 uses a limit (based on \fBLINE_MAX\fP).
+For consistency with
+.IR \%wgetnstr ","
+.I \%ncurses
+6.2 uses a limit based on
+.I LINE_MAX
+(see
+.IR sysconf (3)).
 .bP
 Some other implementations (such as Solaris
 .IR xcurses )
 do the same,
 while others
 .RI \%( PDCurses )
-do not allow this.
+do not permit a negative
+.IR n "."
 .bP
-NetBSD\ 7 curses imitates \fI\%ncurses\fP 6.1 in this regard,
-treating a \fB\-1\fP as an indefinite number of characters.
+NetBSD\ 7
+.I curses
+imitates
+.I \%ncurses
+6.1 in this regard,
+treating
+.B \-1
+as an unbounded count of wide characters.
+.PP
+Implementations vary in their handling of input control characters.
+.bP
+While they may enable the screen's echo option,
+some do not take it out of raw mode,
+and may take cbreak mode into account
+when deciding whether to handle echoing within
+.I \%wgetn_wstr
+or to rely on it as a side effect of calling
+.IR \%wget_wch "."
+.IP
+Since 1995,
+.I \%ncurses
+has provided handlers for
+.I SIGINTR
+and
+.I SIGQUIT
+events,
+which are typically generated at the keyboard with
+.B \*^C
+and
+.B \*^\e
+respectively.
+In cbreak mode,
+those handlers catch a signal and stop the program,
+whereas other implementations write those characters into the buffer.
+.bP
+Starting with
+.I \%ncurses
+6.3 (2021),
+.I \%wgetn_wstr
+preserves raw mode if the screen was already in that state,
+allowing one to enter the characters the terminal interprets
+as interrupt and quit events
+into the buffer,
+for consistency with SVr4
+.IR curses 's
+.IR \%wgetnstr .
 .SH SEE ALSO
 \fB\%curs_getstr\fP(3X) describes comparable functions of the
 .I \%ncurses
diff --git a/man/man_db.renames.in b/man/man_db.renames.in
index 5966ff7e4..1e7d367a7 100644
--- a/man/man_db.renames.in
+++ b/man/man_db.renames.in
@@ -205,6 +205,7 @@ get_wch.3x                  get_wch.3ncurses
 getattr.3x                     getattr.3ncurses
 getcchar.3x                    getcchar.3ncurses
 getch.3x                       getch.3ncurses
+getstr.3x                      getstr.3ncurses
 getwin.3x                      getwin.3ncurses
 getyx.3x                       getyx.3ncurses
 halfdelay.3x                   halfdelay.3ncurses
diff --git a/man/manhtml.aliases b/man/manhtml.aliases
index 9c493173e..2f865bdd8 100644
--- a/man/manhtml.aliases
+++ b/man/manhtml.aliases
@@ -60,6 +60,7 @@ flushinp(3X)          curs_util(3X)
 get_wch(3X)            curs_get_wch(3X)
 getcchar(3X)           curs_getcchar(3X)
 getch(3X)              curs_getch(3X)
+getstr(3X)             curs_getstr(3X)
 getwin(3X)             curs_util(3X)
 getyx(3X)              curs_getyx(3X)
 halfdelay(3X)          curs_inopts(3X)
-- 
2.30.2

Attachment: signature.asc
Description: PGP signature


reply via email to

[Prev in Thread] Current Thread [Next in Thread]