lib/libcurses/curses_print.3

   1 .\"     $NetBSD: curses_print.3,v 1.7 2011/04/06 08:38:43 jruoho Exp $
   2 .\"
   3 .\" Copyright (c) 2002
   4 .\"     Brett Lymn (blymn@NetBSD.org, brett_lymn@yahoo.com.au)
   5 .\"
   6 .\" This code is donated to the NetBSD Foundation by the Author.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. The name of the Author may not be used to endorse or promote
  17 .\"    products derived from this software without specific prior written
  18 .\"    permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"
  33 .Dd April 6, 2011
  34 .Dt CURSES_PRINT 3
  35 .Os
  36 .Sh NAME
  37 .Nm curses_print ,
  38 .Nm printw ,
  39 .Nm wprintw ,
  40 .Nm mvprintw ,
  41 .Nm mvwprintw ,
  42 .Nm unctrl
  43 .Nd curses print formatted strings on windows routines
  44 .Sh LIBRARY
  45 .Lb libcurses
  46 .Sh SYNOPSIS
  47 .In curses.h
  48 .Ft int
  49 .Fn printw "const char *fmt" "..."
  50 .Ft int
  51 .Fn wprintw "WINDOW *win" "const char *fmt" "..."
  52 .Ft int
  53 .Fn mvprintw "int y" "int x" "const char *fmt" "..."
  54 .Ft int
  55 .Fn mvwprintw "WINDOW *win" "int y" "int x" "const char *fmt" "..."
  56 .Ft char *
  57 .Fn unctrl "chtype ch"
  58 .Sh DESCRIPTION
  59 These functions print formatted strings on
  60 .Dv stdscr
  61 or on the specified window.
  62 .Pp
  63 The
  64 .Fn printw
  65 function formats and prints its arguments on
  66 .Dv stdscr .
  67 The behavior is deliberately similar to that of
  68 .Xr printf 3 ,
  69 but, notably, the return value differs.
  70 .Pp
  71 The
  72 .Fn wprintw
  73 function is the same as the
  74 .Fn printw
  75 function, excepting that the resulting output is printed on the window
  76 specified by
  77 .Fa win .
  78 .Pp
  79 The
  80 .Fn mvprintw
  81 and
  82 .Fn mvwprintw
  83 functions are the same as the
  84 .Fn printw
  85 and
  86 .Fn wprintw
  87 functions, respectively, excepting that
  88 .Fn wmove
  89 is called to move the cursor to the position specified by
  90 .Fa y ,
  91 .Fa x
  92 before the output is printed on the window.
  93 .Pp
  94 The
  95 .Fn unctrl
  96 function returns a printable string representation of the character
  97 .Fa ch .
  98 If
  99 .Fa ch
 100 is a control character then it will be converted to the form ^Y.
 101 .Sh RETURN VALUES
 102 Functions returning pointers will return
 103 .Dv NULL
 104 if an error is detected.
 105 The functions that return an int will return one of the following
 106 values:
 107 .Pp
 108 .Bl -tag -width ERR -offset indent
 109 .It Er OK
 110 The function completed successfully.
 111 .It Er ERR
 112 An error occurred in the function.
 113 .El
 114 .Sh SEE ALSO
 115 .Xr curses_cursor 3 ,
 116 .Xr curses_scanw 3 ,
 117 .Xr printf 3
 118 .Sh STANDARDS
 119 The
 120 .Nx
 121 Curses library complies with the X/Open Curses specification, part of the
 122 Single Unix Specification.
 123 .Sh HISTORY
 124 The Curses package appeared in
 125 .Bx 4.0 .