Debian Codegraph @

upstream/mageia-cauldron/man3/curs_printw.3x

raw
1 .\"***************************************************************************
2 .\" Copyright 2018-2024,2025 Thomas E. Dickey *
3 .\" Copyright 1998-2010,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_printw.3x,v 1.63 2025/07/05 13:02:27 tom Exp $
31 .TH curs_printw 3X 2025-07-05 "ncurses 6.5" "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\%printw\fP,
49 \fB\%wprintw\fP,
50 \fB\%mvprintw\fP,
51 \fB\%mvwprintw\fP,
52 \fB\%vwprintw\fP,
53 \fB\%vw_printw\fP \-
54 write formatted output to a \fIcurses\fR window
55 .SH SYNOPSIS
56 .nf
57 \fB#include <curses.h>
58 .PP
59 \fBint printw(const char *\fIfmt\fP, ...);
60 \fBint wprintw(WINDOW *\fIwin\fP, const char *\fIfmt\fP, ...);
61 \fBint mvprintw(int \fIy\fP, int \fIx\fP, const char *\fIfmt\fP, ...);
62 \fBint mvwprintw(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const char *\fIfmt\fP, ...);
63 .PP
64 \fBint vw_printw(WINDOW *\fIwin\fP, const char *\fIfmt\fP, va_list \fIvarglist\fP);
65 .PP
66 \fI/* obsolete */\fP
67 \fBint vwprintw(WINDOW *\fIwin\fP, const char *\fIfmt\fP, va_list \fIvarglist\fP);
68 .fi
69 .SH DESCRIPTION
70 \fB\%printw\fP,
71 \fB\%wprintw\fP,
72 \fB\%mvprintw\fP,
73 and
74 \fB\%mvwprintw\fP
75 are analogous to \fI\%printf\fP(3).
76 In effect,
77 the string that would be output by \fI\%printf\fP(3) is instead output
78 as though \fB\%waddstr\fP(3X) were used with
79 .I win
80 (or
81 .BR \%stdscr )
82 as its first argument.
83 .PP
84 \fB\%vwprintw\fP
85 and
86 \fB\%vw_printw\fP are analogous to \fI\%vprintf\fP(3),
87 and perform a \fB\%wprintw\fP using a variable argument list.
88 The third argument is a \fI\%va_list\fP,
89 a pointer to a list of arguments,
90 as defined in \fI\%stdarg.h\fP.
91 .SH RETURN VALUE
92 These functions return
93 .B ERR
94 upon failure and
95 .B OK
96 upon success.
97 .PP
98 In
99 .IR \%ncurses ,
100 failure occurs if the library cannot allocate enough memory for the
101 buffer into which the output is formatted,
102 or if the window pointer
103 .I win
104 is null.
105 .PP
106 Functions prefixed with \*(``mv\*('' first perform cursor movement and
107 fail if the position
108 .RI ( y ,
109 .IR x )
110 is outside the window boundaries.
111 .SH NOTES
112 No wide character counterpart functions are defined by the
113 \*(``wide\*(''
114 .I \%ncurses
115 configuration nor by any standard.
116 To format and write a wide-character string to a
117 .I curses
118 window,
119 consider using \fI\%swprintf\fP(3) and \fB\%waddwstr\fP(3X) or similar.
120 .SH PORTABILITY
121 X/Open Curses Issue\ 4 describes these functions.
122 It specifies no error conditions for them.
123 .PP
124 .I \%ncurses
125 defines \fB\%vw_printw\fP and \fB\%vwprintw\fP identically to support
126 legacy applications.
127 However,
128 the latter is obsolete.
129 .bP
130 X/Open Curses Issue\ 4 Version\ 2 (1996),
131 marked \fB\%vwprintw\fP as requiring \fI\%varargs.h\fP and
132 \*(``TO BE WITHDRAWN\*('',
133 and specified \fB\%vw_printw\fP using the \fI\%stdarg.h\fP interface.
134 .bP
135 X/Open Curses Issue\ 5, Draft 2
136 (December 2007) marked \fBvwprintw\fP (along with
137 \fBvwscanw\fP and the \fItermcap\fP interface) as withdrawn.
138 After incorporating review comments,
139 this became
140 X/Open Curses Issue\ 7 (2009).
141 .bP
142 .I \%ncurses
143 provides \fB\%vwprintw\fP,
144 but marks it as deprecated.
145 .SH HISTORY
146 4BSD (1980)
147 introduced
148 .I \%wprintw
149 and its variants.
150 .\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/src/lib/\
151 .\" libcurses/printw.c
152 .\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/src/lib/\
153 .\" libcurses/mvprintw.c
154 It implemented all as functions,
155 not macros;
156 this initial distribution of
157 .I curses
158 preceded the ANSI C standard of 1989,
159 prior to which a variadic macro facility was not widely available.
160 .I \%printw
161 went unused in Berkeley distributions until 4.1cBSD (1983),
162 which employed it in games.
163 .\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.1cBSD/usr/src/\
164 .\" games/canfield.c
165 .\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.1cBSD/usr/src/\
166 .\" games/worm.c
167 4BSD's
168 .I \%wprintw
169 did not use
170 .IR \%varargs.h ","
171 which had been available since Seventh Edition Unix (1979).
172 .\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/include/\
173 .\" varargs.h
174 In 1991
175 (a couple of years after SVr4 was generally available,
176 and after the C standard was published),
177 other developers updated the library,
178 using
179 .I \%stdarg.h
180 internally in 4.4BSD
181 .IR curses .
182 Even with this improvement,
183 BSD
184 .I curses
185 did not use function prototypes
186 (nor even declare functions)
187 in
188 .I \%curses.h
189 until 1992.
190 .PP
191 4BSD documented
192 .I \%printw
193 and
194 .I \%wprintw
195 tersely as \*(``printf on
196 .IR \%stdscr "\*(''"
197 and \*(``printf on
198 .IR win "\*('',"
199 respectively.
200 .\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/man/man3/\
201 .\" curses.3
202 .PP
203 SVr3 summarized the functions in three lines,
204 asserting that they were analogous to \fI\%printf\fP(3)
205 and explaining that the string that \fI\%printf\fP(3) would write to the
206 standard output stream would instead be output using
207 .I \%waddstr
208 to the given window.
209 .\" GBR can't find a source to cite for this paraphrase,
210 .\" even after checking
211 .\" <https://github.com/ryanwoodsmall/oldsysv/tree/master>.
212 .\"
213 .\" The indicated paraphrase is from page 432:
214 .\" Unix System V Programmer's Reference Manual
215 .\" Prentice-Hall
216 .\" ISBN 0-13-940479-1
217 .\" (bitsavers has 3rd printing from 1987)
218 .\"
219 .\" This lists mvprintw without detail, and printw as "printf on stdscr":
220 .\" Unix Programmer's Manual
221 .\" System Calls and Library Routines
222 .\" CBS College Publishing's UNIX System Library
223 .\" Holt, Rinehard and Winston, 1986
224 .\" ISBN 0-03-009314-7
225 .PP
226 SVr3 added
227 .IR \%vwprintw ","
228 describing its third parameter as a
229 .IR \%va_list ","
230 defined in
231 .IR \%varargs.h ","
232 and referred the reader to the manual pages for
233 .I \%varargs
234 and
235 .I \%vprintf
236 for detailed descriptions.
237 .PP
238 SVr4 (1989) introduced no new variations of
239 .IR \%printw ","
240 but provided for using either
241 .I \%varargs.h
242 or
243 .I \%stdarg.h
244 to define the
245 .I \%va_list
246 type.
247 .\" either header declares "va_list", but only one can be used
248 .PP
249 X/Open Curses Issue\ 4 (1995),
250 defined
251 .I \%vw_printw
252 to replace
253 .IR \%vwprintw ","
254 stating that its
255 .I \%va_list
256 type is defined in
257 .IR \%stdarg.h "."
258 .SH SEE ALSO
259 \fB\%curses\fP(3X),
260 \fB\%curs_addstr\fP(3X),
261 \fB\%curs_scanw\fP(3X),
262 \fB\%printf\fP(3),
263 \fB\%vprintf\fP(3)