ncurses 6.2 - patch 20210109
[ncurses.git] / man / curs_printw.3x
index a1ec5558194e720b7e941247215fd7522e100a41..4980517275d5832dfad709251a4ccb31410cd7e1 100644 (file)
@@ -1,5 +1,6 @@
 .\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc.              *
+.\" Copyright 2018-2019,2020 Thomas E. Dickey                                *
+.\" Copyright 1998-2010,2017 Free Software Foundation, Inc.                  *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
 .\" copy of this software and associated documentation files (the            *
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_printw.3x,v 1.18 2010/07/31 16:10:55 tom Exp $
+.\" $Id: curs_printw.3x,v 1.28 2020/10/24 09:22:45 tom Exp $
 .TH curs_printw 3X ""
+.ie \n(.g .ds `` \(lq
+.el       .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el       .ds '' ''
+.de bP
+.ie n  .IP \(bu 4
+.el    .IP \(bu 2
+..
 .na
 .hy 0
 .SH NAME
 .SH SYNOPSIS
 \fB#include <curses.h>\fR
 .sp
-\fBint printw(const char *fmt, ...);\fR
+\fBint printw(const char *\fP\fIfmt\fP\fB, ...);\fR
 .br
-\fBint wprintw(WINDOW *win, const char *fmt, ...);\fR
+\fBint wprintw(WINDOW *\fP\fIwin\fP\fB, const char *\fP\fIfmt\fP\fB, ...);\fR
 .br
-\fBint mvprintw(int y, int x, const char *fmt, ...);\fR
+\fBint mvprintw(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, const char *\fP\fIfmt\fP\fB, ...);\fR
 .br
-\fBint mvwprintw(WINDOW *win, int y, int x, const char *fmt, ...);\fR
+\fBint mvwprintw(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, const char *\fP\fIfmt\fP\fB, ...);\fR
 .br
-\fBint vwprintw(WINDOW *win, const char *fmt, va_list varglist);\fR
-.br
-\fBint vw_printw(WINDOW *win, const char *fmt, va_list varglist);\fR
+\fBint vw_printw(WINDOW *\fP\fIwin\fP\fB, const char *\fP\fIfmt\fP\fB, va_list \fP\fIvarglist\fP\fB);\fR
+.sp
+/* obsolete */
 .br
+\fBint vwprintw(WINDOW *\fP\fIwin\fP\fB, const char *\fP\fIfmt\fP\fB, va_list \fP\fIvarglist\fP\fB);\fR
 .SH DESCRIPTION
 The \fBprintw\fR, \fBwprintw\fR, \fBmvprintw\fR and \fBmvwprintw\fR
-routines are analogous to \fBprintf\fR [see \fBprintf\fR(3)].  In
+routines are analogous to \fBprintf\fR [see \fBprintf\fR(3)].
+In
 effect, the string that would be output by \fBprintf\fR is output
 instead as though \fBwaddstr\fR were used on the given window.
 .PP
-The \fBvwprintw\fR and \fBwv_printw\fR routines are analogous
+The \fBvwprintw\fR and \fBvw_printw\fR routines are analogous
 to \fBvprintf\fR [see \fBprintf\fR(3)]
 and perform a \fBwprintw\fR using a variable argument list.
 The third argument is a \fBva_list\fR, a pointer to a
@@ -74,21 +85,70 @@ In this implementation,
 an error may be returned if it cannot allocate enough memory for the
 buffer used to format the results.
 It will return an error if the window pointer is null.
+.PP
+Functions with a \*(``mv\*('' prefix first perform a cursor movement using
+\fBwmove\fP, and return an error if the position is outside the window,
+or if the window pointer is null.
+.SH HISTORY
+While \fBprintw\fP was implemented in 4BSD,
+it was unused until 4.2BSD (which used it in games).
+That early version of curses was before the ANSI C standard.
+It did not use <varargs.h>, though that was available.
+In 1991 (a couple of years after SVr4 was generally available,
+and after the C standard was published),
+other developers updated the library,
+using <stdarg.h> internally in 4.4BSD curses.
+Even with this improvement,
+BSD curses did not use function prototypes (or even declare
+functions) in the <curses.h> header until 1992.
+.PP
+SVr2 documented
+\fBprintw\fP,
+\fBwprintw\fP
+tersely as \*(``printf on \fIstdscr\fP\*('' and
+tersely as \*(``printf on \fIwin\fP\*('', respectively.
+.PP
+SVr3 added
+\fBmvprintw\fP, and
+\fBmvwprintw\fP, with a three-line summary saying that they were analogous
+to \fBprintf\fP(3),
+explaining that the string which would be output from \fBprintf\fP(3) would
+instead be output using \fBwaddstr\fP on the given window.
+SVr3 also added \fBvwprintw\fP, saying that the third parameter
+is a \fBva_list\fP, defined in <varargs.h>,
+and referring the reader to the manual pages for \fIvarargs\fP and
+\fIvprintf\fP for detailed descriptions.
+.PP
+SVr4 added no new variations of \fBprintw\fP,
+but provided for using <varargs.h> or <stdarg.h> to define the \fBva_list\fP
+type.
+.PP
+X/Open Curses added \fBvw_printw\fP to replace \fBvwprintw\fP,
+stating that its \fBva_list\fP definition requires <stdarg.h>.
 .SH PORTABILITY
-The XSI Curses standard, Issue 4 describes these functions.  The function
+In this implementation, \fBvw_printw\fP and \fBvwprintw\fP are equivalent,
+to support legacy applications.
+However, the latter (\fBvwprintw\fP) is obsolete:
+.bP
+The XSI Curses standard, Issue 4 described these functions.
+The function
 \fBvwprintw\fR is marked TO BE WITHDRAWN, and is to be replaced by a function
 \fBvw_printw\fR using the \fB<stdarg.h>\fR interface.
+.bP
 The Single Unix Specification, Version 2 states that
 \fBvw_printw\fR  is preferred to \fBvwprintw\fR since the latter requires
 including \fB<varargs.h>\fR, which
 cannot be used in the same file as \fB<stdarg.h>\fR.
-This implementation uses \fB<stdarg.h>\fR for both, because that header
-is included in \fB<curses.h\fR>.
+This implementation uses \fB<stdarg.h>\fR for both,
+because that header is included in \fB<curses.h\fR>.
+.bP
+X/Open Curses, Issue 5 (December 2007) marked \fBvwprintw\fP (along with
+\fBvwscanw\fP and the termcap interface) as withdrawn.
 .SH SEE ALSO
-\fBcurses\fR(3X), \fBprintf\fR(3), \fBvprintf(3)\fR
-.\"#
-.\"# The following sets edit modes for GNU EMACS
-.\"# Local Variables:
-.\"# mode:nroff
-.\"# fill-column:79
-.\"# End:
+.na
+\fBcurses\fR(3X),
+\fBcurs_addstr\fR(3X),
+\fBcurs_scanw\fR(3X),
+\fBcurs_termcap\fP(3X),
+\fBprintf\fR(3),
+\fBvprintf\fR(3).