- 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.
+ printw, wprintw, mvprintw, and mvwprintw are analogous to printf(3).
+ In effect, the string that would be output by printf(3) is instead
+ output as though waddstr(3x) were used with win (or stdscr) as its
+ first argument.
- 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>.
+ vwprintw and vw_printw are analogous to vprintf(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 defined in stdarg.h.
- Routines that return an integer return ERR upon failure and OK (SVr4
- only specifies "an integer value other than ERR") upon successful com-
- pletion.
+ These functions return ERR upon failure and OK upon success.
- 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.
+ In ncurses, failure occurs if the library cannot allocate enough memory
+ for the buffer into which the output is formatted, or if the window
+ pointer win is null.
- 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.
+ Functions prefixed with "mv" first perform cursor movement and fail if
+ the position (y, x) is outside the window boundaries.
-
- 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.
+
+ No wide character counterpart functions are defined by the "wide"
+ ncurses configuration nor by any standard. To format and write a wide-
+ character string to a curses window, consider using swprintf(3) and
+ waddwstr(3x) or similar.
- 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.
+
+ X/Open Curses, Issue 4 describes these functions. It specifies no
+ error conditions for them.
- SVr4 added no new variations of printw, but provided for using
- <varargs.h> or <stdarg.h> to define the va_list type.
+ ncurses defines vw_printw and vwprintw identically to support legacy
+ applications. However, the latter is obsolete.
- X/Open Curses added vw_printw to replace vwprintw, stating that its
- va_list definition requires <stdarg.h>.
+ o X/Open Curses, Issue 4 Version 2 (1996), marked vwprintw as
+ requiring varargs.h and "TO BE WITHDRAWN", and specified vw_printw
+ using the stdarg.h interface.
+ o X/Open Curses, Issue 5, Draft 2 (December 2007) marked vwprintw
+ (along with vwscanw and the termcap interface) as withdrawn. After
+ incorporating review comments, this became X/Open Curses, Issue 7
+ (2009).
-
- In this implementation, vw_printw and vwprintw are equivalent, to sup-
- port legacy applications. However, the latter (vwprintw) is obsolete:
+ oncurses provides vwprintw, but marks it as deprecated.
- 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.
+
+ While printw was implemented in 4BSD (November 1980), it was unused
+ until 4.2BSD (August 1983), which employed it for games. That early
+ version of curses preceded the ANSI C standard of 1989. It did not use
+ varargs.h, though that had been available since Seventh Edition Unix
+ (1979). 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 (nor even
+ declare functions) in curses.h until 1992.
+
+ SVr2 (1984) documented printw and wprintw tersely as "printf on stdscr"
+ and "printf on win", respectively.
+
+ SVr3 (1987) added mvprintw and mvwprintw, with a three-line summary
+ asserting that they were analogous to printf(3), explaining that the
+ string that printf(3) would write to the standard output stream would
+ instead be output using waddstr to the given window. SVr3 also
+ implemented vwprintw, describing its third parameter as a va_list,
+ defined in varargs.h, and referred the reader to the manual pages for
+ varargs and vprintf for detailed descriptions.
+
+ SVr4 (1989) introduced no new variations of printw, but provided for
+ using either varargs.h or stdarg.h to define the va_list type.
+
+ X/Open Curses, Issue 4 (1995), defined vw_printw to replace vwprintw,
+ stating that its va_list type is defined in stdarg.h.