.\"***************************************************************************
-.\" Copyright (c) 2002-2005,2006 Free Software Foundation, Inc. *
+.\" Copyright 2018-2020,2021 Thomas E. Dickey *
+.\" Copyright 2002-2012,2017 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_in_wchstr.3x,v 1.6 2006/12/02 17:03:07 tom Exp $
+.\" $Id: curs_in_wchstr.3x,v 1.16 2021/12/25 21:49:32 tom Exp $
.TH curs_in_wchstr 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.na
.hy 0
.SH NAME
-\fBin_wchstr\fR,
-\fBin_wchnstr\fR,
-\fBwin_wchstr\fR,
-\fBwin_wchnstr\fR,
-\fBmvin_wchstr\fR,
-\fBmvin_wchnstr\fR,
-\fBmvwin_wchstr\fR,
-\fBmvwin_wchnstr\fR \- get an array of complex characters and renditions from a curses window
+\fBin_wchstr\fP,
+\fBin_wchnstr\fP,
+\fBwin_wchstr\fP,
+\fBwin_wchnstr\fP,
+\fBmvin_wchstr\fP,
+\fBmvin_wchnstr\fP,
+\fBmvwin_wchstr\fP,
+\fBmvwin_wchnstr\fP \- get an array of complex characters and renditions from a curses window
.ad
.hy
.SH SYNOPSIS
.nf
-\fB#include <curses.h>\fR
+\fB#include <curses.h>\fP
.sp
-\fBint in_wchstr(cchar_t *\fR\fIwchstr\fR\fB);\fR
+\fBint in_wchstr(cchar_t *\fP\fIwchstr\fP\fB);\fP
.br
-\fBint in_wchnstr(cchar_t *\fR\fIwchstr\fR\fB, int \fR\fIn\fR\fB);\fR
+\fBint in_wchnstr(cchar_t *\fP\fIwchstr\fP\fB, int \fP\fIn\fP\fB);\fP
.br
-\fBint win_wchstr(WINDOW *\fR\fIwin\fR\fB, cchar_t *\fR\fIwchstr\fR\fB);\fR
+\fBint win_wchstr(WINDOW *\fP\fIwin\fP\fB, cchar_t *\fP\fIwchstr\fP\fB);\fP
.br
-\fBint win_wchnstr(WINDOW *\fR\fIwin\fR\fB, cchar_t *\fR\fIwchstr\fR\fB, int \fR\fIn\fR\fB);\fR
-.br
-\fBint mvin_wchstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, cchar_t *\fR\fIwchstr\fR\fB);\fR
+\fBint win_wchnstr(WINDOW *\fP\fIwin\fP\fB, cchar_t *\fP\fIwchstr\fP\fB, int \fP\fIn\fP\fB);\fP
+.sp
+\fBint mvin_wchstr(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, cchar_t *\fP\fIwchstr\fP\fB);\fP
.br
-\fBint mvin_wchnstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, cchar_t *\fR\fIwchstr\fR\fB, int \fR\fIn\fR\fB);\fR
+\fBint mvin_wchnstr(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, cchar_t *\fP\fIwchstr\fP\fB, int \fP\fIn\fP\fB);\fP
.br
-\fBint mvwin_wchstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, cchar_t *\fR\fIwchstr\fR\fB);\fR
+\fBint mvwin_wchstr(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, cchar_t *\fP\fIwchstr\fP\fB);\fP
.br
-\fBint mvwin_wchnstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, cchar_t *\fR\fIwchstr\fR, int \fIn\fR\fB);\fR
+\fBint mvwin_wchnstr(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, cchar_t *\fP\fIwchstr\fP, int \fIn\fP\fB);\fP
.fi
.SH DESCRIPTION
-These functions return an array of complex characters in \fIwchstr\fR,
+These functions return an array of complex characters in \fIwchstr\fP,
starting at the current cursor position in the named window.
Attributes (rendition) are stored with the characters.
.PP
The
-\fBin_wchnstr\fR,
-\fBmvin_wchnstr\fR,
-\fBmvwin_wchnstr\fR
+\fBin_wchnstr\fP,
+\fBmvin_wchnstr\fP,
+\fBmvwin_wchnstr\fP
and
-\fBwin_wchnstr\fR
+\fBwin_wchnstr\fP
fill the array
with at most
-\fIn\fR
-\fBcchar_t\fR
+\fIn\fP
+\fBcchar_t\fP
elements.
.br
.SH NOTES
Note that all routines except
-\fBwin_wchnstr\fR
+\fBwin_wchnstr\fP
may be
macros.
.PP
Reading a line that overflows the array pointed to by
-\fIwchstr\fR
+\fIwchstr\fP
with
-\fBin_wchstr\fR,
-\fBmvin_wchstr\fR,
-\fBmvwin_wchstr\fR
+\fBin_wchstr\fP,
+\fBmvin_wchstr\fP,
+\fBmvwin_wchstr\fP
or
-\fBwin_wchstr\fR
-causes undefined results. Therefore, the use of
-\fBin_wchnstr\fR,
-\fBmvin_wchnstr\fR,
-\fBmvwin_wchnstr\fR, or
-\fBwin_wchnstr\fR
+\fBwin_wchstr\fP
+causes undefined results.
+Therefore, the use of
+\fBin_wchnstr\fP,
+\fBmvin_wchnstr\fP,
+\fBmvwin_wchnstr\fP, or
+\fBwin_wchnstr\fP
is recommended.
-.SH RETURN VALUES
+.SH RETURN VALUE
Upon successful completion, these functions return
-\fBOK\fR.
+\fBOK\fP.
Otherwise, they return
-\fBERR\fR.
+\fBERR\fP.
+.PP
+Functions with a \*(``mv\*('' prefix first perform a cursor movement using
+\fBwmove\fP, and return an error if the position is outside the window,
+or if the window pointer is null.
.SH PORTABILITY
The XSI Curses defines no error conditions.
This implementation checks for null pointers,
-returning ERR in that case.
+returning \fBERR\fP in that case.
.SH SEE ALSO
Functions:
-\fBcurses\fR(3X),
-\fBcurs_in_wch\fR(3X),
-\fBcurs_instr\fR(3X),
-\fBcurs_inwstr\fR(3X)
-\fBcurs_inchstr\fR(3X)
-.\"#
-.\"# The following sets edit modes for GNU EMACS
-.\"# Local Variables:
-.\"# mode:nroff
-.\"# fill-column:79
-.\"# End:
+\fBcurses\fP(3X),
+\fBcurs_in_wch\fP(3X),
+\fBcurs_instr\fP(3X),
+\fBcurs_inwstr\fP(3X)
+\fBcurs_inchstr\fP(3X)
projects / ncurses.git / blobdiff