Debian Codegraph @

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

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.65 2025/08/16 19:59:33 tom Exp $
31 .TH printw 3NCURSES 2025-08-16 "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\%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(3NCURSES) 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(3NCURSES) 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 in the language.
161 .I \%printw
162 went unused in Berkeley distributions until 4.1cBSD (1983),
163 which employed it in games.
164 .\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.1cBSD/usr/src/\
165 .\" games/canfield.c
166 .\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.1cBSD/usr/src/\
167 .\" games/worm.c
168 4BSD's
169 .I \%wprintw
170 did not use
171 .IR \%varargs.h ","
172 which had been available since Seventh Edition Unix (1979).
173 .\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/include/\
174 .\" varargs.h
175 In 1991
176 (a couple of years after SVr4 was generally available,
177 and after the C standard was published),
178 other developers updated the library,
179 using
180 .I \%stdarg.h
181 internally in 4.4BSD
182 .IR curses .
183 Even with this improvement,
184 BSD
185 .I curses
186 did not use function prototypes
187 (nor even declare functions)
188 in
189 .I \%curses.h
190 until 1992.
191 .PP
192 4BSD documented
193 .I \%printw
194 and
195 .I \%wprintw
196 tersely as \*(``printf on
197 .IR \%stdscr "\*(''"
198 and \*(``printf on
199 .IR win "\*('',"
200 respectively.
201 .\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/man/man3/\
202 .\" curses.3
203 .PP
204 SVr3 summarized the functions in three lines,
205 asserting that they were analogous to \fI\%printf\fP(3)
206 and explaining that the string that \fI\%printf\fP(3) would write to the
207 standard output stream would instead be output using
208 .I \%waddstr
209 to the given window.
210 .\" GBR can't find a source to cite for this paraphrase,
211 .\" even after checking
212 .\" <https://github.com/ryanwoodsmall/oldsysv/tree/master>.
213 .\"
214 .\" The indicated paraphrase is from page 432:
215 .\" Unix System V Programmer's Reference Manual
216 .\" Prentice-Hall
217 .\" ISBN 0-13-940479-1
218 .\" (bitsavers has 3rd printing from 1987)
219 .\"
220 .\" This lists mvprintw without detail, and printw as "printf on stdscr":
221 .\" Unix Programmer's Manual
222 .\" System Calls and Library Routines
223 .\" CBS College Publishing's UNIX System Library
224 .\" Holt, Rinehard and Winston, 1986
225 .\" ISBN 0-03-009314-7
226 .PP
227 SVr3 added
228 .IR \%vwprintw ","
229 describing its third parameter as a
230 .IR \%va_list ","
231 defined in
232 .IR \%varargs.h ","
233 and referred the reader to the manual pages for
234 .I \%varargs
235 and
236 .I \%vprintf
237 for detailed descriptions.
238 .PP
239 SVr4 (1989) introduced no new variations of
240 .IR \%printw ","
241 but provided for using either
242 .I \%varargs.h
243 or
244 .I \%stdarg.h
245 to define the
246 .I \%va_list
247 type.
248 .\" either header declares "va_list", but only one can be used
249 .PP
250 X/Open Curses Issue\ 4 (1995),
251 defined
252 .I \%vw_printw
253 to replace
254 .IR \%vwprintw ","
255 stating that its
256 .I \%va_list
257 type is defined in
258 .IR \%stdarg.h "."
259 .SH SEE ALSO
260 \fB\%ncurses\fP(3NCURSES),
261 \fB\%addstr\fP(3NCURSES),
262 \fB\%scanw\fP(3NCURSES),
263 \fB\%printf\fP(3),
264 \fB\%vprintf\fP(3)