X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_printw.3x;h=ee9ea8a37c02a73d7b89078d7b1b924f071cbff5;hp=d7f2660714bd143ba5e9abd7d45728f7fc8778d0;hb=HEAD;hpb=7e062bb2764a87d98073a90ee65a234a2679f9c1 diff --git a/man/curs_printw.3x b/man/curs_printw.3x index d7f26607..282536b3 100644 --- a/man/curs_printw.3x +++ b/man/curs_printw.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 2018-2023,2024 Thomas E. Dickey * .\" Copyright 1998-2010,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,12 +27,19 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_printw.3x,v 1.40 2023/09/30 21:38:11 tom Exp $ -.TH curs_printw 3X 2023-09-30 "ncurses 6.4" "Library calls" -.ie \n(.g .ds `` \(lq -.el .ds `` `` -.ie \n(.g .ds '' \(rq -.el .ds '' '' +.\" $Id: curs_printw.3x,v 1.53 2024/04/20 19:18:18 tom Exp $ +.TH curs_printw 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls" +.ie \n(.g \{\ +.ds `` \(lq +.ds '' \(rq +.\} +.el \{\ +.ie t .ds `` `` +.el .ds `` "" +.ie t .ds '' '' +.el .ds '' "" +.\} +. .de bP .ie n .IP \(bu 4 .el .IP \(bu 2 @@ -44,108 +51,155 @@ \fB\%mvwprintw\fP, \fB\%vwprintw\fP, \fB\%vw_printw\fP \- -write formatted output to \fIcurses\fR windows +write formatted output to a \fIcurses\fR window .SH SYNOPSIS -\fB#include \fP -.sp -\fBint printw(const char *\fIfmt\fB, ...);\fR -.br -\fBint wprintw(WINDOW *\fIwin\fB, const char *\fIfmt\fB, ...);\fR -.br -\fBint mvprintw(int \fIy\fB, int \fIx\fB, const char *\fIfmt\fB, ...);\fR -.br -\fBint mvwprintw(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, const char *\fIfmt\fB, ...);\fR -.br -\fBint vw_printw(WINDOW *\fIwin\fB, const char *\fIfmt\fB, va_list \fIvarglist\fB);\fR -.sp -/* obsolete */ -.br -\fBint vwprintw(WINDOW *\fIwin\fB, const char *\fIfmt\fB, va_list \fIvarglist\fB);\fR +.nf +\fB#include +.PP +\fBint printw(const char *\fIfmt\fP, ...); +\fBint wprintw(WINDOW *\fIwin\fP, const char *\fIfmt\fP, ...); +\fBint mvprintw(int \fIy\fP, int \fIx\fP, const char *\fIfmt\fP, ...); +\fBint mvwprintw(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const char *\fIfmt\fP, ...); +.PP +\fBint vw_printw(WINDOW *\fIwin\fP, const char *\fIfmt\fP, va_list \fIvarglist\fP); +.PP +\fI/* obsolete */\fP +\fBint vwprintw(WINDOW *\fIwin\fP, const char *\fIfmt\fP, va_list \fIvarglist\fP); +.fi .SH DESCRIPTION -The \fBprintw\fP, \fBwprintw\fP, \fBmvprintw\fP and \fBmvwprintw\fP -routines are analogous to \fBprintf\fP [see \fBprintf\fP(3)]. -In -effect, the string that would be output by \fBprintf\fP is output -instead as though \fBwaddstr\fP were used on the given window. +\fB\%printw\fP, +\fB\%wprintw\fP, +\fB\%mvprintw\fP, +and +\fB\%mvwprintw\fP +are analogous to \fI\%printf\fP(3). +In effect, +the string that would be output by \fI\%printf\fP(3) is instead output +as though \fB\%waddstr\fP(3X) were used with +.I win +(or +.BR \%stdscr ) +as its first argument. .PP -The \fBvwprintw\fP and \fBvw_printw\fP routines are analogous -to \fBvprintf\fP [see \fBprintf\fP(3)] -and perform a \fBwprintw\fP using a variable argument list. -The third argument is a \fBva_list\fP, a pointer to a -list of arguments, as defined in \fB\fP. +\fB\%vwprintw\fP +and +\fB\%vw_printw\fP are analogous to \fI\%vprintf\fP(3), +and perform a \fB\%wprintw\fP using a variable argument list. +The third argument is a \fI\%va_list\fP, +a pointer to a list of arguments, +as defined in \fI\%stdarg.h\fP. .SH RETURN VALUE -Routines that return an integer return \fBERR\fP upon failure and \fBOK\fP -(SVr4 only specifies "an integer value other than \fBERR\fP") upon successful -completion. +These functions return +.B ERR +upon failure and +.B OK +upon success. .PP -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 +.IR \%ncurses , +failure occurs if the library cannot allocate enough memory for the +buffer into which the output is formatted, +or if the window pointer +.I win +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. +Functions prefixed with \*(``mv\*('' first perform cursor movement and +fail if the position +.RI ( y , +.IR x ) +is outside the window boundaries. +.SH NOTES +No wide character counterpart functions are defined by the +\*(``wide\*('' +.I \%ncurses +configuration nor by any standard. +To format and write a wide-character string to a +.I curses +window, +consider using \fI\%swprintf\fP(3) and \fB\%waddwstr\fP(3X) or similar. +.SH PORTABILITY +X/Open Curses, +Issue 4 describes these functions. +It specifies no error conditions for them. +.PP +.I \%ncurses +defines \fB\%vw_printw\fP and \fB\%vwprintw\fP identically to support +legacy applications. +However, +the latter is obsolete. +.bP +X/Open Curses, +Issue 4 Version 2 (1996), +marked \fB\%vwprintw\fP as requiring \fI\%varargs.h\fP and +\*(``TO BE WITHDRAWN\*('', +and specified \fB\%vw_printw\fP using the \fI\%stdarg.h\fP interface. +.bP +X/Open Curses, Issue 5, Draft 2 +(December 2007) marked \fBvwprintw\fP (along with +\fBvwscanw\fP and the \fItermcap\fP interface) as withdrawn. +After incorporating review comments, +this became +X/Open Curses, Issue 7 (2009). +.bP +.I \%ncurses +provides \fB\%vwprintw\fP, +but marks it as deprecated. .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 , though that was available. -In 1991 (a couple of years after SVr4 was generally available, +While \fB\%printw\fP was implemented in 4BSD +(November 1980), +.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/src/lib/\ +.\" libcurses/printw.c +it was unused until 4.2BSD +(August 1983), +which employed it for games. +That early version of +.I curses +preceded the ANSI C standard of 1989. +It did not use \fI\%varargs.h\fP, +though that had been available since Seventh Edition Unix (1979). +.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/include/\ +.\" varargs.h +In 1991 +(a couple of years after SVr4 was generally available, and after the C standard was published), other developers updated the library, -using internally in 4.4BSD curses. +using \fI\%stdarg.h\fP internally in 4.4BSD +.IR curses . Even with this improvement, -BSD curses did not use function prototypes (or even declare -functions) in the header until 1992. +BSD +.I curses +did not use function prototypes +(nor even declare functions) +in \fI\%curses.h\fP until 1992. .PP -SVr2 documented -\fBprintw\fP, -\fBwprintw\fP -tersely as \*(``printf on \fIstdscr\fP\*('' and -tersely as \*(``printf on \fIwin\fP\*('', respectively. +SVr2 (1984) documented \fB\%printw\fP and \fB\%wprintw\fP tersely as +\*(``printf on \fB\%stdscr\fP\*('' and +\*(``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 , -and referring the reader to the manual pages for \fIvarargs\fP and -\fBvprintf\fP for detailed descriptions. +SVr3 (1987) added \fB\%mvprintw\fP and \fB\%mvwprintw\fP, +with a three-line summary asserting that they were analogous to +\fI\%printf\fP(3), +explaining that the string that \fI\%printf\fP(3) would write to the +standard output stream would instead be output using \fB\%waddstr\fP to +the given window. +SVr3 also implemented \fB\%vwprintw\fP, +describing its third parameter as a \fI\%va_list\fP, +defined in \fI\%varargs.h\fP, +and referred the reader to the manual pages for \fI\%varargs\fP and +\fI\%vprintf\fP for detailed descriptions. .PP -SVr4 added no new variations of \fBprintw\fP, -but provided for using or to define the \fBva_list\fP -type. +SVr4 (1989) introduced no new variations of \fI\%printw\fP, +but provided for using either \fI\%varargs.h\fP or \fI\%stdarg.h\fP to +define the \fI\%va_list\fP type. +.\" either header declares "va_list", but only one can be used .PP -X/Open Curses added \fBvw_printw\fP to replace \fBvwprintw\fP, -stating that its \fBva_list\fP definition requires . -.SH PORTABILITY -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\fP is marked TO BE WITHDRAWN, and is to be replaced by a function -\fBvw_printw\fP using the \fB\fP interface. -.bP -The Single Unix Specification, Version 2 states that -\fBvw_printw\fP is preferred to \fBvwprintw\fP since the latter requires -including \fB\fP, which -cannot be used in the same file as \fB\fP. -This implementation uses \fB\fP for both, -because that header is included in \fB. -.bP -X/Open Curses, Issue 5 (December 2007) marked \fBvwprintw\fP (along with -\fBvwscanw\fP and the termcap interface) as withdrawn. +X/Open Curses, Issue 4 (1995), +defined \fB\%vw_printw\fP to replace \fB\%vwprintw\fP, +stating that its \fI\%va_list\fP type is defined in \fI\%stdarg.h\fP. .SH SEE ALSO \fB\%curses\fP(3X), \fB\%curs_addstr\fP(3X), \fB\%curs_scanw\fP(3X), -\fB\%curs_termcap\fP(3X), \fB\%printf\fP(3), \fB\%vprintf\fP(3)