]> ncurses.scripts.mit.edu Git - ncurses.git/blobdiff - man/curs_insstr.3x
projects / ncurses.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
ncurses 6.5 - patch 20240511
[ncurses.git] / man / curs_insstr.3x
diff --git a/man/curs_insstr.3x b/man/curs_insstr.3x
index b2b563946b1467df85edf1b5ef6a696f966cdf68..888d4250091fd9c6b74ab48356fefd87c61c8a90 100644 (file)
--- a/man/curs_insstr.3x
+++ b/man/curs_insstr.3x
@@ -1,5 +1,5 @@
 .\"***************************************************************************
 .\"***************************************************************************
-.\" Copyright 2019-2022,2023 Thomas E. Dickey                                *
+.\" Copyright 2019-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  *
 .\" Copyright 1998-2010,2017 Free Software Foundation, Inc.                  *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
@@ -27,78 +27,98 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_insstr.3x,v 1.33 2023/07/01 15:43:20 tom Exp $
-.TH curs_insstr 3X 2023-07-01 "ncurses 6.4" "Library calls"
-.ie \n(.g .ds `` \(lq
-.el       .ds `` ``
-.ie \n(.g .ds '' \(rq
-.el       .ds '' ''
+.\" $Id: curs_insstr.3x,v 1.51 2024/04/20 21:20:07 tom Exp $
+.TH curs_insstr 3X 2024-04-20 "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
-\fBinsstr\fP,
-\fBinsnstr\fP,
-\fBwinsstr\fP,
-\fBwinsnstr\fP,
-\fBmvinsstr\fP,
-\fBmvinsnstr\fP,
-\fBmvwinsstr\fP,
-\fBmvwinsnstr\fP \- insert string before cursor in a \fBcurses\fP window
+\fB\%insstr\fP,
+\fB\%insnstr\fP,
+\fB\%winsstr\fP,
+\fB\%winsnstr\fP,
+\fB\%mvinsstr\fP,
+\fB\%mvinsnstr\fP,
+\fB\%mvwinsstr\fP,
+\fB\%mvwinsnstr\fP \-
+insert a string in a \fIcurses\fR window
 .SH SYNOPSIS
 .SH SYNOPSIS
-\fB#include <curses.h>\fP
-.br
-\fBint insstr(const char *\fIstr\fB);\fR
-.br
-\fBint insnstr(const char *\fIstr\fB, int \fIn\fB);\fR
-.br
-\fBint winsstr(WINDOW *\fIwin\fB, const char *\fIstr\fB);\fR
-.br
-\fBint winsnstr(WINDOW *\fIwin\fB, const char *\fIstr\fB, int \fIn\fB);\fR
-.sp
-\fBint mvinsstr(int \fIy\fB, int \fIx\fB, const char *\fIstr\fB);\fR
-.br
-\fBint mvinsnstr(int \fIy\fB, int \fIx\fB, const char *\fIstr\fB, int \fIn\fB);\fR
-.br
-\fBint mvwinsstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, const char *\fIstr\fB);\fR
-.br
-\fBint mvwinsnstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, const char *\fIstr\fB, int \fIn\fB);\fR
+.nf
+\fB#include <curses.h>
+\fBint insstr(const char *\fIstr\fP);
+\fBint insnstr(const char *\fIstr\fP, int \fIn\fP);
+\fBint winsstr(WINDOW *\fIwin\fP, const char *\fIstr\fP);
+\fBint winsnstr(WINDOW *\fIwin\fP, const char *\fIstr\fP, int \fIn\fP);
+.PP
+\fBint mvinsstr(int \fIy\fP, int \fIx\fP, const char *\fIstr\fP);
+\fBint mvinsnstr(int \fIy\fP, int \fIx\fP, const char *\fIstr\fP, int \fIn\fP);
+\fBint mvwinsstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const char *\fIstr\fP);
+\fBint mvwinsnstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const char *\fIstr\fP, int \fIn\fP);
+.fi
 .SH DESCRIPTION
 These routines insert a character string
 (as many characters as will fit on the line)
 .SH DESCRIPTION
 These routines insert a character string
 (as many characters as will fit on the line)
-before the character under the cursor.
-All characters to the right of the cursor are shifted right
+before the character under the cursor,
+as if calling \fBwinsch\fP(3X).
+All characters to the right of the cursor are shifted right,
 with the possibility of the rightmost characters on the line being lost.
 with the possibility of the rightmost characters on the line being lost.
+No wrapping is performed.
+.PP
 The cursor position does not change
 (after moving to \fIy\fP, \fIx\fP, if specified).
 The cursor position does not change
 (after moving to \fIy\fP, \fIx\fP, if specified).
+.PP
 The functions with \fIn\fP as the last argument
 insert a leading substring of at most \fIn\fP characters.
 The functions with \fIn\fP as the last argument
 insert a leading substring of at most \fIn\fP characters.
-If \fIn\fP<=0, then the entire string is inserted.
+If \fIn\fP is less than zero, the entire string is inserted
+(stopping on a NUL character).
 .PP
 .PP
-Special characters are handled as in \fBaddch\fP.
+Special characters are handled as in \fBwaddch\fP(3X).
 .SH RETURN VALUE
 .SH RETURN VALUE
-All routines that return an integer return \fBERR\fP upon failure and \fBOK\fP
-(SVr4 specifies only "an integer value other than \fBERR\fP")
-upon successful completion,
-unless otherwise noted in the preceding routine descriptions.
+All functions return the integer \fBERR\fP upon failure and \fBOK\fP on success.
 .PP
 .PP
-X/Open defines no error conditions.
-In this implementation,
-if the window parameter is null or the str parameter is null,
-an error is returned.
+X/Open Curses does not specify any error conditions.
+This implementation returns an error
+.bP
+if the \fIwin\fP parameter is null or
+.bP
+if the \fIstr\fP parameter is null or
+.bP
+the \fBwinsch\fP(3X) function returns an error.
 .PP
 .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
 .SH NOTES
-Note that all but \fBwinsnstr\fP may be macros.
+All but \fBwinsnstr\fP may be macros.
 .SH PORTABILITY
 .SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4, which adds
-const qualifiers to the arguments.
-.LP
+These functions are described in X/Open Curses, Issue 4,
+which adds \fI\%const\fP qualifiers to the arguments.
+.PP
 The Single Unix Specification, Version 2 states that
 \fBinsnstr\fP and \fBwinsnstr\fP perform wrapping.
 This is probably an error, since it makes this group of functions inconsistent.
 Also, no implementation of curses documents this inconsistency.
 The Single Unix Specification, Version 2 states that
 \fBinsnstr\fP and \fBwinsnstr\fP perform wrapping.
 This is probably an error, since it makes this group of functions inconsistent.
 Also, no implementation of curses documents this inconsistency.
+.PP
+X/Open states that the entire string is inserted if \fIn\fP is less than 1.
+This is probably an error,
+because it is inconsistent with other functions,
+and differs from the SVr4 and X/Open implementations on Solaris.
 .SH SEE ALSO
 .SH SEE ALSO
-\fBcurses\fP(3X),
-\fBcurs_util\fP(3X),
-\fBcurs_clear\fP(3X),
-\fBcurs_inch\fP(3X).
+\fB\%curses\fP(3X),
+\fB\%curs_inch\fP(3X),
+\fB\%curs_ins_wstr\fP(3X),
+\fB\%curs_util\fP(3X)
ncurses, with patches starting at ncurses-5.6; new users should use https://github.com/ThomasDickey/ncurses-snapshots/