diff options
Diffstat (limited to 'upstream/opensuse-tumbleweed/man3/printw.3ncurses')
| -rw-r--r-- | upstream/opensuse-tumbleweed/man3/printw.3ncurses | 201 |
1 files changed, 201 insertions, 0 deletions
diff --git a/upstream/opensuse-tumbleweed/man3/printw.3ncurses b/upstream/opensuse-tumbleweed/man3/printw.3ncurses new file mode 100644 index 00000000..c25762f9 --- /dev/null +++ b/upstream/opensuse-tumbleweed/man3/printw.3ncurses @@ -0,0 +1,201 @@ +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_printw.3x,v 1.47 2023/12/23 14:41:07 tom Exp $ +.TH printw 3NCURSES 2023-12-23 "ncurses 6.4" "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 +.. +.SH NAME +\fB\%printw\fP, +\fB\%wprintw\fP, +\fB\%mvprintw\fP, +\fB\%mvwprintw\fP, +\fB\%vwprintw\fP, +\fB\%vw_printw\fP \- +write formatted output to a \fIcurses\fR window +.SH SYNOPSIS +.nf +\fB#include <ncursesw/curses.h> +.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 +\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(3NCURSES) were used with +.I win +(or +.BR \%stdscr ) +as its first argument. +.PP +\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 +These functions return +.B ERR +upon failure and +.B OK +upon success. +.PP +In +.I \%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 \fB\%wmove\fP, +and fail if the position is outside the window. +.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(3NCURSES) 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 \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 \fI\%stdarg.h\fP internally in 4.4BSD +.I curses. +Even with this improvement, +BSD +.I curses +did not use function prototypes +(nor even declare functions) +in \fI\%curses.h\fP until 1992. +.PP +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 (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 (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, 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\%ncurses\fP(3NCURSES), +\fB\%addstr\fP(3NCURSES), +\fB\%scanw\fP(3NCURSES), +\fB\%printf\fP(3), +\fB\%vprintf\fP(3) |