release.sh: restore -jJAILDIR option
[minix.git] / lib / libcurses / curses_addstr.3
blob8ed7199f2dbcafb93b3456cffd77ed25a140399b
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
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
95 .Dv stdscr
96 but will limit the number of characters added to be, at most,
97 .Fa len .
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.
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 .
115 The functions
116 .Fn mvaddstr ,
117 .Fn mwaddnstr ,
118 .Fn mvwaddstr
120 .Fn mvwaddnstr
121 are the same as the functions
122 .Fn addstr ,
123 .Fn waddstr ,
124 .Fn waddstr
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:
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.
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
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 .