'\" t
.\"***************************************************************************
-.\" Copyright 2018-2022,2023 Thomas E. Dickey *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
.\" Copyright 1998-2010,2017 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_inch.3x,v 1.33 2023/08/19 20:46:33 tom Exp $
-.TH curs_inch 3X 2023-08-19 "ncurses 6.4" "Library calls"
-.ie \n(.g .ds `` \(lq
-.el .ds `` ``
-.ie \n(.g .ds '' \(rq
-.el .ds '' ''
+.\" $Id: curs_inch.3x,v 1.54 2024/05/18 20:07:52 tom Exp $
+.TH curs_inch 3X 2024-05-18 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
.ie n .IP \(bu 4
.el .IP \(bu 2
..
.SH NAME
-\fBinch\fP,
-\fBwinch\fP,
-\fBmvinch\fP,
-\fBmvwinch\fP \- get a character and attributes from a \fBcurses\fP window
+\fB\%inch\fP,
+\fB\%winch\fP,
+\fB\%mvinch\fP,
+\fB\%mvwinch\fP \-
+get a \fIcurses\fR character from a window
.SH SYNOPSIS
-\fB#include <curses.h>\fP
-.sp
-\fBchtype inch(void);\fP
-.br
-\fBchtype winch(WINDOW *\fIwin\fB);\fR
-.sp
-\fBchtype mvinch(int \fIy\fB, int \fIx\fB);\fR
-.br
-\fBchtype mvwinch(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB);\fR
-.SH DESCRIPTION
-These routines return the character, of type \fBchtype\fP, at the current
-position in the named window.
-If any attributes are set for that position,
-their values are OR'ed into the value returned.
-Constants defined in
-\fB<curses.h>\fP can be used with the \fB&\fP (logical AND) operator to
-extract the character or attributes alone.
-.
-.SS Attributes
-The following bit-masks may be AND-ed with characters returned by \fBwinch\fP.
+.nf
+\fB#include <curses.h>
.PP
-.TS
-l l .
-\fBA_CHARTEXT\fP Bit-mask to extract character
-\fBA_ATTRIBUTES\fP Bit-mask to extract attributes
-\fBA_COLOR\fP Bit-mask to extract color-pair field information
-.TE
+\fBchtype inch(void);
+\fBchtype winch(WINDOW * \fIwin\fP);
+\fBchtype mvinch(int \fIy\fP, int \fIx\fP);
+\fBchtype mvwinch(WINDOW * \fIwin\fP, int \fIy\fP, int \fIx\fP);
+.fi
+.SH DESCRIPTION
+.B \%winch
+returns the
+.I curses
+character,
+including its attributes and color pair identifier,
+at the cursor position in the window
+.IR win "."
+Subsection \*(``Video Attributes\*('' of \fB\%attron\fP(3X) explains
+how to extract these data from a
+.IR chtype "."
+\fB\%ncurses\fP(3X) describes the variants of this function.
.SH RETURN VALUE
-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.
+These functions return
+.B OK
+on success and
+.B ERR
+on failure.
.PP
-The \fBwinch\fP function does not return an error if the window contains
-characters larger than 8-bits (255).
-Only the low-order 8 bits of the character are used by \fBwinch\fP.
+In
+.IR \%ncurses ","
+.B \%winch
+returns
+.B ERR
+if
+.I win
+is
+.BR NULL "."
+.PP
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
.SH NOTES
-Note that all of these routines may be macros.
+.BR \%inch ,
+.BR \%mvinch ,
+and
+.B \%mvwinch
+may be implemented as macros.
+.PP
+These functions do not return an error if the window contains cells of
+.I curses
+complex characters;
+that is,
+if they contain characters with codes wider than eight bits
+(or greater than 255 as an unsigned decimal integer).
+They instead extract only the low-order eight bits of the character code
+from the cell.
.SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4.
+X/Open Curses,
+Issue 4 describes these functions.
+It specifies no error conditions for them.
+.SH HISTORY
+The original
+.I curses
+in 4BSD (1980) defined
+.I \%winch
+as a macro accessing the
+.I \%WINDOW
+structure member representing character cell data,
+at that time a
+.IR char ","
+containing only a 7-bit ASCII character code
+and a \*(``standout\*(`` attribute bit,
+the only one the library supported.
.PP
-Very old systems (before standardization) provide a different function
-with the same name:
-.bP
-The \fBwinch\fP function was part of the original BSD curses library,
-which stored a 7-bit character combined with the \fIstandout\fP attribute.
-.IP
-In BSD curses, \fBwinch\fP returned only the character (as an integer)
-with the \fIstandout\fP attribute removed.
-.bP
-System V curses added support for several video attributes which
-could be combined with characters in the window.
-.IP
-Reflecting this improvement, the function was altered to return the
-character combined with all video attributes in a \fBchtype\fP value.
+SVr2
+.I curses
+(1984)
+extended this approach,
+widening the character code to eight bits
+and permitting several attributes to be combined with it
+by storing them together in a
+.IR \%chtype ","
+an alias of
+.IR "unsigned short" "."
+.\" ...indirectly through a preprocessor macro named CHTYPE, encouraging
+.\" builders to change the typedef to `char` or `long` as desired. More
+.\" innocent times with respect to ABI compatibility concerns... --GBR
+Because a macro was used,
+its value was not type-checked
+as a function return value could have been.
+Goodheart documented SVr3 (1987)
+.I \%winch
+as returning an
+.IR int "."
+.\" ...but the implementation remained unchanged.
+SVr3.1's (1987)
+.I \%chtype
+became an alias of
+.IR "unsigned long" ","
+using 16 bits for the character code and
+widening the type in practical terms to 32 bits,
+as 64-bit Unix systems were not yet in wide use,
+and fixed-width integral types would not be standard until ISO C99.
+.\" Cray's UNICOS was 1985 (how many shops had Crays?). DEC OSF/1 for
+.\" the Alpha arrived in 1993. --GBR
+SVr3.2 (1988)
+added a 6-bit color pair identifier alongside the attributes.
.PP
-X/Open Curses does not specify
-the size and layout of attributes, color and character values in
-\fBchtype\fP; it is implementation-dependent.
-This implementation uses 8 bits for character values.
-An application using more bits, e.g., a Unicode value,
-should use the wide-character equivalents to these functions.
+X/Open Curses does not specify the sizes of the character code or
+color pair identifier,
+nor the quantity of attribute bits,
+in
+.IR chtype ";"
+these are implementation-dependent.
+.I \%ncurses
+uses eight bits for the character code.
+An application requiring a wider character type,
+for instance to represent Unicode,
+should use the wide-character counterparts of these functions.
.SH SEE ALSO
-.TP 5
-\fBcurses\fP(3X)
-gives an overview of the WINDOW and \fBchtype\fP data types.
-.TP 5
-\fBcurs_attr\fP(3X)
-goes into more detail, pointing out portability problems and
-constraints on the use of \fBchtype\fP for returning window information.
-.TP 5
-\fBcurs_in_wch\fP(3X)
-describes comparable functions for the wide-character (ncursesw) library.
+\fB\%curs_in_wch\fP(3X) describes comparable functions of the
+.I \%ncurses
+library in its wide-character configuration
+.RI ( \%ncursesw ).
+.PP
+\fB\%curses\fP(3X),
+\fB\%curs_instr\fP(3X)
projects / ncurses.git / blobdiff