ncurses 6.5 - patch 20240511

[ncurses.git] / man / curs_addchstr.3x

diff --git a/man/curs_addchstr.3x b/man/curs_addchstr.3x
index fd5600dd2e1eabb22c78162bfb43e050aad88258..19c47fc59ff91e961d1a318fea3c8e72448216eb 100644 (file)
--- a/man/curs_addchstr.3x
+++ b/man/curs_addchstr.3x
@@ -1,55 +1,150 @@
-.TH curs_addchstr 3X ""
+.\"***************************************************************************
+.\" Copyright 2019-2023,2024 Thomas E. Dickey                                *
+.\" Copyright 1998-2012,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            *
+.\" "Software"), to deal in the Software without restriction, including      *
+.\" without limitation the rights to use, copy, modify, merge, publish,      *
+.\" distribute, distribute with modifications, sublicense, and/or sell       *
+.\" copies of the Software, and to permit persons to whom the Software is    *
+.\" furnished to do so, subject to the following conditions:                 *
+.\"                                                                          *
+.\" The above copyright notice and this permission notice shall be included  *
+.\" in all copies or substantial portions of the Software.                   *
+.\"                                                                          *
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
+.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
+.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
+.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
+.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
+.\"                                                                          *
+.\" Except as contained in this notice, the name(s) of the above copyright   *
+.\" holders shall not be used in advertising or otherwise to promote the     *
+.\" sale, use or other dealings in this Software without prior written       *
+.\" authorization.                                                           *
+.\"***************************************************************************
+.\"
+.\" $Id: curs_addchstr.3x,v 1.46 2024/05/11 20:39:53 tom Exp $
+.TH curs_addchstr 3X 2024-05-11 "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
+..

 .SH NAME
 .SH NAME

-\fBaddchstr\fR, \fBaddchnstr\fR, \fBwaddchstr\fR,
-\fBwaddchnstr\fR, \fBmvaddchstr\fR, \fBmvaddchnstr\fR, \fBmvwaddchstr\fR,
-\fBmvwaddchnstr\fR - add a string of characters (and attributes) to a
-\fBcurses\fR window
+\fB\%addchstr\fP,
+\fB\%addchnstr\fP,
+\fB\%waddchstr\fP,
+\fB\%waddchnstr\fP,
+\fB\%mvaddchstr\fP,
+\fB\%mvaddchnstr\fP,
+\fB\%mvwaddchstr\fP,
+\fB\%mvwaddchnstr\fP \-
+add a \fIcurses\fR character string to a window

 .SH SYNOPSIS
 .SH SYNOPSIS

-\fB#include <curses.h>\fR
-
-\fBint addchstr(const chtype *chstr);\fR
-.br
-\fBint addchnstr(const chtype *chstr, int n);\fR
-.br
-\fBint waddchstr(WINDOW *win, const chtype *chstr);\fR
-.br
-\fBint waddchnstr(WINDOW *win, const chtype *chstr, int n);\fR
-.br
-\fBint mvaddchstr(int y, int x, const chtype *chstr);\fR
-.br
-\fBint mvaddchnstr(int y, int x, const chtype *chstr, int n);\fR
-.br
-\fBint mvwaddchstr(WINDOW *win, int y, int x, const chtype *chstr);\fR
-.br
-\fBint mvwaddchnstr(WINDOW *win, int y, int x, const chtype *chstr, int n);\fR
+.nf
+\fB#include <curses.h>
+.PP
+\fBint addchstr(const chtype *\fIchstr\fP);
+\fBint waddchstr(WINDOW *\fIwin\fP, const chtype *\fIchstr\fP);
+\fBint mvaddchstr(int \fIy\fP, int \fIx\fP, const chtype *\fIchstr\fP);
+\fBint mvwaddchstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const chtype *\fIchstr\fP);
+.PP
+\fBint addchnstr(const chtype *\fIchstr\fP, int \fIn\fP);
+\fBint waddchnstr(WINDOW *\fIwin\fP, const chtype *\fIchstr\fP, int \fIn\fP);
+\fBint mvaddchnstr(int \fIy\fP, int \fIx\fP, const chtype *\fIchstr\fP, int \fIn\fP);
+\fBint mvwaddchnstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const chtype *\fIchstr\fP, int \fIn\fP);
+.fi

 .SH DESCRIPTION
 .SH DESCRIPTION

-These routines copy \fIchstr\fR into the window image structure at and after
-the current cursor position.  The four routines with \fIn\fR as the last
-argument copy at most \fIn\fR elements, but no more than will fit on the line.
-If \fBn\fR=\fB-1\fR then the whole string is copied, to the maximum number of
-characters that will fit on the line.
-
-The window cursor is \fInot\fR advanced, and these routines work faster than
-\fBwaddnstr\fR.  On the other hand, they don't perform any kind of checking
-(such as for the newline, backspace, or carriage return characters), they don't
-advance the current cursor position, they don't expand other control characters
-to ^-escapes, and they truncate the string if it crosses the right margin,
-rather then wrapping it around to the new line.
-
-.SH RETURN VALUES
-All routines return the integer \fBERR\fR upon failure and \fBOK\fR on success
-(the SVr4 manuals specify only "an integer value other than \fBERR\fR") upon
-successful completion, unless otherwise noted in the preceding routine
-descriptions.
+.B \%waddchstr
+copies the string of
+.I curses
+characters
+.I \%chstr
+to the window
+.IR win "."
+A null
+.I curses
+character terminates the string.
+.B \%waddchnstr
+does the same,
+but copies at most
+.I n
+characters,
+or as many as possible if
+.I n
+is
+.BR \-1 "."
+\fB\%ncurses\fP(3X) describes the variants of these functions.
+.PP
+Because these functions do not call \fB\%waddch\fP(3X) internally,
+they are faster than \fB\%waddstr\fP(3X) and \fB\%waddnstr\fP(3X).
+On the other hand,
+they
+.bP
+do not treat the backspace,
+carriage return,
+or line feed characters specially;
+.bP
+do not represent unprintable characters with \fB\%unctrl\fP(3X);
+.bP
+do not update the cursor position to follow the last character written;
+.bP
+truncate the string at the window's right margin,
+rather than wrapping it to the next line and potentially scrolling.
+.SH RETURN VALUE
+These functions return
+.B OK
+on success and
+.B ERR
+on failure.
+.PP
+X/Open Curses does not specify any error conditions.
+.I \%ncurses
+returns
+.B ERR
+if
+.bP
+.I win
+is
+.B NULL
+or
+.bP
+.I chstr
+is
+.BR NULL "."
+.PP
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.

 .SH NOTES
 .SH NOTES

-Note that all routines except \fBwaddchnstr\fR may be macros.
+All of these functions except
+.B \%waddchnstr
+may be implemented as macros.

 .SH PORTABILITY
 .SH PORTABILITY

-All these entry points are described in the XSI Curses standard, Issue 4.
+X/Open Curses,
+Issue 4 describes these functions.

 .SH SEE ALSO
 .SH SEE ALSO

-\fBcurses\fR(3X).
-.\"#
-.\"# The following sets edit modes for GNU EMACS
-.\"# Local Variables:
-.\"# mode:nroff
-.\"# fill-column:79
-.\"# End:
+\fB\%curs_add_wchstr\fP(3X) describes comparable functions of the
+.I \%ncurses
+library in its wide-character configuration
+.RI ( \%ncursesw ).
+.PP
+\fB\%curses\fP(3X),
+\fB\%curs_addch\fP(3X),
+\fB\%curs_addstr\fP(3X)