X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_printw.3x;h=4980517275d5832dfad709251a4ccb31410cd7e1;hp=2f0152f3a77b027dd47a5f004904f6b45c1234ba;hb=fae162795e065e5901068152e91f2962b6b247f3;hpb=0eb88fc5281804773e2a0c7a488a4452463535ce diff --git a/man/curs_printw.3x b/man/curs_printw.3x index 2f0152f3..49805172 100644 --- a/man/curs_printw.3x +++ b/man/curs_printw.3x @@ -1,5 +1,6 @@ .\"*************************************************************************** -.\" Copyright (c) 1998 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 * @@ -26,51 +27,128 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_printw.3x,v 1.8 1998/12/26 20:09:36 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 -\fBprintw\fR, \fBwprintw\fR, \fBmvprintw\fR, -\fBmvwprintw\fR, \fBvwprintw\fR - print formatted output in -\fBcurses\fR windows +\fBprintw\fR, +\fBwprintw\fR, +\fBmvprintw\fR, +\fBmvwprintw\fR, +\fBvwprintw\fR, \fBvw_printw\fR \- print formatted output in \fBcurses\fR windows +.ad +.hy .SH SYNOPSIS \fB#include \fR - -\fBint printw(char *fmt\fR [\fB, arg\fR] \fB...);\fR +.sp +\fBint printw(const char *\fP\fIfmt\fP\fB, ...);\fR .br -\fBint wprintw(WINDOW *win, char *fmt\fR [\fB, arg\fR] \fB...);\fR +\fBint wprintw(WINDOW *\fP\fIwin\fP\fB, const char *\fP\fIfmt\fP\fB, ...);\fR .br -\fBint mvprintw(int y, int x, char *fmt\fR [\fB, arg\fR] \fB...);\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,\fR - \fBchar *fmt\fR [\fB, arg]\fR ...); - -\fB#include \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, char *fmt, 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(3S)]. 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. - -The \fBvwprintw\fR routine is analogous to \fBvprintf\fR [see -\fBprintf\fR(3S)] and performs a \fBwprintw\fR using a variable -argument list. The third argument is a \fBva_list\fR, a pointer to a -list of arguments, as defined in \fB\fR. +.PP +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 +list of arguments, as defined in \fB\fR. .SH RETURN VALUE Routines that return an integer return \fBERR\fR upon failure and \fBOK\fR (SVr4 only specifies "an integer value other than \fBERR\fR") upon successful completion. +.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. +.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 , 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 internally in 4.4BSD curses. +Even with this improvement, +BSD curses did not use function prototypes (or even declare +functions) in the 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 , +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 or 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 . .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\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\fR, which +cannot be used in the same file as \fB\fR. +This implementation uses \fB\fR 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. .SH SEE ALSO -\fBcurses\fR(3X), \fBprintf\fR(3S), \fBvprintf(3S)\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).