'\" te
.\"  Copyright (c) 1990, 1995 by Mortice Kern Systems Inc.  All Rights Reserved  Portions Copyright (c) 1996, Sun Microsystems, Inc.  All Rights Reserved
.TH addnstr 3XCURSES "5 Jun 2002" "SunOS 5.11" "X/Open Curses Library Functions"
.SH NAME
addnstr, addstr, mvaddnstr, mvaddstr, mvwaddnstr, mvwaddstr, waddnstr, waddstr \- add a multi-byte character string (without rendition) to a window
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-I\fR /usr/xpg4/include \fB -L \fR /usr/xpg4/lib \e
\fB -R \fR /usr/xpg4/lib \fB -lcurses \fR [ \fIlibrary\fR... ]

\fBc89\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lcurses\fR [ \fIlibrary\fR ... ]
 
#include <curses.h>

\fBint\fR \fBaddnstr\fR(\fBconst char *\fR\fIstr\fR, \fBint\fR \fIn\fR);
.fi

.LP
.nf
\fBint\fR \fBaddstr\fR(\fBconst char *\fR\fIstr\fR);
.fi

.LP
.nf
\fBint\fR \fBmvaddnstr\fR(\fBint\fR \fIy\fR, \fBint\fR \fIx\fR, \fBconst char *\fR\fIstr\fR, \fBint\fR \fIn\fR);
.fi

.LP
.nf
\fBint\fR \fBmvaddstr\fR(\fBint\fR \fIy\fR, \fBint\fR \fIx\fR, \fBconst char *\fR\fIstr\fR);
.fi

.LP
.nf
\fBint\fR \fBmvwaddnstr\fR(\fBWINDOW *\fR\fIwin\fR, \fBint\fR \fIy\fR, \fBint\fR \fIx\fR, \fBconst char *\fR\fIstr\fR, \fBint\fR \fIn\fR);
.fi

.LP
.nf
\fBint\fR \fBmvwaddstr\fR(\fBWINDOW *\fR\fIwin\fR, \fBint\fR \fIy\fR, \fBint\fR \fIx\fR, \fBconst char *\fR\fIstr\fR);
.fi

.LP
.nf
\fBint\fR \fBwaddstr\fR(\fBWINDOW *\fR\fIwin\fR, \fBconst char *\fR\fIstr\fR);
.fi

.LP
.nf
\fBint\fR \fBwaddnstr\fR(\fBWINDOW *\fR\fIwin\fR, \fBconst char *\fR\fIstr\fR, \fBint\fR \fIn\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBaddstr()\fR function writes a null-terminated string of multi-byte characters to the \fBstdscr\fR window at the current cursor position. The \fBwaddstr()\fR function performs an identical action, but writes the  character to the window specified by \fIwin\fR.  The \fBmvaddstr()\fR and \fBmvwaddstr()\fR functions write the string to the  position indicated by the \fIx\fR (column) and \fIy\fR (row) parameters (the  former to the \fBstdscr\fR window; the latter to window \fIwin\fR).
.sp
.LP
The \fBaddnstr()\fR, \fBwaddnstr()\fR, \fBmvaddnstr()\fR, and  \fBmvwaddnstr()\fR functions are similar but write at most \fIn\fR characters  to the window. If \fIn\fR is less than 0, the entire string is written.
.sp
.LP
All of these functions advance the cursor after writing the string.
.sp
.LP
These functions are functionally equivalent to calling the corresponding  function from the \fBaddch\fR(3XCURSES) set of functions once for each character in  the string.  Refer to the \fBcurses\fR(3XCURSES) man page for a complete description of  special character handling and of the interaction between the window rendition (or background character and rendition) and the character written.
.sp
.LP
Note that these functions differ from the \fBaddchstr()\fR set of functions in that the \fBaddchstr\fR(3XCURSES) functions copy the string as is (without  combining each character with the window rendition or the background character  and rendition.
.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fIstr\fR\fR
.ad
.RS 7n
.rt  
Is a pointer to the character string that is to be written to the window.
.RE

.sp
.ne 2
.mk
.na
\fB\fIn\fR\fR
.ad
.RS 7n
.rt  
Is the maximum number of characters to be copied from \fIstr\fR. If \fIn\fR is less than 0, the entire string is written or as much of it as fits on the line.
.RE

.sp
.ne 2
.mk
.na
\fB\fIy\fR\fR
.ad
.RS 7n
.rt  
Is the y (row) coordinate of the starting position of \fIstr\fR in the window.
.RE

.sp
.ne 2
.mk
.na
\fB\fIx\fR\fR
.ad
.RS 7n
.rt  
Is the x (column) coordinate of the starting position of \fIstr\fR in  the window.
.RE

.sp
.ne 2
.mk
.na
\fB\fIwin\fR\fR
.ad
.RS 7n
.rt  
Is a pointer to the window in which the string is to be written.
.RE

.SH RETURN VALUES
.sp
.LP
On success, these functions return \fBOK\fR. Otherwise, they return \fBERR\fR.
.SH ERRORS
.sp
.LP
None.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
MT-LevelUnsafe
_
StandardSee \fBstandards\fR(5).
.TE

.SH SEE ALSO
.sp
.LP
\fBaddch\fR(3XCURSES), \fBaddchstr\fR(3XCURSES), \fBcurses\fR(3XCURSES), \fBlibcurses\fR(3XCURSES), \fBattributes\fR(5), \fBstandards\fR(5)