ncurses 6.2 - patch 20210213

[ncurses.git] / man / curs_inwstr.3x

diff --git a/man/curs_inwstr.3x b/man/curs_inwstr.3x
index b345ce6e6fd5fafd41a9d2aa2da56c4c86490780..b3899c4b94f2eafbf53f35c91bf6828709e3bb1d 100644 (file)
--- a/man/curs_inwstr.3x
+++ b/man/curs_inwstr.3x
@@ -1,5 +1,6 @@
 .\"***************************************************************************
 .\"***************************************************************************

-.\" Copyright (c) 2002 Free Software Foundation, Inc.                        *
+.\" Copyright 2018-2019,2020 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            *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
 .\" copy of this software and associated documentation files (the            *


@@ -26,10 +27,13 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"

-.\" $Id: curs_inwstr.3x,v 1.2 2002/04/13 20:25:35 tom Exp $
-.TH curs_inwstr 3 ""
+.\" $Id: curs_inwstr.3x,v 1.14 2020/10/17 23:22:11 tom Exp $
+.TH curs_inwstr 3X ""
+.ie \n(.g .ds `` \(lq
+.el       .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el       .ds '' ''

 .SH NAME
 .SH NAME

-.PP

 \fBinwstr\fR,
 \fBinnwstr\fR,
 \fBwinwstr\fR,
 \fBinwstr\fR,
 \fBinnwstr\fR,
 \fBwinwstr\fR,


@@ -41,55 +45,62 @@
 .SH SYNOPSIS
 .nf
 \fB#include <curses.h> \fR
 .SH SYNOPSIS
 .nf
 \fB#include <curses.h> \fR

-
-\fBint inwstr(\fR\fBwchar_t *\fR\fIstr\fR\fB);\fR
-.br
-\fBint innwstr(\fR\fBwchar_t *\fR\fIstr\fR\fB, int \fR\fIn\fR\fB);\fR
+.sp
+\fBint inwstr(\fR\fBwchar_t *\fR\fIwstr\fR\fB);\fR

 .br
 .br

-\fBint winwstr(\fR\fBWINDOW *\fR\fIwin\fR\fB, wchar_t *\fR\fIstr\fR\fB);\fR
+\fBint innwstr(\fR\fBwchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR

 .br
 .br

-\fBint winnwstr(\fR\fBWINDOW *\fR\fIwin\fR\fB, wchar_t *\fR\fIstr\fR\fB, int \fR\fIn\fR\fB);\fR
+\fBint winwstr(\fR\fBWINDOW *\fR\fIwin\fR\fB, wchar_t *\fR\fIwstr\fR\fB);\fR

 .br
 .br

-\fBint mvinwstr(\fR\fBint \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wchar_t *\fR\fIstr\fR\fB);\fR
+\fBint winnwstr(\fR\fBWINDOW *\fR\fIwin\fR\fB, wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR
+.sp
+\fBint mvinwstr(\fR\fBint \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wchar_t *\fR\fIwstr\fR\fB);\fR

 .br
 .br

-\fBint mvinnwstr(\fR\fBint \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wchar_t *\fR\fIstr\fR\fB, int \fR\fIn\fR\fB);\fR
+\fBint mvinnwstr(\fR\fBint \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR

 .br
 .br

-\fBint mvwinwstr(\fR\fBWINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wchar_t *\fR\fIstr\fR\fB);\fR
+\fBint mvwinwstr(\fR\fBWINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wchar_t *\fR\fIwstr\fR\fB);\fR

 .br
 .br

-\fBint mvwinnwstr(\fR\fBWINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wchar_t *\fR\fIstr\fR\fB, int \fR\fIn\fR\fB);\fR
+\fBint mvwinnwstr(\fR\fBWINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR

 .fi
 .SH DESCRIPTION
 .fi
 .SH DESCRIPTION

-These routines return a string of \fBwchar_t\fR characters in \fIwstr\fR,
+.PP
+These routines return a string of \fBwchar_t\fR wide characters in \fIwstr\fR,

 extracted starting at the current cursor position in the named window.
 extracted starting at the current cursor position in the named window.

-Attributes are stripped from the characters.
-The four functions with \fIn\fR as the last argument return a leading substring at most
-\fIn\fR bytes long (exclusive of the trailing NUL).
-Transfer stops at the end of the current line, or when \fIn\fR bytes have
+.PP
+The four functions with \fIn\fR as the last argument return
+a leading substring at most \fIn\fR characters long
+(exclusive of the trailing NUL).
+Transfer stops at the end of the current line, or when \fIn\fR characters have

 been stored at the location referenced by \fIwstr\fR.
 .PP
 been stored at the location referenced by \fIwstr\fR.
 .PP

-If the size \fIn\fR is not large enough to store a complete character,
+If the size \fIn\fR is not large enough to store a complete complex character,

 an error is generated.
 .SH NOTES
 an error is generated.
 .SH NOTES

-Note that all routines except
+.PP
+All routines except

 \fBwinnwstr\fR
 may be macros.
 \fBwinnwstr\fR
 may be macros.

-.SH RETURN VALUES
+.PP
+Each cell in the window holds a complex character (i.e., base-
+and combining-characters) together with attributes and color.
+These functions store only the wide characters,
+ignoring attributes and color.
+Use \fBin_wchstr\fP to return the complex characters from a window.
+.SH RETURN VALUE

 All routines return
 \fBERR\fR
 All routines return
 \fBERR\fR

-upon failure. Upon
+upon failure.
+Upon

 successful completion, the *\fBinwstr\fR
 routines return
 \fBOK\fR, and the *\fBinnwstr\fR
 routines return the
 number of characters read into the string.
 successful completion, the *\fBinwstr\fR
 routines return
 \fBOK\fR, and the *\fBinnwstr\fR
 routines return the
 number of characters read into the string.

+.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 SEE ALSO
 .SH SEE ALSO

-Functions:

 \fBcurses\fR(3X),
 \fBcurs_instr\fR(3X),
 \fBcurs_in_wchstr\fR(3X)
 \fBcurses\fR(3X),
 \fBcurs_instr\fR(3X),
 \fBcurs_in_wchstr\fR(3X)

-.\"#
-.\"# The following sets edit modes for GNU EMACS
-.\"# Local Variables:
-.\"# mode:nroff
-.\"# fill-column:79
-.\"# End: