Debian Codegraph @

upstream/debian-unstable/man3/addstr.3ncurses

raw
1 .\"***************************************************************************
2 .\" Copyright 2019-2024,2025 Thomas E. Dickey *
3 .\" Copyright 1998-2012,2017 Free Software Foundation, Inc. *
4 .\" *
5 .\" Permission is hereby granted, free of charge, to any person obtaining a *
6 .\" copy of this software and associated documentation files (the *
7 .\" "Software"), to deal in the Software without restriction, including *
8 .\" without limitation the rights to use, copy, modify, merge, publish, *
9 .\" distribute, distribute with modifications, sublicense, and/or sell *
10 .\" copies of the Software, and to permit persons to whom the Software is *
11 .\" furnished to do so, subject to the following conditions: *
12 .\" *
13 .\" The above copyright notice and this permission notice shall be included *
14 .\" in all copies or substantial portions of the Software. *
15 .\" *
16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
17 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
19 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
20 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
21 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
22 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
23 .\" *
24 .\" Except as contained in this notice, the name(s) of the above copyright *
25 .\" holders shall not be used in advertising or otherwise to promote the *
26 .\" sale, use or other dealings in this Software without prior written *
27 .\" authorization. *
28 .\"***************************************************************************
29 .\"
30 .\" $Id: curs_addstr.3x,v 1.71 2025/10/21 00:09:34 tom Exp $
31 .TH addstr 3NCURSES 2025-10-20 "ncurses 6.6" "Library calls"
32 .ie \n(.g \{\
33 .ds `` \(lq
34 .ds '' \(rq
35 .\}
36 .el \{\
37 .ie t .ds `` ``
38 .el .ds `` ""
39 .ie t .ds '' ''
40 .el .ds '' ""
41 .\}
42 .
43 .de bP
44 .ie n .IP \(bu 4
45 .el .IP \(bu 2
46 ..
47 .SH NAME
48 \fB\%addstr\fP,
49 \fB\%waddstr\fP,
50 \fB\%mvaddstr\fP,
51 \fB\%mvwaddstr\fP,
52 \fB\%addnstr\fP,
53 \fB\%waddnstr\fP,
54 \fB\%mvaddnstr\fP,
55 \fB\%mvwaddnstr\fP \-
56 add a string to a \fIcurses\fR window and advance the cursor
57 .SH SYNOPSIS
58 .nf
59 \fB#include <curses.h>
60 .PP
61 \fBint addstr(const char * \fIstr\fP);
62 \fBint waddstr(WINDOW * \fIwin\fP, const char * \fIstr\fP);
63 \fBint mvaddstr(int \fIy\fP, int \fIx\fP, const char * \fIstr\fP);
64 \fBint mvwaddstr(WINDOW * \fIwin\fP, int \fIy\fP, int \fIx\fP, const char * \fIstr\fP);
65 .PP
66 \fBint addnstr(const char * \fIstr\fP, int \fIn\fP);
67 \fBint waddnstr(WINDOW * \fIwin\fP, const char * \fIstr\fP, int \fIn\fP);
68 \fBint mvaddnstr(int \fIy\fP, int \fIx\fP, const char * \fIstr\fP, int \fIn\fP);
69 \fBint mvwaddnstr(WINDOW * \fIwin\fP, int \fIy\fP, int \fIx\fP, const char * \fIstr\fP, int \fIn\fP);
70 .fi
71 .SH DESCRIPTION
72 .B \%waddstr
73 writes the characters of the (null-terminated) string
74 .I str
75 to the window
76 .IR win ,
77 as if by calling \fB\%waddch\fP(3NCURSES) for each
78 .I char
79 in
80 .IR str .
81 .B \%waddnstr
82 is similar,
83 but writes at most
84 .I n
85 characters.
86 If
87 .I n
88 is \-1,
89 .B \%waddnstr
90 writes the entire string.
91 \fB\%ncurses\fP(3NCURSES) describes the variants of these functions.
92 .SH RETURN VALUE
93 These functions return
94 .B OK
95 on success and
96 .B ERR
97 on failure.
98 .PP
99 In
100 .IR \%ncurses ","
101 these functions fail if
102 .bP
103 the
104 .I curses
105 screen has not been initialized,
106 .bP
107 .I str
108 is a null pointer,
109 .bP
110 (for functions taking a
111 .I \%WINDOW
112 pointer argument)
113 .I win
114 is a null pointer,
115 or
116 .bP
117 an internal \fB\%waddch\fP(3NCURSES) call returns
118 .BR ERR "."
119 .PP
120 Functions prefixed with \*(``mv\*('' first perform cursor movement and
121 fail if the position
122 .RI ( y ,
123 .IR x )
124 is outside the window boundaries.
125 .SH NOTES
126 All of these functions except
127 .B \%waddnstr
128 may be implemented as macros.
129 .SH PORTABILITY
130 X/Open Curses Issue\ 4 describes these functions.
131 It specifies no error conditions for them.
132 .PP
133 SVr4 describes a successful return value only as
134 \*(``an integer value other than
135 .IR ERR \*(''. \" Courier roman in source; SVID 4, vol. 3, p. 474
136 .SH HISTORY
137 4BSD (1980)
138 introduced
139 .I \%waddstr
140 along with its variants,
141 the latter defined as macros.
142 .PP
143 SVr3.1 (1987)
144 added
145 .I \%waddnstr
146 (and its variants)
147 redefining
148 .I \%waddstr
149 as a macro wrapping it.
150 .SH SEE ALSO
151 \fB\%addwstr\fP(3NCURSES) describes comparable functions of the
152 .I \%ncurses
153 library in its wide-character configuration
154 .RI \%( ncursesw ).
155 .PP
156 \fB\%ncurses\fP(3NCURSES),
157 \fB\%addch\fP(3NCURSES),
158 \fB\%addchstr\fP(3NCURSES)