lib/libcurses/curses_addchstr.3

   1 .\"     $NetBSD: curses_addchstr.3,v 1.3 2008/04/30 13:10:51 martin Exp $
   2 .\"
   3 .\" Copyright (c) 2003
   4 .\"     Douwe Kiela (virtus@wanadoo.nl)
   5 .\" Copyright (c) 2003 The NetBSD Foundation, Inc.
   6 .\" All rights reserved.
   7 .\"
   8 .\" This code is derived from software contributed to The NetBSD Foundation
   9 .\" by Douwe Kiela (virtus@wanadoo.nl).
  10 .\"
  11 .\" Redistribution and use in source and binary forms, with or without
  12 .\" modification, are permitted provided that the following conditions
  13 .\" are met:
  14 .\" 1. Redistributions of source code must retain the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer.
  16 .\" 2. Redistributions in binary form must reproduce the above copyright
  17 .\"    notice, this list of conditions and the following disclaimer in the
  18 .\"    documentation and/or other materials provided with the distribution.
  19 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  20 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  21 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  22 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  23 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  24 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  25 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  26 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  27 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  28 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  29 .\" POSSIBILITY OF SUCH DAMAGE.
  30 .\"
  31 .\"
  32 .Dd May 21, 2003
  33 .Dt CURSES_ADDCHSTR 3
  34 .Os
  35 .Sh NAME
  36 .Nm curses_addchstr ,
  37 .Nm addchstr ,
  38 .Nm waddchstr ,
  39 .Nm addchnstr ,
  40 .Nm waddchnstr ,
  41 .Nm mvaddchstr ,
  42 .Nm mvwaddchstr ,
  43 .Nm mvaddchnstr ,
  44 .Nm mvwaddchnstr
  45 .Nd curses add character strings to windows routines
  46 .Sh LIBRARY
  47 .Lb libcurses
  48 .Sh SYNOPSIS
  49 .In curses.h
  50 .Ft int
  51 .Fn addchstr "const chtype *chstr"
  52 .Ft int
  53 .Fn waddchstr "WINDOW *win" "const chtype *chstr"
  54 .Ft int
  55 .Fn mvaddchstr "int y" "int x" "const chtype *chstr"
  56 .Ft int
  57 .Fn mvwaddchstr "WINDOW *win" "int y" "int x" "const chtype *chstr"
  58 .Ft int
  59 .Fn addchnstr "const chtype *chstr" "int n"
  60 .Ft int
  61 .Fn waddchnstr "WINDOW *win" "const chtype *chstr" "int n"
  62 .Ft int
  63 .Fn mvaddchnstr "int y" "int x" "const chtype *chstr" "int n"
  64 .Ft int
  65 .Fn mvwaddchnstr "WINDOW *win" "int y" "int x" "const chtype *chstr" "int n"
  66 .Sh DESCRIPTION
  67 These functions add character strings and attributes to
  68 .Dv stdscr
  69 or to the specified window.
  70 .Pp
  71 The
  72 .Fn addchstr
  73 function will add the characters and their attributes passed in
  74 .Fa chstr
  75 to
  76 .Dv stdscr
  77 starting at the current cursor position.
  78 Any character attributes set in
  79 .Fa chstr
  80 will be merged with the background attributes currently set on
  81 .Dv stdscr .
  82 The
  83 .Fn waddstr
  84 function does the same as
  85 .Fn addchstr
  86 but adds the string to the window specified by
  87 .Fn win .
  88 .Pp
  89 The
  90 .Fn addchnstr
  91 function will add the contents of
  92 .Fa string
  93 to
  94 .Dv stdscr
  95 but will limit the number of characters added to be, at most,
  96 .Fa n .
  97 If
  98 .Fa n
  99 is \-1 then
 100 .Fa addchnstr
 101 will add the number of characters contained in the null terminated string
 102 .Fa chstr .
 103 Any character attributes set in
 104 .Fa chstr
 105 will be merged with the background attributes currently set on
 106 .Dv stdscr .
 107 .Pp
 108 The
 109 .Fn waddchnstr
 110 function does the same as
 111 .Fa addchnstr
 112 but adds the string to the window specified by
 113 .Fa win .
 114 .Pp
 115 The functions
 116 .Fn mvaddchstr ,
 117 .Fn mwaddchnstr ,
 118 .Fn mvwaddchstr
 119 and
 120 .Fn mvwaddchnstr
 121 are the same as the functions
 122 .Fn addchstr ,
 123 .Fn waddchstr ,
 124 .Fn waddchstr
 125 and
 126 .Fn waddchnstr ,
 127 respectively, except 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 The functions will return one of the following values:
 135 .Pp
 136 .Bl -tag -width ERR -compact
 137 .It Er OK
 138 The function completed successfully.
 139 .It Er ERR
 140 An error occurred in the function.
 141 .El
 142 .Sh SEE ALSO
 143 .Xr curses_addch 3 ,
 144 .Xr curses_addstr 3 ,
 145 .Xr curses_attributes 3 ,
 146 .Xr curses_cursor 3 ,
 147 .Xr curses_inch 3
 148 .Sh STANDARDS
 149 The
 150 .Nx
 151 Curses library complies with the X/Open Curses specification, part of the
 152 Single Unix Specification.
 153 .Sh HISTORY
 154 These functions first appeared in
 155 .Nx 2.0 .