- The printw, wprintw, mvprintw and mvwprintw routines are
- analogous to printf [see printf(3S)]. In effect, the
- string that would be output by printf is output instead as
- though waddstr were used on the given window.
+
+ The printw, wprintw, mvprintw and mvwprintw routines are analogous to
+ printf [see printf(3)]. In effect, the string that would be output by
+ printf is output instead as though waddstr were used on the given win-
+ dow.
- The vwprintw routine is analogous to vprintf [see
- printf(3S)] and performs a wprintw using a variable argu-
- ment list. The third argument is a va_list, a pointer to
- a list of arguments, as defined in <varargs.h>.
+ The vwprintw and vw_printw routines are analogous to vprintf [see
+ printf(3)] and perform a wprintw using a variable argument list. The
+ third argument is a va_list, a pointer to a list of arguments, as de-
+ fined in <stdarg.h>.
-
-
RETURN VALUE
- Routines that return an integer return ERR upon failure
- and OK (SVr4 only specifies "an integer value other than
- ERR") upon successful completion.
+
+ Routines that return an integer return ERR upon failure and OK (SVr4
+ only specifies "an integer value other than ERR") upon successful com-
+ pletion.
+ X/Open defines no error conditions. 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.
-
-
PORTABILITY
- The XSI Curses standard, Issue 4 describes these func-
- tions. The function vwprintw is marked TO BE WITHDRAWN,
- and is to be replaced by a function vw_printw using the
- <stdarg.h> interface.
+ Functions with a "mv" prefix first perform a cursor movement using
+ wmove, and return an error if the position is outside the window, or if
+ the window pointer is null.
-
+ While printw 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 improve-
+ ment, BSD curses did not use function prototypes (or even declare func-
+ tions) in the <curses.h> header until 1992.
+
+ SVr2 documented printw, wprintw tersely as "printf on stdscr" and
+ tersely as "printf on win", respectively.
+ SVr3 added mvprintw, and mvwprintw, with a three-line summary saying
+ that they were analogous to printf(3), explaining that the string which
+ would be output from printf(3) would instead be output using waddstr on
+ the given window. SVr3 also added vwprintw, saying that the third pa-
+ rameter is a va_list, defined in <varargs.h>, and referring the reader
+ to the manual pages for varargs and vprintf for detailed descriptions.
+ SVr4 added no new variations of printw, but provided for using
+ <varargs.h> or <stdarg.h> to define the va_list type.
+ X/Open Curses added vw_printw to replace vwprintw, stating that its
+ va_list definition requires <stdarg.h>.
+
+ In this implementation, vw_printw and vwprintw are equivalent, to sup-
+ port legacy applications. However, the latter (vwprintw) is obsolete:
+ o The XSI Curses standard, Issue 4 described these functions. The
+ function vwprintw is marked TO BE WITHDRAWN, and is to be replaced
+ by a function vw_printw using the <stdarg.h> interface.
+ o The Single Unix Specification, Version 2 states that vw_printw is
+ preferred to vwprintw since the latter requires including
+ <varargs.h>, which cannot be used in the same file as <stdarg.h>.
+ This implementation uses <stdarg.h> for both, because that header
+ is included in <curses.h>.
+ o X/Open Curses, Issue 5 (December 2007) marked vwprintw (along with
+ vwscanw and the termcap interface) as withdrawn.
+