1.\" $NetBSD: curses_addstr.3,v 1.1 2002/10/21 13:55:09 blymn 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 August 12, 2002 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.Fd #include \*[Lt]curses.h\*[Gt] 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 68These functions add character strings to 69.Dv stdscr 70or to the specified window. 71.Pp 72The 73.Fn addstr 74function 75will add the characters passed in 76.Fa string 77to 78.Dv stdscr 79starting at the current cursor position. 80Any background attributes currently set on 81.Dv stdscr 82will be applied to the added character. 83The 84.Fn waddstr 85function does the same as 86.Fn addstr 87but adds the string to the window specified by 88.Fn win . 89.Pp 90The 91.Fn addnstr 92function will add the contents of 93.Fa string 94to 95.Dv stdscr 96but will limit the number of characters added to be, at most, 97.Fa len . 98If 99.Fa len 100is \-1 then 101.Fa addnstr 102will add the number of characters contained in the null terminated string 103.Fa string . 104Any background attributes currently set on 105.Dv stdscr 106will be applied to the added character. 107The 108.Fn waddnstr 109function 110does the same as 111.Fa addnstr 112but adds the string to the window specified by 113.Fa win . 114.Pp 115The functions 116.Fn mvaddstr , 117.Fn mwaddnstr , 118.Fn mvwaddstr 119and 120.Fn mvwaddnstr 121are the same as the functions 122.Fn addstr , 123.Fn waddstr , 124.Fn waddstr 125and 126.Fn waddnstr , 127respectively, excepting that 128.Fn wmove 129is called to move the cursor to the position specified by 130.Fa y , 131.Fa x 132before the string is added to the window. 133.Sh RETURN VALUES 134Functions returning pointers will return 135.Dv NULL 136if an error is detected. 137The functions that return an int will return one of the following 138values: 139.Pp 140.Bl -tag -width ERR -compact 141.It Er OK 142The function completed successfully. 143.It Er ERR 144An error occurred in the function. 145.El 146.Sh SEE ALSO 147.Xr curses_addch 3 , 148.Xr curses_attributes 3 , 149.Xr curses_cursor 3 , 150.Xr curses_inch 3 151.Sh STANDARDS 152The 153.Nx 154Curses library complies with the X/Open Curses specification, part of the 155Single Unix Specification. 156.Sh HISTORY 157The Curses package appeared in 158.Bx 4.0 . 159