Debian Codegraph @

upstream/debian-trixie/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.57 2025/01/19 00:51:10 tom Exp $
31 .TH printw 3NCURSES 2025-01-18 "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(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 While \fB\%printw\fP was implemented in 4BSD
147 (November 1980),
148 .\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/src/lib/\
149 .\" libcurses/printw.c
150 it was unused until 4.2BSD
151 (August 1983),
152 which employed it for games.
153 That early version of
154 .I curses
155 preceded the ANSI C standard of 1989.
156 It did not use \fI\%varargs.h\fP,
157 though that had been available since Seventh Edition Unix (1979).
158 .\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/include/\
159 .\" varargs.h
160 In 1991
161 (a couple of years after SVr4 was generally available,
162 and after the C standard was published),
163 other developers updated the library,
164 using \fI\%stdarg.h\fP internally in 4.4BSD
165 .IR curses .
166 Even with this improvement,
167 BSD
168 .I curses
169 did not use function prototypes
170 (nor even declare functions)
171 in \fI\%curses.h\fP until 1992.
172 .PP
173 SVr2 (1984) documented \fB\%printw\fP and \fB\%wprintw\fP tersely as
174 \*(``printf on \fB\%stdscr\fP\*('' and
175 \*(``printf on \fIwin\fP\*('',
176 respectively.
177 .PP
178 SVr3 (1987) added \fB\%mvprintw\fP and \fB\%mvwprintw\fP,
179 with a three-line summary asserting that they were analogous to
180 \fI\%printf\fP(3),
181 explaining that the string that \fI\%printf\fP(3) would write to the
182 standard output stream would instead be output using \fB\%waddstr\fP to
183 the given window.
184 SVr3 also implemented \fB\%vwprintw\fP,
185 describing its third parameter as a \fI\%va_list\fP,
186 defined in \fI\%varargs.h\fP,
187 and referred the reader to the manual pages for \fI\%varargs\fP and
188 \fI\%vprintf\fP for detailed descriptions.
189 .PP
190 SVr4 (1989) introduced no new variations of \fI\%printw\fP,
191 but provided for using either \fI\%varargs.h\fP or \fI\%stdarg.h\fP to
192 define the \fI\%va_list\fP type.
193 .\" either header declares "va_list", but only one can be used
194 .PP
195 X/Open Curses Issue\ 4 (1995),
196 defined \fB\%vw_printw\fP to replace \fB\%vwprintw\fP,
197 stating that its \fI\%va_list\fP type is defined in \fI\%stdarg.h\fP.
198 .SH SEE ALSO
199 \fB\%ncurses\fP(3NCURSES),
200 \fB\%addstr\fP(3NCURSES),
201 \fB\%scanw\fP(3NCURSES),
202 \fB\%printf\fP(3),
203 \fB\%vprintf\fP(3)