man/curs_addstr.3x

   1 .\"***************************************************************************
   2 .\" Copyright 2019-2023,2024 Thomas E. Dickey                                *
   3 .\" Copyright 1998-2012,2017 Free Software Foundation, Inc.                  *
   4 .\"                                                                          *
   5 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
   6 .\" copy of this software and associated documentation files (the            *
   7 .\" "Software"), to deal in the Software without restriction, including      *
   8 .\" without limitation the rights to use, copy, modify, merge, publish,      *
   9 .\" distribute, distribute with modifications, sublicense, and/or sell       *
  10 .\" copies of the Software, and to permit persons to whom the Software is    *
  11 .\" furnished to do so, subject to the following conditions:                 *
  12 .\"                                                                          *
  13 .\" The above copyright notice and this permission notice shall be included  *
  14 .\" in all copies or substantial portions of the Software.                   *
  15 .\"                                                                          *
  16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  17 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  19 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  20 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  21 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  22 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  23 .\"                                                                          *
  24 .\" Except as contained in this notice, the name(s) of the above copyright   *
  25 .\" holders shall not be used in advertising or otherwise to promote the     *
  26 .\" sale, use or other dealings in this Software without prior written       *
  27 .\" authorization.                                                           *
  28 .\"***************************************************************************
  29 .\"
  30 .\" $Id: curs_addstr.3x,v 1.43 2024/04/13 22:14:06 tom Exp $
  31 .TH curs_addstr 3X 2024-04-13 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
  32 .ie \n(.g \{\
  33 .ds `` \(lq
  34 .ds '' \(rq
  35 .\}
  36 .el \{\
  37 .ie t .ds `` ``
  38 .el   .ds `` ""
  39 .ie t .ds '' ''
  40 .el   .ds '' ""
  41 .\}
  42 .
  43 .de bP
  44 .ie n  .IP \(bu 4
  45 .el    .IP \(bu 2
  46 ..
  47 .SH NAME
  48 \fB\%addstr\fP,
  49 \fB\%addnstr\fP,
  50 \fB\%waddstr\fP,
  51 \fB\%waddnstr\fP,
  52 \fB\%mvaddstr\fP,
  53 \fB\%mvaddnstr\fP,
  54 \fB\%mvwaddstr\fP,
  55 \fB\%mvwaddnstr\fP \-
  56 add a string to a \fIcurses\fR window and advance the cursor
  57 .SH SYNOPSIS
  58 .nf
  59 \fB#include <curses.h>
  60 .PP
  61 \fBint addstr(const char *\fIstr\fP);
  62 \fBint mvaddstr(int \fIy\fP, int \fIx\fP, const char *\fIstr\fP);
  63 \fBint mvwaddstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const char *\fIstr\fP);
  64 \fBint waddstr(WINDOW *\fIwin\fP, const char *\fIstr\fP);
  65 .PP
  66 \fBint addnstr(const char *\fIstr\fP, int \fIn\fP);
  67 \fBint mvaddnstr(int \fIy\fP, int \fIx\fP, const char *\fIstr\fP, int \fIn\fP);
  68 \fBint mvwaddnstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const char *\fIstr\fP, int \fIn\fP);
  69 \fBint waddnstr(WINDOW *\fIwin\fP, const char *\fIstr\fP, int \fIn\fP);
  70 .fi
  71 .SH DESCRIPTION
  72 .B waddstr
  73 writes the characters of the (null-terminated) string
  74 .I str
  75 to the window
  76 .IR win .
  77 Its process is similar to calling \fB\%waddch\fP(3X) for each
  78 .I char
  79 in
  80 .IR str .
  81 Control characters are processed as in \fB\%waddch\fP(3X).
  82 .PP
  83 .B waddnstr
  84 writes at most
  85 .I n
  86 characters,
  87 or until a terminating null character occurs in
  88 .IR str .
  89 If
  90 .I n
  91 is \-1,
  92 .B
  93 .B waddnstr
  94 writes the entire string.
  95 .PP
  96 \fB\%ncurses\fP(3X) describes the variants of these functions.
  97 .SH RETURN VALUE
  98 These functions return
  99 .B OK
 100 on success and
 101 .B ERR
 102 on failure.
 103 .PP
 104 X/Open Curses does not specify any error conditions.
 105 .I \%ncurses
 106 returns an error
 107 .bP
 108 if the window pointer is
 109 .BR NULL ,
 110 .bP
 111 if the string pointer is
 112 .BR NULL ,
 113 or
 114 .bP
 115 if an internal \fB\%waddch\fP(3X) call returns an error.
 116 .PP
 117 Functions with a \*(``mv\*('' prefix first perform cursor movement using
 118 \fB\%wmove\fP(3X) and fail if the position is outside the window,
 119 or
 120 (for \*(``mvw\*('' functions)
 121 if the
 122 .I \%WINDOW
 123 pointer is null.
 124 .SH NOTES
 125 All of these functions except \fBwaddnstr\fP may be macros.
 126 .SH PORTABILITY
 127 X/Open Curses,
 128 Issue 4 describes these functions.
 129 .SH SEE ALSO
 130 \fB\%curs_addwstr\fP(3X) describes comparable functions of the
 131 .I \%ncurses
 132 library in its wide-character configuration
 133 .RI ( \%ncursesw ).
 134 .PP
 135 \fB\%curses\fP(3X),
 136 \fB\%curs_addch\fP(3X),
 137 \fB\%curs_addchstr\fP(3X)