Gitiles
Code Review Sign In
gerrit.omnirom.org / android_external_libncurses / b2cef93693cf7cfd01098c9b69603c90f0f4b803 / . / man / curs_addstr.3x
blob: b1cb1cc25c15ba30cc3668a34b0ed4f2b57a6ca1 [file] [log] [blame]
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]1.\"***************************************************************************
Steve Kondikae271bc2015-11-15 02:50:53 +0100[diff] [blame]2.\" Copyright (c) 1998-2010,2012 Free Software Foundation, Inc. *
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]3.\" *
4.\" Permission is hereby granted, free of charge, to any person obtaining a *
5.\" copy of this software and associated documentation files (the *
6.\" "Software"), to deal in the Software without restriction, including *
7.\" without limitation the rights to use, copy, modify, merge, publish, *
8.\" distribute, distribute with modifications, sublicense, and/or sell *
9.\" copies of the Software, and to permit persons to whom the Software is *
10.\" furnished to do so, subject to the following conditions: *
11.\" *
12.\" The above copyright notice and this permission notice shall be included *
13.\" in all copies or substantial portions of the Software. *
14.\" *
15.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
16.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
17.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
18.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
19.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
20.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
21.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
22.\" *
23.\" Except as contained in this notice, the name(s) of the above copyright *
24.\" holders shall not be used in advertising or otherwise to promote the *
25.\" sale, use or other dealings in this Software without prior written *
26.\" authorization. *
27.\"***************************************************************************
28.\"
Steve Kondikae271bc2015-11-15 02:50:53 +0100[diff] [blame]29.\" $Id: curs_addstr.3x,v 1.17 2012/11/03 22:57:31 tom Exp $
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]30.TH curs_addstr 3X ""
Steve Kondikae271bc2015-11-15 02:50:53 +0100[diff] [blame]31.de bP
32.IP \(bu 4
33..
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]34.na
35.hy 0
36.SH NAME
37\fBaddstr\fR,
38\fBaddnstr\fR,
39\fBwaddstr\fR,
40\fBwaddnstr\fR,
41\fBmvaddstr\fR,
42\fBmvaddnstr\fR,
43\fBmvwaddstr\fR,
Steve Kondikae271bc2015-11-15 02:50:53 +0100[diff] [blame]44\fBmvwaddnstr\fR \- add a string of characters to a \fBcurses\fR window and advance cursor
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]45.ad
46.hy
47.SH SYNOPSIS
48.nf
49\fB#include <curses.h>\fR
50.PP
51\fBint addstr(const char *\fR\fIstr\fR\fB);\fR
52.br
53\fBint addnstr(const char *\fR\fIstr\fR\fB, int \fR\fIn\fR\fB);\fR
54.br
55\fBint waddstr(WINDOW *\fR\fIwin\fR\fB, const char *\fR\fIstr\fR\fB);\fR
56.br
57\fBint waddnstr(WINDOW *\fR\fIwin\fR\fB, const char *\fR\fIstr\fR\fB, int \fR\fIn\fR\fB);\fR
58.br
59\fBint mvaddstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const char *\fR\fIstr\fR\fB);\fR
60.br
61\fBint mvaddnstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const char *\fR\fIstr\fR\fB, int \fR\fIn\fR\fB);\fR
62.br
63\fBint mvwaddstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const char *\fR\fIstr\fR\fB);\fR
64.br
65\fBint mvwaddnstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const char *\fR\fIstr, int \fR\fIn\fR\fB);\fR
66.fi
67.SH DESCRIPTION
Steve Kondikae271bc2015-11-15 02:50:53 +0100[diff] [blame]68These functions write the (null-terminated) character string
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]69\fIstr\fR on the given window.
70It is similar to calling \fBwaddch\fR once for each character in the string.
Steve Kondikae271bc2015-11-15 02:50:53 +0100[diff] [blame]71.PP
72The \fImv\fR functions perform cursor movement once, before writing any
73characters.
74Thereafter, the cursor is advanced as a side-effect of writing to the window.
75.PP
76The four functions with \fIn\fR as the last argument
77write at most \fIn\fR characters,
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]78or until a terminating null is reached.
Steve Kondikae271bc2015-11-15 02:50:53 +0100[diff] [blame]79If \fIn\fR is \-1, then the entire string will be added.
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]80.SH RETURN VALUE
Steve Kondikae271bc2015-11-15 02:50:53 +0100[diff] [blame]81All functions return the integer \fBERR\fR upon failure and \fBOK\fR on success.
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]82.PP
83X/Open does not define any error conditions.
84This implementation returns an error
Steve Kondikae271bc2015-11-15 02:50:53 +0100[diff] [blame]85.bP
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]86if the window pointer is null or
Steve Kondikae271bc2015-11-15 02:50:53 +0100[diff] [blame]87.bP
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]88if the string pointer is null or
Steve Kondikae271bc2015-11-15 02:50:53 +0100[diff] [blame]89.bP
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]90if the corresponding calls to \fBwaddch\fP return an error.
Steve Kondikae271bc2015-11-15 02:50:53 +0100[diff] [blame]91.PP
92Functions with a "mv" prefix first perform a cursor movement using
93\fBwmove\fP, and return an error if the position is outside the window,
94or if the window pointer is null.
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]95.SH NOTES
Steve Kondikae271bc2015-11-15 02:50:53 +0100[diff] [blame]96All of these functions except \fBwaddnstr\fR may be macros.
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]97.SH PORTABILITY
Steve Kondikae271bc2015-11-15 02:50:53 +0100[diff] [blame]98These functions are described in the XSI Curses standard, Issue 4.
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]99.SH SEE ALSO
Steve Kondikae271bc2015-11-15 02:50:53 +0100[diff] [blame]100\fBcurses\fR(3X),
101\fBcurs_addch\fR(3X).