- 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 window.
+ 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 wv_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 defined 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 completion.
+ These functions return ERR upon failure and OK upon success.
+
+ 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.
- X/Open defines no error conditions. In this implementa-
- tion, 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.
+ Functions prefixed with "mv" first perform cursor movement and fail if
+ the position (y, x) is outside the window boundaries.
- Functions with a "mv" prefix first perform a cursor move-
- ment using wmove, and return an error if the position is
- outside the window, or if the window pointer is null.
+
+
+ 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.
- 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. The Single Unix Specification, Ver-
- sion 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 im-
- plementation uses <stdarg.h> for both, because that header
- is included in <curses.h>.
+ X/Open Curses, Issue 4 describes these functions. It specifies no
+ error conditions for them.
+
+ ncurses defines vw_printw and vwprintw identically to support legacy
+ applications. However, the latter is obsolete.
+
+ 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).
+
+ oncurses provides vwprintw, but marks it as deprecated.
+
+
+
+ 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.