lib/libcurses/curses_addstr.3

   1 .\"     $NetBSD: curses_addstr.3,v 1.4 2003/05/21 21:22:15 jdc 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 May 21, 2003
  34 .Dt CURSES_ADDSTR 3
  35 .Os
  36 .Sh NAME
  37 .Nm curses_addstr ,
  38 .Nm addstr ,
  39 .Nm waddstr ,
  40 .Nm addnstr ,
  41 .Nm waddnstr ,
  42 .Nm mvaddstr ,
  43 .Nm mvwaddstr ,
  44 .Nm mvaddnstr ,
  45 .Nm mvwaddnstr
  46 .Nd curses add character strings to windows routines
  47 .Sh LIBRARY
  48 .Lb libcurses
  49 .Sh SYNOPSIS
  50 .In curses.h
  51 .Ft int
  52 .Fn addstr "const char *string"
  53 .Ft int
  54 .Fn waddstr "WINDOW *win" "const char *string"
  55 .Ft int
  56 .Fn mvaddstr "int y" "int x" "const char *string"
  57 .Ft int
  58 .Fn mvwaddstr "WINDOW *win" "int y" "int x" "const char *string"
  59 .Ft int
  60 .Fn addnstr "const char *string" "int len"
  61 .Ft int
  62 .Fn waddnstr "WINDOW *win" "const char *string" "int len"
  63 .Ft int
  64 .Fn mvaddnstr "int y" "int x" "const char *string" "int len"
  65 .Ft int
  66 .Fn mvwaddnstr "WINDOW *win" "int y" "int x" "const char *string" "int len"
  67 .Sh DESCRIPTION
  68 These functions add character strings to
  69 .Dv stdscr
  70 or to the specified window.
  71 .Pp
  72 The
  73 .Fn addstr
  74 function
  75 will add the characters passed in
  76 .Fa string
  77 to
  78 .Dv stdscr
  79 starting at the current cursor position.
  80 Any background attributes currently set on
  81 .Dv stdscr
  82 will be applied to the added character.
  83 The
  84 .Fn waddstr
  85 function does the same as
  86 .Fn addstr
  87 but adds the string to the window specified by
  88 .Fn win .
  89 .Pp
  90 The
  91 .Fn addnstr
  92 function will add the contents of
  93 .Fa string
  94 to
  95 .Dv stdscr
  96 but will limit the number of characters added to be, at most,
  97 .Fa len .
  98 If
  99 .Fa len
 100 is \-1 then
 101 .Fa addnstr
 102 will add the number of characters contained in the null terminated string
 103 .Fa string .
 104 Any background attributes currently set on
 105 .Dv stdscr
 106 will be applied to the added character.
 107 The
 108 .Fn waddnstr
 109 function
 110 does the same as
 111 .Fa addnstr
 112 but adds the string to the window specified by
 113 .Fa win .
 114 .Pp
 115 The functions
 116 .Fn mvaddstr ,
 117 .Fn mwaddnstr ,
 118 .Fn mvwaddstr
 119 and
 120 .Fn mvwaddnstr
 121 are the same as the functions
 122 .Fn addstr ,
 123 .Fn waddstr ,
 124 .Fn waddstr
 125 and
 126 .Fn waddnstr ,
 127 respectively, excepting that
 128 .Fn wmove
 129 is called to move the cursor to the position specified by
 130 .Fa y ,
 131 .Fa x
 132 before the string is added to the window.
 133 .Sh RETURN VALUES
 134 Functions returning pointers will return
 135 .Dv NULL
 136 if an error is detected.
 137 The functions that return an int will return one of the following
 138 values:
 139 .Pp
 140 .Bl -tag -width ERR -compact
 141 .It Er OK
 142 The function completed successfully.
 143 .It Er ERR
 144 An error occurred in the function.
 145 .El
 146 .Sh SEE ALSO
 147 .Xr curses_addch 3 ,
 148 .Xr curses_addchstr 3 ,
 149 .Xr curses_attributes 3 ,
 150 .Xr curses_cursor 3 ,
 151 .Xr curses_inch 3
 152 .Sh STANDARDS
 153 The
 154 .Nx
 155 Curses library complies with the X/Open Curses specification, part of the
 156 Single Unix Specification.
 157 .Sh HISTORY
 158 The Curses package appeared in
 159 .Bx 4.0 .