From cea297eb34d2361e79529034397465068ae34ecd Mon Sep 17 00:00:00 2001 From: Xin LI Date: Sat, 1 Mar 2014 00:40:26 +0000 Subject: Vendor import of ncurses 5.9 20140222 snapshot. --- man/Makefile.in | 8 +- man/clear.1 | 11 +- man/curs_add_wch.3x | 6 +- man/curs_add_wchstr.3x | 64 +++++--- man/curs_addchstr.3x | 50 +++--- man/curs_addstr.3x | 38 +++-- man/curs_addwstr.3x | 35 +++-- man/curs_attr.3x | 59 ++++++-- man/curs_bkgrnd.3x | 6 +- man/curs_border_set.3x | 6 +- man/curs_get_wch.3x | 6 +- man/curs_get_wstr.3x | 6 +- man/curs_getcchar.3x | 6 +- man/curs_getch.3x | 12 +- man/curs_in_wchstr.3x | 6 +- man/curs_initscr.3x | 17 ++- man/curs_inopts.3x | 63 +++++++- man/curs_ins_wstr.3x | 6 +- man/curs_inwstr.3x | 6 +- man/curs_mouse.3x | 24 ++- man/curs_opaque.3x | 13 +- man/curs_overlay.3x | 26 ++-- man/curs_sp_funcs.3x | 6 +- man/curs_termcap.3x | 61 +++++++- man/curs_terminfo.3x | 211 ++++++++++++++++++-------- man/curs_threads.3x | 8 +- man/curs_util.3x | 112 +++++++++++--- man/curs_variables.3x | 9 +- man/form_field.3x | 6 +- man/form_variables.3x | 6 +- man/infocmp.1m | 176 +++++++++++++++------ man/manhtml.aliases | 16 ++ man/manhtml.externs | 24 +++ man/menu_items.3x | 6 +- man/ncurses.3x | 148 +++++++++++++----- man/resizeterm.3x | 16 +- man/tabs.1 | 24 +-- man/term.7 | 6 +- man/term_variables.3x | 14 +- man/terminfo.head | 15 +- man/terminfo.tail | 404 ++++++++++++++++++++++++++++++++----------------- man/tic.1m | 200 ++++++++++++++++-------- man/toe.1m | 21 ++- man/tput.1 | 35 +++-- man/tset.1 | 101 ++++++++----- 45 files changed, 1454 insertions(+), 645 deletions(-) create mode 100644 man/manhtml.aliases create mode 100644 man/manhtml.externs (limited to 'man') diff --git a/man/Makefile.in b/man/Makefile.in index 82a67065c322..ad40bc53a2c2 100644 --- a/man/Makefile.in +++ b/man/Makefile.in @@ -1,6 +1,6 @@ -# $Id: Makefile.in,v 1.45 2010/11/27 21:45:27 tom Exp $ +# $Id: Makefile.in,v 1.47 2013/08/04 20:23:20 tom Exp $ ############################################################################## -# Copyright (c) 1998-2007,2010 Free Software Foundation, Inc. # +# Copyright (c) 1998-2010,2013 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 "Software"), # @@ -41,8 +41,12 @@ DESTDIR = @DESTDIR@ srcdir = @srcdir@ prefix = @prefix@ exec_prefix = @exec_prefix@ +datarootdir = @datarootdir@ datadir = @datadir@ mandir = @mandir@ +includesubdir = @includesubdir@ + +INCLUDEDIR = $(DESTDIR)$(includedir)$(includesubdir) INSTALL = @INSTALL@ INSTALL_DATA = @INSTALL_DATA@ diff --git a/man/clear.1 b/man/clear.1 index b70d37e80c09..d8e24e5bb926 100644 --- a/man/clear.1 +++ b/man/clear.1 @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 1998-2010,2013 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 * @@ -26,7 +26,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: clear.1,v 1.8 2010/12/04 18:36:44 tom Exp $ +.\" $Id: clear.1,v 1.10 2013/06/22 22:22:11 tom Exp $ .TH @CLEAR@ 1 "" .ds n 5 .SH NAME @@ -35,9 +35,10 @@ \fB@CLEAR@\fR .br .SH DESCRIPTION -\fB@CLEAR@\fR clears your screen if this is possible. It looks in the -environment for the terminal type and then in the \fBterminfo\fR database to -figure out how to clear the screen. +\fB@CLEAR@\fR clears your screen if this is possible, +including its scrollback buffer (if the extended "E3" capability is defined). +\fB@CLEAR@\fR looks in the environment for the terminal type and then in the +\fBterminfo\fR database to determine how to clear the screen. .PP \fB@CLEAR@\fR ignores any command-line parameters that may be present. .SH SEE ALSO diff --git a/man/curs_add_wch.3x b/man/curs_add_wch.3x index 26319a8ef909..b7164ada0e2b 100644 --- a/man/curs_add_wch.3x +++ b/man/curs_add_wch.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 2001-2010,2011 Free Software Foundation, Inc. * +.\" Copyright (c) 2001-2011,2012 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 * @@ -26,7 +26,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_add_wch.3x,v 1.14 2011/01/15 15:27:43 tom Exp $ +.\" $Id: curs_add_wch.3x,v 1.15 2012/11/03 23:03:59 tom Exp $ .TH curs_add_wch 3X "" .de bP .IP \(bu 4 @@ -176,7 +176,7 @@ WACS_D_HLINE 0x2550 - double horizontal line WACS_D_VLINE 0x2551 | double vertical line WACS_D_PLUS 0x256c + double large plus or crossover .TE -.SH RETURN VALUES +.SH RETURN VALUE .PP All routines return the integer \fBERR\fR upon failure and \fBOK\fR on success. .PP diff --git a/man/curs_add_wchstr.3x b/man/curs_add_wchstr.3x index 957adc025724..37e3df614b16 100644 --- a/man/curs_add_wchstr.3x +++ b/man/curs_add_wchstr.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 2002-2005,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 2002-2010,2012 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 * @@ -26,8 +26,13 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_add_wchstr.3x,v 1.9 2010/12/04 18:36:44 tom Exp $ +.\" $Id: curs_add_wchstr.3x,v 1.10 2012/11/03 22:54:43 tom Exp $ .TH curs_add_wchstr 3X "" +.de bP +.IP \(bu 4 +.. +.na +.hy 0 .SH NAME \fBadd_wchstr\fR, \fBadd_wchnstr\fR, @@ -37,10 +42,12 @@ \fBmvadd_wchnstr\fR, \fBmvwadd_wchstr\fR, \fBmvwadd_wchnstr\fR \- add an array of complex characters (and attributes) to a curses window +.ad +.hy .SH SYNOPSIS -.B #include -.PP .nf +\fB#include \fR +.PP \fBint add_wchstr(const cchar_t *\fR\fIwchstr\fR\fB);\fR .br \fBint add_wchnstr(const cchar_t *\fR\fIwchstr\fR\fB, int \fR\fIn\fR\fB);\fR @@ -58,38 +65,53 @@ \fBint mvwadd_wchnstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const cchar_t *\fR\fIwchstr\fR\fB, int \fR\fIn\fR\fB);\fR .fi .SH DESCRIPTION -These routines copy the array of complex characters \fIwchstr\fR -into the window image structure at and after the current cursor position. -The four routines with \fIn\fR as the last -argument copy at most \fIn\fR elements, but no more than will fit on the line. +These functions copy the (null-terminated) +array of complex characters \fIwchstr\fR +into the window image structure +starting at the current cursor position. +The four functions with \fIn\fR as the last +argument copy at most \fIn\fR elements, +but no more than will fit on the line. If \fBn\fR=\fB\-1\fR then the whole array is copied, to the maximum number of characters that will fit on the line. .PP The window cursor is \fInot\fR advanced. -These routines work faster than \fBwaddnstr\fR. -On the other hand, they do not perform checking +These functions work faster than \fBwaddnstr\fR. +On the other hand: +.bP +they do not perform checking (such as for the newline, backspace, or carriage return characters), +.bP they do not advance the current cursor position, -they do not expand other control characters to ^-escapes, -and they truncate the string if it crosses the right margin, +.bP +they do not expand other control characters to ^-escapes, and +.bP +they truncate the string if it crosses the right margin, rather than wrapping it around to the new line. .PP -These routines end successfully +These functions end successfully on encountering a null \fIcchar_t\fR, or when they have filled the current line. If a complex character cannot completely fit at the end of the current line, the remaining columns are filled with the background character and rendition. -.SH NOTES -All functions except \fBwadd_wchnstr\fR may be macros. -.SH RETURN VALUES -All routines return the integer \fBERR\fR upon failure and \fBOK\fR on success. +.SH RETURN VALUE +All functions return the integer \fBERR\fR upon failure and \fBOK\fR on success. +.PP +X/Open does not define any error conditions. +This implementation returns an error +if the window pointer is null. .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 NOTES +All functions except \fBwadd_wchnstr\fR may be macros. .SH PORTABILITY -All these entry points are described in the XSI Curses standard, Issue 4. +These entry points are described in the XSI Curses standard, Issue 4. .SH SEE ALSO -\fBcurses\fR(3X), -\fBcurs_addchstr\fR(3X), -\fBcurs_addwstr\fR(3X) +\fBcurs_addwstr\fR(3X), +\fBcurses\fR(3X). +.PP +Comparable functions in the narrow-character (ncurses) library are +described in +\fBcurs_addchstr\fR(3X). diff --git a/man/curs_addchstr.3x b/man/curs_addchstr.3x index 1547219f8309..08536e330260 100644 --- a/man/curs_addchstr.3x +++ b/man/curs_addchstr.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 1998-2010,2012 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 * @@ -26,8 +26,11 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_addchstr.3x,v 1.15 2010/12/04 18:36:44 tom Exp $ +.\" $Id: curs_addchstr.3x,v 1.16 2012/11/03 22:54:43 tom Exp $ .TH curs_addchstr 3X "" +.de bP +.IP \(bu 4 +.. .na .hy 0 .SH NAME @@ -42,6 +45,7 @@ .ad .hy .SH SYNOPSIS +.nf \fB#include \fR .PP \fBint addchstr(const chtype *chstr);\fR @@ -59,24 +63,33 @@ \fBint mvwaddchstr(WINDOW *win, int y, int x, const chtype *chstr);\fR .br \fBint mvwaddchnstr(WINDOW *win, int y, int x, const chtype *chstr, int n);\fR +.fi .SH DESCRIPTION -These routines copy \fIchstr\fR into the window image structure at and after -the current cursor position. The four routines with \fIn\fR as the last -argument copy at most \fIn\fR elements, but no more than will fit on the line. -If \fBn\fR=\fB\-1\fR then the whole string is copied, to the maximum number of -characters that will fit on the line. +These functions copy the (null-terminated) +\fIchstr\fR array +into the window image structure +starting at the current cursor position. +The four functions with \fIn\fR as the last +argument copy at most \fIn\fR elements, +but no more than will fit on the line. +If \fBn\fR=\fB\-1\fR then the whole array is copied, +to the maximum number of characters that will fit on the line. .PP -The window cursor is \fInot\fR advanced, and these routines work faster than -\fBwaddnstr\fR. On the other hand, they do not perform any kind of checking -(such as for the newline, backspace, or carriage return characters), they do not -advance the current cursor position, they do not expand other control characters -to ^-escapes, and they truncate the string if it crosses the right margin, +The window cursor is \fInot\fR advanced. +These functions work faster than \fBwaddnstr\fR. +On the other hand: +.bP +they do not perform checking +(such as for the newline, backspace, or carriage return characters), +.bP +they do not advance the current cursor position, +.bP +they do not expand other control characters to ^-escapes, and +.bP +they truncate the string if it crosses the right margin, rather than wrapping it around to the new line. -.SH RETURN VALUES -All routines return the integer \fBERR\fR upon failure and \fBOK\fR on success -(the SVr4 manuals specify only "an integer value other than \fBERR\fR") upon -successful completion, unless otherwise noted in the preceding routine -descriptions. +.SH RETURN VALUE +All functions return the integer \fBERR\fR upon failure and \fBOK\fR on success. .PP X/Open does not define any error conditions. This implementation returns an error @@ -86,10 +99,11 @@ 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 NOTES -Note that all routines except \fBwaddchnstr\fR may be macros. +All functions except \fBwaddchnstr\fR may be macros. .SH PORTABILITY These entry points are described in the XSI Curses standard, Issue 4. .SH SEE ALSO +\fBcurs_addstr\fR(3X), \fBcurses\fR(3X). .PP Comparable functions in the wide-character (ncursesw) library are diff --git a/man/curs_addstr.3x b/man/curs_addstr.3x index a52619ea7f2a..b1cb1cc25c15 100644 --- a/man/curs_addstr.3x +++ b/man/curs_addstr.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 1998-2005,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 1998-2010,2012 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 * @@ -26,8 +26,11 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_addstr.3x,v 1.16 2010/12/04 18:36:44 tom Exp $ +.\" $Id: curs_addstr.3x,v 1.17 2012/11/03 22:57:31 tom Exp $ .TH curs_addstr 3X "" +.de bP +.IP \(bu 4 +.. .na .hy 0 .SH NAME @@ -62,34 +65,37 @@ \fBint mvwaddnstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const char *\fR\fIstr, int \fR\fIn\fR\fB);\fR .fi .SH DESCRIPTION -These routines write the characters of the (null-terminated) character string +These functions write the (null-terminated) character string \fIstr\fR on the given window. It is similar to calling \fBwaddch\fR once for each character in the string. -The four routines with \fIn\fR as the last argument -write at most \fIn\fR characters. -If \fIn\fR is \-1, then the entire string will be added, -up to the maximum number of characters that will fit on the line, +.PP +The \fImv\fR functions perform cursor movement once, before writing any +characters. +Thereafter, the cursor is advanced as a side-effect of writing to the window. +.PP +The four functions with \fIn\fR as the last argument +write at most \fIn\fR characters, or until a terminating null is reached. +If \fIn\fR is \-1, then the entire string will be added. .SH RETURN VALUE -All routines return the integer \fBERR\fR upon failure and \fBOK\fR on success -(the SVr4 manuals specify only "an integer value other than \fBERR\fR") upon -successful completion. +All functions return the integer \fBERR\fR upon failure and \fBOK\fR on success. .PP X/Open does not define any error conditions. This implementation returns an error +.bP if the window pointer is null or +.bP if the string pointer is null or +.bP if the corresponding calls to \fBwaddch\fP return an error. .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 NOTES -Note that all of these routines except \fBwaddstr\fR and \fBwaddnstr\fR may be -macros. +All of these functions except \fBwaddnstr\fR may be macros. .SH PORTABILITY -All these entry points are described in the XSI Curses standard, Issue 4. The -XSI errors EILSEQ and EOVERFLOW, associated with extended-level conformance, -are not yet detected. +These functions are described in the XSI Curses standard, Issue 4. .SH SEE ALSO -\fBcurses\fR(3X), \fBcurs_addch\fR(3X). +\fBcurses\fR(3X), +\fBcurs_addch\fR(3X). diff --git a/man/curs_addwstr.3x b/man/curs_addwstr.3x index 4e10d304fd61..835cb34010fc 100644 --- a/man/curs_addwstr.3x +++ b/man/curs_addwstr.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 2002-2006,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 2002-2010,2012 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 * @@ -26,8 +26,11 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_addwstr.3x,v 1.10 2010/12/04 18:36:44 tom Exp $ +.\" $Id: curs_addwstr.3x,v 1.11 2012/11/03 22:57:31 tom Exp $ .TH curs_addwstr 3X "" +.de bP +.IP \(bu 4 +.. .na .hy 0 .SH NAME @@ -62,31 +65,39 @@ \fBint mvwaddnwstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR .fi .SH DESCRIPTION -These routines write the characters of the +These functions write the characters of the (null-terminated) \fBwchar_t\fR character string \fIwstr\fR on the given window. It is similar to constructing a \fBcchar_t\fR for each wchar_t in the string, then calling \fBwadd_wch\fR for the resulting \fBcchar_t\fR. .PP -The \fImv\fR routines perform cursor movement once, before writing any +The \fImv\fR functions perform cursor movement once, before writing any characters. Thereafter, the cursor is advanced as a side-effect of writing to the window. .PP -The four routines with \fIn\fR as the last argument -write at most \fIn\fR \fBwchar_t\fR characters. -If \fIn\fR is \-1, then the entire string will be added, -up to the maximum number of characters that will fit on the line, +The four functions with \fIn\fR as the last argument +write at most \fIn\fR \fBwchar_t\fR characters, or until a terminating null is reached. -.SH RETURN VALUES -All routines return the integer \fBERR\fR upon failure and \fBOK\fR on success. +If \fIn\fR is \-1, then the entire string will be added. +.SH RETURN VALUE +All functions return the integer \fBERR\fR upon failure and \fBOK\fR on success. +.PP +X/Open does not define any error conditions. +This implementation returns an error +.bP +if the window pointer is null or +.bP +if the string pointer is null or +.bP +if the corresponding calls to \fBwadd_wch\fP return an error. .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 NOTES -Note that all of these routines except \fBwaddnwstr\fR may be macros. +All of these functions except \fBwaddnwstr\fR may be macros. .SH PORTABILITY -All these entry points are described in the XSI Curses standard, Issue 4. +These functions are described in the XSI Curses standard, Issue 4. .SH SEE ALSO \fBcurses\fR(3X), \fBcurs_add_wch\fR(3X) diff --git a/man/curs_attr.3x b/man/curs_attr.3x index 67740f9e2a72..7a0d1588d516 100644 --- a/man/curs_attr.3x +++ b/man/curs_attr.3x @@ -1,6 +1,6 @@ '\" t .\"*************************************************************************** -.\" Copyright (c) 1998-2009,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 1998-2010,2013 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 * @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_attr.3x,v 1.36 2010/12/04 18:36:44 tom Exp $ +.\" $Id: curs_attr.3x,v 1.39 2013/09/21 20:39:49 Sven.Joachim Exp $ .TH curs_attr 3X "" .na .hy 0 @@ -164,9 +164,12 @@ The following video attributes, defined in \fB\fR, can be passed to the routines \fBattron\fR, \fBattroff\fR, and \fBattrset\fR, or OR'd with the characters passed to \fBaddch\fR. .PP +.RS .TS -center ; +l l +_ _ _ l l . +\fIName\fR \fIDescription\fR \fBA_NORMAL\fR Normal display (no highlight) \fBA_STANDOUT\fR Best highlighting mode of the terminal. \fBA_UNDERLINE\fR Underlining @@ -177,9 +180,30 @@ l l . \fBA_PROTECT\fR Protected mode \fBA_INVIS\fR Invisible or blank mode \fBA_ALTCHARSET\fR Alternate character set +\fBA_ITALIC\fR Italics (non-X/Open extension) \fBA_CHARTEXT\fR Bit-mask to extract a character \fBCOLOR_PAIR(\fR\fIn\fR\fB)\fR Color-pair number \fIn\fR .TE +.RE +.PP +These video attributes are supported by \fBattr_on\fP and related functions +(which also support the attributes recognized by \fBattron\fP, etc.): +.RS +.TS +l l +_ _ _ +l l . +\fIName\fR \fIDescription\fR +\fBWA_HORIZONTAL\fR Horizontal highlight +\fBWA_LEFT\fR Left highlight +\fBWA_LOW\fR Low highlight +\fBWA_RIGHT\fR Right highlight +\fBWA_TOP\fR Top highlight +\fBWA_VERTICAL\fR Vertical highlight +.TE +.RE +.PP +For consistency .PP The following macro is the reverse of \fBCOLOR_PAIR(\fR\fIn\fR\fB)\fR: .PP @@ -214,19 +238,27 @@ The XSI Curses standard states that whether the traditional functions SVr4 curses, these functions correctly manipulate all other highlights (specifically, \fBA_ALTCHARSET\fR, \fBA_PROTECT\fR, and \fBA_INVIS\fR). .PP +This implementation provides the \fBA_ITALIC\fP attribute for terminals +which have the \fIenter_italics_mode\fP (sitm) and \fIexit_italics_mode\fP (ritm) capabilities. +Italics are not mentioned in X/Open Curses. +Unlike the other video attributes, \fBI_ITALIC\fP is unrelated +to the \fIset_attributes\fP capabilities. +This implementation makes the assumption that +\fIexit_attribute_mode\fP may also reset italics. +.PP XSI Curses added the new entry points, \fBattr_get\fR, \fBattr_on\fR, \fBattr_off\fR, \fBattr_set\fR, \fBwattr_on\fR, \fBwattr_off\fR, \fBwattr_get\fR, \fBwattr_set\fR. These are intended to work with a new series of highlight macros prefixed with \fBWA_\fR. +The older macros have direct counterparts in the newer set of names: .PP -Older versions of this library did not force an update of the screen -when changing the attributes. -Use \fBtouchwin\fR to force the screen to match the updated attributes. -.PP +.RS .ne 9 .TS -center ; +l l +_ _ _ l l . +\fIName\fR \fIDescription\fR \fBWA_NORMAL\fR Normal display (no highlight) \fBWA_STANDOUT\fR Best highlighting mode of the terminal. \fBWA_UNDERLINE\fR Underlining @@ -236,6 +268,11 @@ l l . \fBWA_BOLD\fR Extra bright or bold \fBWA_ALTCHARSET\fR Alternate character set .TE +.RE +.PP +Older versions of this library did not force an update of the screen +when changing the attributes. +Use \fBtouchwin\fR to force the screen to match the updated attributes. .PP The XSI curses standard specifies that each pair of corresponding \fBA_\fR and \fBWA_\fR-using functions operates on the same current-highlight @@ -243,8 +280,10 @@ information. .PP The XSI standard extended conformance level adds new highlights \fBA_HORIZONTAL\fR, \fBA_LEFT\fR, \fBA_LOW\fR, \fBA_RIGHT\fR, \fBA_TOP\fR, -\fBA_VERTICAL\fR (and corresponding \fBWA_\fR macros for each) which this -implementation does not yet support. +\fBA_VERTICAL\fR (and corresponding \fBWA_\fR macros for each). +As of August 2013, +no known terminal provides these highlights +(i.e., via the \fBsgr1\fP capability). .SH RETURN VALUE All routines return the integer \fBOK\fR on success, or \fBERR\fP on failure. .PP diff --git a/man/curs_bkgrnd.3x b/man/curs_bkgrnd.3x index 43112a79ab79..08ea59f10217 100644 --- a/man/curs_bkgrnd.3x +++ b/man/curs_bkgrnd.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 2002-2006,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 2002-2010,2012 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 * @@ -26,7 +26,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_bkgrnd.3x,v 1.4 2010/12/04 18:49:20 tom Exp $ +.\" $Id: curs_bkgrnd.3x,v 1.5 2012/11/03 23:03:59 tom Exp $ .TH curs_bkgrnd 3X "" .SH NAME \fBbkgrnd\fR, @@ -89,7 +89,7 @@ Note that \fBbkgrndset\fR, and \fBgetbkgrnd\fR may be macros. -.SH RETURN VALUES +.SH RETURN VALUE The \fBbkgrndset\fR and \fBwbkgrndset\fR routines do not return a value. .PP Upon successful completion, the other functions return \fBOK\fR. diff --git a/man/curs_border_set.3x b/man/curs_border_set.3x index 8f831dd9b4cc..c9621ac74b35 100644 --- a/man/curs_border_set.3x +++ b/man/curs_border_set.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 2002-2010,2011 Free Software Foundation, Inc. * +.\" Copyright (c) 2002-2011,2012 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 * @@ -26,7 +26,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_border_set.3x,v 1.10 2011/01/15 12:56:18 tom Exp $ +.\" $Id: curs_border_set.3x,v 1.11 2012/11/03 23:03:59 tom Exp $ .TH curs_border_set 3X "" .na .hy 0 @@ -187,7 +187,7 @@ Note that \fBvline_set\fR may be macros. .br -.SH RETURN VALUES +.SH RETURN VALUE .PP Upon successful completion, these functions return \fBOK\fR. diff --git a/man/curs_get_wch.3x b/man/curs_get_wch.3x index fe49849a2ecd..df9bc6a6e6c6 100644 --- a/man/curs_get_wch.3x +++ b/man/curs_get_wch.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 2002-2006,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 2002-2010,2012 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 * @@ -26,7 +26,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_get_wch.3x,v 1.7 2010/08/14 23:31:42 tom Exp $ +.\" $Id: curs_get_wch.3x,v 1.8 2012/11/03 23:03:59 tom Exp $ .TH curs_get_wch 3X "" .SH NAME \fBget_wch\fR, @@ -132,7 +132,7 @@ is typed, the program may produce undesirable results. .PP All functions except \fBwget_wch\fR and \fBunget_wch\fR may be macros. -.SH RETURN VALUES +.SH RETURN VALUE When \fBget_wch\fR, \fBwget_wch\fR, diff --git a/man/curs_get_wstr.3x b/man/curs_get_wstr.3x index 9beb1773ca61..2a3fb3ce27bf 100644 --- a/man/curs_get_wstr.3x +++ b/man/curs_get_wstr.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 2002-2006,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 2002-2010,2012 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 * @@ -26,7 +26,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_get_wstr.3x,v 1.8 2010/12/04 18:36:44 tom Exp $ +.\" $Id: curs_get_wstr.3x,v 1.9 2012/11/03 23:03:59 tom Exp $ .TH curs_get_wstr 3X "" .na .hy 0 @@ -144,7 +144,7 @@ These functions cannot return \fBKEY_\fR values because there is no way to distinguish a \fBKEY_\fR value from a valid \fBwchar_t\fR value. .PP All of these routines except \fBwgetn_wstr\fR may be macros. -.SH RETURN VALUES +.SH RETURN VALUE All of these functions return \fBOK\fR upon successful completion. Otherwise, they return \fBERR\fR. .PP diff --git a/man/curs_getcchar.3x b/man/curs_getcchar.3x index 1b878f313c2d..a974c738a8c3 100644 --- a/man/curs_getcchar.3x +++ b/man/curs_getcchar.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 2001-2009,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 2001-2010,2012 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 * @@ -26,7 +26,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_getcchar.3x,v 1.15 2010/12/04 18:36:44 tom Exp $ +.\" $Id: curs_getcchar.3x,v 1.16 2012/11/03 23:03:59 tom Exp $ .TH curs_getcchar 3X "" .de bP .IP \(bu 4 @@ -116,7 +116,7 @@ Currently, an application must provide a null pointer as \fIopts\fP. The \fIwcval\fP argument may be a value generated by a call to \fBsetcchar\fP or by a function that has a \fBcchar_t\fP output argument. If \fIwcval\fP is constructed by any other means, the effect is unspecified. -.SH RETURN VALUES +.SH RETURN VALUE .PP When \fIwch\fP is a null pointer, \fBgetcchar\fP returns the number of wide characters referenced by diff --git a/man/curs_getch.3x b/man/curs_getch.3x index 2d5d6fda785f..a8b2ffea1868 100644 --- a/man/curs_getch.3x +++ b/man/curs_getch.3x @@ -1,6 +1,6 @@ '\" t .\"*************************************************************************** -.\" Copyright (c) 1998-2010,2011 Free Software Foundation, Inc. * +.\" Copyright (c) 1998-2011,2012 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 * @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_getch.3x,v 1.36 2011/01/22 19:38:51 tom Exp $ +.\" $Id: curs_getch.3x,v 1.37 2012/07/07 20:04:56 tom Exp $ .TH curs_getch 3X "" .na .hy 0 @@ -237,14 +237,14 @@ See \fBresizeterm\fR(3X) for more details about \fBKEY_RESIZE\fP, and All routines return the integer \fBERR\fR upon failure and an integer value other than \fBERR\fR (\fBOK\fR in the case of ungetch()) upon successful completion. -.RS +.RS 3 .TP 5 \fBungetch\fP -returns an error +returns ERR if there is no more room in the FIFO. -.TP 5 +.TP \fBwgetch\fP -returns an error +returns ERR if the window pointer is null, or if its timeout expires without having any data. .RE diff --git a/man/curs_in_wchstr.3x b/man/curs_in_wchstr.3x index 042abfd6051d..f92968779623 100644 --- a/man/curs_in_wchstr.3x +++ b/man/curs_in_wchstr.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 2002-2006,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 2002-2010,2012 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 * @@ -26,7 +26,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_in_wchstr.3x,v 1.8 2010/12/04 18:36:44 tom Exp $ +.\" $Id: curs_in_wchstr.3x,v 1.9 2012/11/03 23:03:59 tom Exp $ .TH curs_in_wchstr 3X "" .na .hy 0 @@ -98,7 +98,7 @@ causes undefined results. Therefore, the use of \fBmvwin_wchnstr\fR, or \fBwin_wchnstr\fR is recommended. -.SH RETURN VALUES +.SH RETURN VALUE Upon successful completion, these functions return \fBOK\fR. Otherwise, they return diff --git a/man/curs_initscr.3x b/man/curs_initscr.3x index 83a01eafb4e9..0dceb973d1e6 100644 --- a/man/curs_initscr.3x +++ b/man/curs_initscr.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 1998-2005,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 1998-2012,2013 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 * @@ -26,8 +26,12 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_initscr.3x,v 1.17 2010/12/04 18:36:58 tom Exp $ +.\" $Id: curs_initscr.3x,v 1.19 2013/07/20 19:34:14 tom Exp $ .TH curs_initscr 3X "" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' .na .hy 0 .SH NAME @@ -121,10 +125,19 @@ Old versions of curses, e.g., BSD 4.4, may have returned a null pointer from \fBinitscr\fR when an error is detected, rather than exiting. It is safe but redundant to check the return value of \fBinitscr\fR in XSI Curses. +.PP +If the TERM variable is missing or empty, \fBinitscr\fP uses the +value \*(``unknown\*('', +which normally corresponds to a terminal entry with the \fIgeneric\fP +(\fIgn\fP) capability. +Generic entries are detected by \fBsetupterm\fP(3X) and cannot be +used for full-screen operation. +Other implementations may handle a missing/empty TERM variable differently. .SH SEE ALSO \fBcurses\fR(3X), \fBcurs_kernel\fR(3X), \fBcurs_refresh\fR(3X), \fBcurs_slk\fR(3X), +\fBcurs_terminfo\fR(3X), \fBcurs_util\fR(3X), \fBcurs_variables\fR(3X). diff --git a/man/curs_inopts.3x b/man/curs_inopts.3x index aecb2e3714f8..2e637ce30b64 100644 --- a/man/curs_inopts.3x +++ b/man/curs_inopts.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 1998-2005,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 1998-2012,2013 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 * @@ -26,8 +26,12 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_inopts.3x,v 1.15 2010/12/04 18:40:45 tom Exp $ +.\" $Id: curs_inopts.3x,v 1.18 2013/07/20 19:42:02 tom Exp $ .TH curs_inopts 3X "" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' .na .hy 0 .SH NAME @@ -188,11 +192,13 @@ Hence, these routines provide the same functionality as \fBnodelay\fR, plus the additional capability of being able to block for only \fIdelay\fR milliseconds (where \fIdelay\fR is positive). .PP -The \fBcurses\fR library does ``line-breakout optimization'' by looking for -typeahead periodically while updating the screen. If input is found, -and it is coming from a tty, the current update is postponed until -\fBrefresh\fR or \fBdoupdate\fR is called again. This allows faster -response to commands typed in advance. Normally, the input FILE +The \fBcurses\fR library does \*(``line-breakout optimization\*('' +by looking for typeahead periodically while updating the screen. +If input is found, and it is coming from a tty, +the current update is postponed until +\fBrefresh\fR or \fBdoupdate\fR is called again. +This allows faster response to commands typed in advance. +Normally, the input FILE pointer passed to \fBnewterm\fR, or \fBstdin\fR in the case that \fBinitscr\fR was used, will be used to do this typeahead checking. The \fBtypeahead\fR routine specifies that the file descriptor @@ -223,6 +229,42 @@ initializes the terminal state. BSD curses differed from this slightly; it left the echo bit on at initialization, but the BSD \fBraw\fR call turned it off as a side-effect. For best portability, set echo or noecho explicitly just after initialization, even if your program remains in cooked mode. +.PP +When \fBkeypad\fP is first enabled, +ncurses loads the key-definitions for the current terminal description. +If the terminal description includes extended string capabilities, +e.g., from using the \fB\-x\fP option of @TIC@, +then ncurses also defines keys for the capabilities whose names +begin with "k". +The corresponding keycodes are generated and (depending on previous +loads of terminal descriptions) may differ from one execution of a +program to the next. +The generated keycodes are recognized by the \fBkeyname\fP function +(which will then return a name beginning with "k" denoting the +terminfo capability name rather than "K", used for curses key-names). +On the other hand, an application can use \fBdefine_key\fP to establish +a specific keycode for a given string. +This makes it possible for an application to check for an extended +capability's presence with \fItigetstr\fP, +and reassign the keycode to match its own needs. +.PP +Low-level applications can use \fBtigetstr\fP to obtain the definition +of any particular string capability. +Higher-level applications which use the curses \fBwgetch\fP +and similar functions to return keycodes rely upon the order in which +the strings are loaded. +If more than one key definition has the same string value, +then \fBwgetch\fP can return only one keycode. +Most curses implementations (including ncurses) +load key definitions in the order +defined by the array of string capability names. +The last key to be loaded determines the keycode which will be returned. +In ncurses, you may also have extended capabilities interpreted as +key definitions. +These are loaded after the predefined keys, +and if a capability's value is the same as a previously-loaded +key definition, +the later definition is the one used. .SH NOTES Note that \fBecho\fR, \fBnoecho\fR, \fBhalfdelay\fR, \fBintrflush\fR, \fBmeta\fR, \fBnodelay\fR, \fBnotimeout\fR, \fBnoqiflush\fR, @@ -233,4 +275,9 @@ they attempt to restore to normal (`cooked') mode from raw and cbreak modes respectively. Mixing raw/noraw and cbreak/nocbreak calls leads to tty driver control states that are hard to predict or understand; it is not recommended. .SH SEE ALSO -\fBcurses\fR(3X), \fBcurs_getch\fR(3X), \fBcurs_initscr\fR(3X), \fBtermio\fR(7) +\fBcurses\fR(3X), +\fBcurs_getch\fR(3X), +\fBcurs_initscr\fR(3X), +\fBcurs_util\fR(3X), +\fBdefine_key\fR(3X), +\fBtermio\fR(7) diff --git a/man/curs_ins_wstr.3x b/man/curs_ins_wstr.3x index d01654533f73..12479b0d9306 100644 --- a/man/curs_ins_wstr.3x +++ b/man/curs_ins_wstr.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 2002-2005,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 2002-2010,2012 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 * @@ -26,7 +26,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_ins_wstr.3x,v 1.6 2010/12/04 18:38:55 tom Exp $ +.\" $Id: curs_ins_wstr.3x,v 1.7 2012/11/03 23:03:59 tom Exp $ .TH curs_ins_wstr 3X "" .na .hy 0 @@ -92,7 +92,7 @@ If the first character in the string is a nonspacing character, these functions will fail. XSI does not define what will happen if a nonspacing character follows a control character. -.SH RETURN VALUES +.SH RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. .PP diff --git a/man/curs_inwstr.3x b/man/curs_inwstr.3x index 966c7b4f7de9..0cdf4d8df65b 100644 --- a/man/curs_inwstr.3x +++ b/man/curs_inwstr.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 2002-2006,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 2002-2010,2012 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 * @@ -26,7 +26,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_inwstr.3x,v 1.7 2010/12/04 18:38:55 tom Exp $ +.\" $Id: curs_inwstr.3x,v 1.8 2012/11/03 23:03:59 tom Exp $ .TH curs_inwstr 3X "" .SH NAME \fBinwstr\fR, @@ -72,7 +72,7 @@ an error is generated. Note that all routines except \fBwinnwstr\fR may be macros. -.SH RETURN VALUES +.SH RETURN VALUE All routines return \fBERR\fR upon failure. Upon diff --git a/man/curs_mouse.3x b/man/curs_mouse.3x index 01dc68297623..1de85e510851 100644 --- a/man/curs_mouse.3x +++ b/man/curs_mouse.3x @@ -1,6 +1,6 @@ '\" t .\"*************************************************************************** -.\" Copyright (c) 1998-2009,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 1998-2010,2013 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 * @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_mouse.3x,v 1.38 2010/12/04 18:38:55 tom Exp $ +.\" $Id: curs_mouse.3x,v 1.39 2013/06/22 18:09:42 tom Exp $ .TH curs_mouse 3X "" .na .hy 0 @@ -40,20 +40,18 @@ .ad .hy .SH SYNOPSIS -.nf -\fB#include +\fB#include \fR .PP -\fBtypedef unsigned long mmask_t; +\fBtypedef unsigned long mmask_t;\fR .PP -typedef struct -{ - short id; \fI/* ID to distinguish multiple devices */\fB - int x, y, z; \fI/* event coordinates */\fB - mmask_t bstate; \fI/* button state bits */\fB -} -MEVENT;\fR +.nf +\fBtypedef struct {\fR +\fB short id; \fR\fI/* ID to distinguish multiple devices */\fR +\fB int x, y, z; \fR\fI/* event coordinates */\fR +\fB mmask_t bstate; \fR\fI/* button state bits */\fR +\fB} MEVENT;\fR .fi -.br +.PP \fBbool has_mouse(void);\fR .br \fBint getmouse(MEVENT *event);\fR diff --git a/man/curs_opaque.3x b/man/curs_opaque.3x index f3ad22e1482e..8c315ddda432 100644 --- a/man/curs_opaque.3x +++ b/man/curs_opaque.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 2007-2009,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 2007-2010,2013 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 * @@ -26,8 +26,12 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_opaque.3x,v 1.9 2010/12/04 18:40:45 tom Exp $ +.\" $Id: curs_opaque.3x,v 1.10 2013/07/20 19:42:29 tom Exp $ .TH curs_opaque 3X "" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' .na .hy 0 .SH NAME @@ -78,7 +82,7 @@ .br .SH DESCRIPTION This implementation provides functions which return properties -set in the WINDOW structure, allowing it to be ``opaque'' if +set in the WINDOW structure, allowing it to be \*(``opaque\*('' if the symbol \fBNCURSES_OPAQUE\fR is defined: .TP 5 \fBis_cleared\fR @@ -124,7 +128,8 @@ returns the parent WINDOW pointer for subwindows, or NULL for windows having no parent. .TP 5 \fBwgetscrreg\fR -returns the top and bottom rows for the scrolling margin as set in \fBwsetscrreg\fP. +returns the top and bottom rows for the scrolling margin +as set in \fBwsetscrreg\fP. .SH RETURN VALUE These functions all return TRUE or FALSE, except as noted. .SH NOTES diff --git a/man/curs_overlay.3x b/man/curs_overlay.3x index cea734e4a97c..972a95774b14 100644 --- a/man/curs_overlay.3x +++ b/man/curs_overlay.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 1998-2010,2013 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 * @@ -26,7 +26,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_overlay.3x,v 1.16 2010/12/04 18:40:45 tom Exp $ +.\" $Id: curs_overlay.3x,v 1.17 2013/04/06 23:48:51 tom Exp $ .TH curs_overlay 3X "" .na .hy 0 @@ -48,18 +48,21 @@ \fBint dmaxcol, int overlay);\fR .SH DESCRIPTION The \fBoverlay\fR and \fBoverwrite\fR routines overlay \fIsrcwin\fR on -top of \fIdstwin\fR. \fIscrwin\fR and \fIdstwin\fR are not required -to be the same size; only text where the two windows overlap is -copied. The difference is that \fBoverlay\fR is non-destructive +top of \fIdstwin\fR. +\fIscrwin\fR and \fIdstwin\fR are not required +to be the same size; only text where the two windows overlap is copied. +The difference is that \fBoverlay\fR is non-destructive (blanks are not copied) whereas \fBoverwrite\fR is destructive. .PP The \fBcopywin\fR routine provides a finer granularity of control over the -\fBoverlay\fR and \fBoverwrite\fR routines. Like in the \fBprefresh\fR -routine, a rectangle is specified in the destination window, (\fIdminrow\fR, +\fBoverlay\fR and \fBoverwrite\fR routines. +As in the \fBprefresh\fR routine, +a rectangle is specified in the destination window, (\fIdminrow\fR, \fIdmincol\fR) and (\fIdmaxrow\fR, \fIdmaxcol\fR), and the upper-left-corner -coordinates of the source window, (\fIsminrow\fR, \fIsmincol\fR). If the -argument \fIoverlay\fR is \fBtrue\fR, then copying is non-destructive, as in -\fBoverlay\fR. +coordinates of the source window, (\fIsminrow\fR, \fIsmincol\fR). +If the argument \fIoverlay\fR is \fBtrue\fR, +then copying is non-destructive, +as in \fBoverlay\fR. .SH RETURN VALUE Routines that return an integer return \fBERR\fR upon failure, and \fBOK\fR (SVr4 only specifies "an integer value other than \fBERR\fR") upon successful @@ -75,7 +78,8 @@ if some part of the window would be placed off-screen. Note that \fBoverlay\fR and \fBoverwrite\fR may be macros. .SH PORTABILITY The XSI Curses standard, Issue 4 describes these functions (adding the const -qualifiers). It further specifies their behavior in the presence of characters +qualifiers). +It further specifies their behavior in the presence of characters with multibyte renditions (not yet supported in this implementation). .SH SEE ALSO \fBcurses\fR(3X), \fBcurs_pad\fR(3X), \fBcurs_refresh\fR(3X) diff --git a/man/curs_sp_funcs.3x b/man/curs_sp_funcs.3x index 020e5c115aab..c7c55ddb62fe 100644 --- a/man/curs_sp_funcs.3x +++ b/man/curs_sp_funcs.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 2010 Free Software Foundation, Inc. * +.\" Copyright (c) 2010,2013 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 * @@ -26,7 +26,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_sp_funcs.3x,v 1.5 2010/12/04 18:38:55 tom Exp $ +.\" $Id: curs_sp_funcs.3x,v 1.6 2013/06/22 17:53:59 tom Exp $ .TH curs_sp_funcs 3X "" .na .hy 0 @@ -186,7 +186,7 @@ new_prescr \- \fBcurses\fR screen-pointer extension .br \fBint slk_attrset_sp(SCREEN*, const chtype);\fR .br -\fBint slk_attr_sp((SCREEN*);\fR +\fBint slk_attr_sp(SCREEN*);\fR .br \fBint slk_clear_sp(SCREEN*);\fR .br diff --git a/man/curs_termcap.3x b/man/curs_termcap.3x index 70a6710ad648..f8977bebca9c 100644 --- a/man/curs_termcap.3x +++ b/man/curs_termcap.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 1998-2007,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 1998-2012,2013 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 * @@ -26,8 +26,11 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_termcap.3x,v 1.26 2010/12/04 18:38:55 tom Exp $ +.\" $Id: curs_termcap.3x,v 1.30 2013/01/19 15:58:48 tom Exp $ .TH curs_termcap 3X "" +.de bP +.IP \(bu 4 +.. .na .hy 0 .ds n 5 @@ -75,11 +78,39 @@ the \fItermcap\fR library. Their parameters are the same and the routines are emulated using the \fIterminfo\fR database. Thus, they can only be used to query the capabilities of entries for which a terminfo entry has been compiled. +.SS INITIALIZATION .PP The \fBtgetent\fR routine loads the entry for \fIname\fR. -It returns 1 on success, 0 if there is no such entry, and \-1 if the -terminfo database could not be found. +It returns: +.RS 3 +.TP 3 +1 +on success, +.TP 3 +0 +if there is no such entry +(or that it is a generic type, having too little information for curses +applications to run), and +.TP 3 +\-1 +if the terminfo database could not be found. +.RE +.PP +This differs from the \fItermcap\fP library in two ways: +.RS 3 +.bP The emulation ignores the buffer pointer \fIbp\fR. +The \fItermcap\fP library would store a copy of the terminal +description in the area referenced by this pointer. +However, ncurses stores its terminal descriptions in compiled +binary form, which is not the same thing. +.bP +There is a difference in return codes. +The \fItermcap\fP library does not check if the terminal +description is marked with the \fIgeneric\fP capability, +or if the terminal description has cursor-addressing. +.RE +.SS CAPABILITY VALUES .PP The \fBtgetflag\fR routine gets the boolean entry for \fIid\fR, or zero if it is not available. @@ -98,12 +129,14 @@ Only the first two characters of the \fBid\fR parameter of \fBtgetflag\fR, \fBtgetnum\fR and \fBtgetstr\fR are compared in lookups. +.SS FORMATTING CAPABILITIES .PP The \fBtgoto\fR routine instantiates the parameters into the given capability. The output from this routine is to be passed to \fBtputs\fR. .PP The \fBtputs\fR routine is described on the \fBcurs_terminfo\fR(3X) manual page. It can retrieve capabilities by either termcap or terminfo name. +.SS GLOBAL VARIABLES .PP The variables \fBPC\fR, @@ -165,8 +198,28 @@ However, termcap applications' use of those variables is poorly documented, e.g., not distinguishing between input and output. In particular, some applications are reported to declare and/or modify \fBospeed\fR. +.PP +The comment that only the first two characters of the \fBid\fR parameter +are used escapes many application developers. +The original BSD 4.2 termcap library (and historical relics thereof) +did not require a trailing null NUL on the parameter name passed +to \fBtgetstr\fP, \fBtgetnum\fP and \fBtgetflag\fP. +Some applications assume that the termcap interface does not require +the trailing NUL for the parameter name. +Taking into account these issues: +.bP +As a special case, +\fBtgetflag\fP matched against a single-character identifier +provided that was at the end of the terminal description. +You should not rely upon this behavior in portable programs. +This implementation disallows matches against single-character capability names. +.bP +This implementation disallows matches by the termcap interface against +extended capability names which are longer than two characters. .SH SEE ALSO \fBcurses\fR(3X), \fBterminfo\fR(\*n), \fBterm_variables\fR(3X), \fBputc\fR(3). +.sp +http://invisible-island.net/ncurses/tctest.html diff --git a/man/curs_terminfo.3x b/man/curs_terminfo.3x index 0e95d1c2248d..7d440bf53ebc 100644 --- a/man/curs_terminfo.3x +++ b/man/curs_terminfo.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 1999-2008,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 1999-2011,2013 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 * @@ -26,8 +26,15 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_terminfo.3x,v 1.35 2010/12/04 18:38:55 tom Exp $ +.\" $Id: curs_terminfo.3x,v 1.43 2013/07/20 19:29:59 tom Exp $ .TH curs_terminfo 3X "" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.IP \(bu 4 +.. .ds n 5 .na .hy 0 @@ -77,7 +84,7 @@ .br \fBint vidattr(chtype \fR\fIattrs\fR\fB);\fR .br -\fBint vid_puts(attr_t \fR\fIattrs\fR\fB, short \fR\fIpair\fR\fB, void *\fR\fIopts\fR\fB, int (*\fR\fIputc\fR\fB)(char));\fR +\fBint vid_puts(attr_t \fR\fIattrs\fR\fB, short \fR\fIpair\fR\fB, void *\fR\fIopts\fR\fB, int (*\fR\fIputc\fR\fB)(int));\fR .br \fBint vid_attr(attr_t \fR\fIattrs\fR\fB, short \fR\fIpair\fR\fB, void *\fR\fIopts\fR\fB);\fR .br @@ -98,40 +105,54 @@ directly with the \fBterminfo\fR database to handle certain terminal capabilities, such as programming function keys. For all other functionality, \fBcurses\fR routines are more suitable and their use is recommended. +.SS Initialization .PP Initially, \fBsetupterm\fR should be called. Note that \fBsetupterm\fR is automatically called by \fBinitscr\fR and \fBnewterm\fR. This defines the set of terminal-dependent variables [listed in \fBterminfo\fR(\*n)]. +.PP +Each initialization routine provides applications with the +terminal capabilities either directly (via header definitions), +or by special functions. +The header files \fBcurses.h\fR and \fBterm.h\fR should be included (in this +order) to get the definitions for these strings, numbers, and flags. +.PP The \fBterminfo\fR variables \fBlines\fR and \fBcolumns\fR are initialized by \fBsetupterm\fR as follows: -.RS -.PP +.bP If \fBuse_env(FALSE)\fR has been called, values for \fBlines\fR and \fBcolumns\fR specified in \fBterminfo\fR are used. -.PP +.bP Otherwise, if the environment variables \fBLINES\fR and \fBCOLUMNS\fR exist, their values are used. If these environment variables do not exist and the program is running in a window, the current window size is used. Otherwise, if the environment variables do not exist, the values for \fBlines\fR and \fBcolumns\fR specified in the \fBterminfo\fR database are used. -.RE .PP -The header files \fBcurses.h\fR and \fBterm.h\fR should be included (in this -order) to get the definitions for these strings, numbers, and flags. Parameterized strings should be passed through \fBtparm\fR to instantiate them. All \fBterminfo\fR strings [including the output of \fBtparm\fR] should be printed -with \fBtputs\fR or \fBputp\fR. Call the \fBreset_shell_mode\fR to restore the -tty modes before exiting [see \fBcurs_kernel\fR(3X)]. Programs which use -cursor addressing should output \fBenter_ca_mode\fR upon startup and should -output \fBexit_ca_mode\fR before exiting. Programs desiring shell escapes -should call -.PP -\fBreset_shell_mode\fR and output \fBexit_ca_mode\fR before the shell -is called and should output \fBenter_ca_mode\fR and call -\fBreset_prog_mode\fR after returning from the shell. +with \fBtputs\fR or \fBputp\fR. +Call \fBreset_shell_mode\fR to restore the +tty modes before exiting [see \fBcurs_kernel\fR(3X)]. +.PP +Programs which use +cursor addressing should +.bP +output \fBenter_ca_mode\fR upon startup and +.bP +output \fBexit_ca_mode\fR before exiting. +.PP +Programs which execute shell subprocesses should +.bP +call \fBreset_shell_mode\fR and +output \fBexit_ca_mode\fR before the shell +is called and +.bP +output \fBenter_ca_mode\fR and +call \fBreset_prog_mode\fR after returning from the shell. .PP The \fBsetupterm\fR routine reads in the \fBterminfo\fR database, initializing the \fBterminfo\fR structures, but does not set up the @@ -146,19 +167,23 @@ then \fBsetupterm\fR returns \fBOK\fR or A return value of \fBOK\fR combined with status of \fB1\fR in \fIerrret\fR is normal. If \fBERR\fR is returned, examine \fIerrret\fR: -.RS .TP 5 .B 1 means that the terminal is hardcopy, cannot be used for curses applications. +.IP +\fBsetupterm\fP determines if the entry is a hardcopy type by +checking the \fIhc\fP (\fIhardcopy\fP) capability. .TP 5 .B 0 means that the terminal could not be found, or that it is a generic type, having too little information for curses applications to run. +.IP +\fBsetupterm\fP determines if the entry is a generic type by +checking the \fIgn\fP (\fIgeneric\fP) capability. .TP 5 .B \-1 means that the \fBterminfo\fR database could not be found. -.RE .PP If \fIerrret\fR is null, \fBsetupterm\fR prints an error message upon finding an error @@ -168,18 +193,33 @@ and exits. Thus, the simplest call is: .sp which uses all the defaults and sends the output to \fBstdout\fR. .PP -The \fBsetterm\fR routine is being replaced by \fBsetupterm\fR. The call: +The \fBsetterm\fR routine was replaced by \fBsetupterm\fR. The call: .sp \fBsetupterm(\fR\fIterm\fR\fB, 1, (int *)0)\fR .sp provides the same functionality as \fBsetterm(\fR\fIterm\fR\fB)\fR. -The \fBsetterm\fR routine is included here for BSD compatibility, and +The \fBsetterm\fR routine is provided for BSD compatibility, and is not recommended for new programs. -.PP -The \fBset_curterm\fR routine sets the variable \fBcur_term\fR to +.\" *************************************************************************** +.SS The Terminal State +.PP +The \fBsetupterm\fR routine stores its information about the terminal +in a \fBTERMINAL\fP structure pointed to by the global variable \fBcur_term\fP. +If it detects an error, +or decides that the terminal is unsuitable (hardcopy or generic), +it discards this information, +making it not available to applications. +.PP +If \fBsetupterm\fP is called repeatedly for the same terminal type, +it will reuse the information. +It maintains only one copy of a given terminal's capabilities in memory. +If it is called for different terminal types, +\fBsetupterm\fP allocates new storage for each set of terminal capabilities. +.PP +The \fBset_curterm\fR routine sets \fBcur_term\fR to \fInterm\fR, and makes all of the \fBterminfo\fR boolean, numeric, and -string variables use the values from \fInterm\fR. It returns the old value -of \fBcur_term\fR. +string variables use the values from \fInterm\fR. +It returns the old value of \fBcur_term\fR. .PP The \fBdel_curterm\fR routine frees the space pointed to by \fIoterm\fR and makes it available for further use. If \fIoterm\fR is @@ -189,11 +229,14 @@ memory locations until another \fBsetupterm\fR has been called. .PP The \fBrestartterm\fR routine is similar to \fBsetupterm\fR and \fBinitscr\fR, except that it is called after restoring memory to a previous state (for -example, when reloading a game saved as a core image dump). It assumes that -the windows and the input and output options are the same as when memory was -saved, but the terminal type and baud rate may be different. Accordingly, -it saves various tty state bits, calls \fBsetupterm\fP, -and then restores the bits. +example, when reloading a game saved as a core image dump). +\fBrestartterm\fP assumes that the windows and the input and output options +are the same as when memory was saved, +but the terminal type and baud rate may be different. +Accordingly, \fBrestartterm\fP saves various tty state bits, +calls \fBsetupterm\fP, and then restores the bits. +.\" *************************************************************************** +.SS Formatting Output .PP The \fBtparm\fR routine instantiates the string \fIstr\fR with parameters \fIpi\fR. A pointer is returned to the result of \fIstr\fR @@ -202,6 +245,8 @@ with the parameters applied. \fBtiparm\fP is a newer form of \fBtparm\fP which uses \fI\fP rather than a fixed-parameter list. Its numeric parameters are integers (int) rather than longs. +.\" *************************************************************************** +.SS Output Functions .PP The \fBtputs\fR routine applies padding information to the string \fIstr\fR and outputs it. The \fIstr\fR must be a terminfo string @@ -235,26 +280,48 @@ Currently, applications must provide a null pointer for that argument. .PP The \fBmvcur\fR routine provides low-level cursor motion. It takes effect immediately (rather than at the next refresh). +.\" *************************************************************************** +.SS Terminal Capability Functions .PP The \fBtigetflag\fR, \fBtigetnum\fR and \fBtigetstr\fR routines return the value of the capability corresponding to the \fBterminfo\fR \fIcapname\fR passed to them, such as \fBxenl\fR. -.PP -The \fBtigetflag\fR routine returns the value \fB\-1\fR if -\fIcapname\fR is not a boolean capability, -or \fB0\fR if it is canceled or absent from the terminal description. -.PP -The \fBtigetnum\fR routine returns the value \fB\-2\fR if -\fIcapname\fR is not a numeric capability, -or \fB\-1\fR if it is canceled or absent from the terminal description. -.PP -The \fBtigetstr\fR routine returns the value \fB(char *)\-1\fR -if \fIcapname\fR is not a string capability, -or \fB0\fR if it is canceled or absent from the terminal description. -.PP The \fIcapname\fR for each capability is given in the table column entitled \fIcapname\fR code in the capabilities section of \fBterminfo\fR(\*n). -.sp +.PP +These routines return special values to denote errors. +.PP +The \fBtigetflag\fR routine returns +.TP +\fB\-1\fR +if \fIcapname\fR is not a boolean capability, +or +.TP +\fB0\fR +if it is canceled or absent from the terminal description. +.PP +The \fBtigetnum\fR routine returns +.TP +\fB\-2\fR +if \fIcapname\fR is not a numeric capability, or +.TP +\fB\-1\fR +if it is canceled or absent from the terminal description. +.PP +The \fBtigetstr\fR routine returns +.TP +\fB(char *)\-1\fR +if \fIcapname\fR is not a string capability, +or +.TP +\fB0\fR +if it is canceled or absent from the terminal description. +.\" *************************************************************************** +.SS Terminal Capability Names +These null-terminated arrays contain +the short terminfo names ("codes"), +the \fBtermcap\fR names, and the long terminfo names ("fnames") +for each of the predefined \fBterminfo\fR variables: .RS \fBchar *boolnames[]\fR, \fB*boolcodes[]\fR, \fB*boolfnames[]\fR .sp @@ -262,10 +329,6 @@ The \fIcapname\fR for each capability is given in the table column entitled .sp \fBchar *strnames[]\fR, \fB*strcodes[]\fR, \fB*strfnames[]\fR .RE -.PP -These null-terminated arrays contain the \fIcapnames\fR, the -\fBtermcap\fR codes, and the full C names, for each of the -\fBterminfo\fR variables. .SH RETURN VALUE Routines that return an integer return \fBERR\fR upon failure and \fBOK\fR (SVr4 only specifies "an integer value other than \fBERR\fR") upon successful @@ -275,7 +338,7 @@ Routines that return pointers always return \fBNULL\fR on error. .PP X/Open defines no error conditions. In this implementation -.RS +.RS 5 .TP 5 \fBdel_curterm\fP returns an error @@ -300,19 +363,41 @@ It does not detect I/O errors: X/Open states that \fBtputs\fP ignores the return value of the output function \fIputc\fP. .RE -.SH NOTES -The \fBsetupterm\fR routine should be used in place of \fBsetterm\fR. -It may be useful when you want to test for terminal capabilities without -committing to the allocation of storage involved in \fBinitscr\fR. -.PP -Note that \fBvidattr\fR and \fBvidputs\fR may be macros. .SH PORTABILITY +X/Open notes that \fBvidattr\fR and \fBvidputs\fR may be macros. +.PP The function \fBsetterm\fR is not described by X/Open and must -be considered non-portable. All other functions are as described by X/Open. +be considered non-portable. +All other functions are as described by X/Open. .PP \fBsetupterm\fP copies the terminal name to the array \fBttytype\fP. This is not part of X/Open Curses, but is assumed by some applications. .PP +If configured to use the terminal-driver, +e.g., for the MinGW port, +.bP +\fBsetupterm\fP interprets a missing/empty TERM variable as the +special value \*(``unknown\*(''. +.bP +\fBsetupterm\fP allows explicit use of the +the windows console driver by checking if $TERM is set to +\*(``#win32con\*('' or an abbreviation of that string. +.PP +Older versions of \fBncurses\fP assumed that the file descriptor passed to +\fBsetupterm\fP from \fBinitscr\fP or \fBnewterm\fP uses buffered I/O, +and would write to the corresponding stream. +In addition to the limitation that the terminal was left in block-buffered +mode on exit (like SystemV curses), +it was problematic because \fBncurses\fP +did not allow a reliable way to cleanup on receiving SIGTSTP. +The current version uses output buffers managed directly by \fBncurses\fP. +Some of the low-level functions described in this manual page write +to the standard output. +They are not signal-safe. +The high-level functions in \fBncurses\fP use +alternate versions of these functions +using the more reliable buffering scheme. +.PP In System V Release 4, \fBset_curterm\fR has an \fBint\fR return type and returns \fBOK\fR or \fBERR\fR. We have chosen to implement the X/Open Curses semantics. @@ -332,12 +417,12 @@ Portable applications should provide 9 parameters after the format; zeroes are fine for this purpose. .PP In response to comments by Thomas E. Dickey, -X/Open Curses Issue 7 proposed the \fBtiparam\fP function in mid-2009. +X/Open Curses Issue 7 proposed the \fBtiparm\fP function in mid-2009. .PP X/Open notes that after calling \fBmvcur\fR, the curses state may not match the actual terminal state, and that an application should touch and refresh the window before resuming normal curses calls. -Both ncurses and System V Release 4 curses implement \fBmvcur\fR using +Both \fBncurses\fP and System V Release 4 curses implement \fBmvcur\fR using the SCREEN data allocated in either \fBinitscr\fR or \fBnewterm\fR. So though it is documented as a terminfo function, \fBmvcur\fR is really a curses function which is not well specified. @@ -346,8 +431,12 @@ X/Open states that the old location must be given for \fBmvcur\fP. This implementation allows the caller to use \-1's for the old ordinates. In that case, the old location is unknown. .PP -Extended terminal capability names, e.g., as defined by \fBtic\ \-x\fP, -are not stored in the arrays described in this section. +Other implementions may not declare the capability name arrays. +Some provide them without declaring them. +X/Open does not specify them. +.PP +Extended terminal capability names, e.g., as defined by \fB@TIC@\ \-x\fP, +are not stored in the arrays described here. .SH SEE ALSO \fBcurses\fR(3X), \fBcurs_initscr\fR(3X), diff --git a/man/curs_threads.3x b/man/curs_threads.3x index 4baa2a1f4917..5732e924c1b5 100644 --- a/man/curs_threads.3x +++ b/man/curs_threads.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 2008,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 2008-2010,2012 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 * @@ -26,7 +26,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_threads.3x,v 1.18 2010/12/04 18:38:55 tom Exp $ +.\" $Id: curs_threads.3x,v 1.19 2012/05/26 17:03:26 tom Exp $ .TH curs_threads 3X "" .de bP .IP \(bu 4 @@ -51,9 +51,9 @@ .br \fBint set_tabsize(int size);\fR .br -\fBint use_screen(SCREEN *scr, NCURSES_WINDOW_CB func, void *data);\fR +\fBint use_screen(SCREEN *scr, NCURSES_SCREEN_CB func, void *data);\fR .br -\fBint use_window(WINDOW *win, NCURSES_SCREEN_CB func, void *data);\fR +\fBint use_window(WINDOW *win, NCURSES_WINDOW_CB func, void *data);\fR .br .SH DESCRIPTION This implementation can be configured to provide rudimentary support diff --git a/man/curs_util.3x b/man/curs_util.3x index fb912b65f328..444f40e2cffb 100644 --- a/man/curs_util.3x +++ b/man/curs_util.3x @@ -1,5 +1,6 @@ +'\" t .\"*************************************************************************** -.\" Copyright (c) 1998-2008,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 1998-2012,2013 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 * @@ -26,8 +27,12 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_util.3x,v 1.32 2010/12/04 18:38:55 tom Exp $ +.\" $Id: curs_util.3x,v 1.37 2013/07/20 19:43:45 tom Exp $ .TH curs_util 3X "" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' .de bP .IP \(bu 4 .. @@ -44,6 +49,7 @@ \fBputwin\fR, \fBunctrl\fR, \fBuse_env\fR, +\fBuse_tioctl\fR, \fBwunctrl\fR \- miscellaneous \fBcurses\fR utility routines .ad .hy @@ -64,6 +70,8 @@ .br \fBvoid use_env(bool f);\fR .br +\fBvoid use_tioctl(bool f);\fR +.br \fBint putwin(WINDOW *win, FILE *filep);\fR .br \fBWINDOW *getwin(FILE *filep);\fR @@ -80,10 +88,12 @@ Printing characters are displayed as is. The corresponding \fBwunctrl\fR returns a printable representation of a wide character. .PP -The \fBkeyname\fR routine returns a character string corresponding to the key \fIc\fR: +The \fBkeyname\fR routine returns a character string +corresponding to the key \fIc\fR: .RS 3 .bP -Printable characters are displayed as themselves, e.g., a one-character string containing the key. +Printable characters are displayed as themselves, +e.g., a one-character string containing the key. .bP Control characters are displayed in the \fB^\fR\fIX\fR notation. .bP @@ -123,16 +133,70 @@ using a different value of \fB$TERM\fP. The limitation arises because the \fBfilter\fP routine modifies the in-memory copy of the terminal information. .PP -The \fBuse_env\fR routine, if used, is called before \fBinitscr\fR or -\fBnewterm\fR are called. When called with \fBFALSE\fR as an -argument, the values of \fBlines\fR and \fBcolumns\fR specified in the -\fIterminfo\fR database will be used, even if environment variables -\fBLINES\fR and \fBCOLUMNS\fR (used by default) are set, or if -\fBcurses\fR is running in a window (in which case default behavior -would be to use the window size if \fBLINES\fR and \fBCOLUMNS\fR are -not set). -Note that setting \fBLINES\fR or \fBCOLUMNS\fR overrides the -corresponding size which may be obtained from the operating system. +The \fBuse_env\fR routine, if used, +should be called before \fBinitscr\fR or +\fBnewterm\fR are called +(because those compute the screen size). +It modifies the way \fBncurses\fP treats environment variables +when determining the screen size. +.bP +Normally ncurses looks first at the terminal database for the screen size. +.IP +If \fBuse_env\fP was called with \fBFALSE\fP for parameter, +it stops here unless +If \fBuse_tioctl\fP was also called with \fBTRUE\fP for parameter. +.bP +Then it asks for the screen size via operating system calls. +If successful, +it overrides the values from the terminal database. +.bP +Finally (unless \fBuse_env\fP was called with \fBFALSE\fP parameter), +ncurses examines the \fBLINES\fR or \fBCOLUMNS\fR environment variables, +using a value in those to override the results +from the operating system or terminal database. +.IP +Ncurses also updates the screen size in response to SIGWINCH, +unless overridden by the \fBLINES\fR or \fBCOLUMNS\fR environment variables, +.PP +The \fBuse_tioctl\fR routine, if used, +should be called before \fBinitscr\fR or \fBnewterm\fR are called +(because those compute the screen size). +After \fBuse_tioctl\fR is called with \fBTRUE\fR as an argument, +ncurses modifies the last step in its computation of screen size as follows: +.bP +checks if the \fBLINES\fR and \fBCOLUMNS\fR environment variables +are set to a number greater than zero. +.bP +for each, ncurses updates the corresponding environment variable +with the value that it has obtained via operating system call +or from the terminal database. +.bP +ncurses re-fetches the value of the environment variables so that +it is still the environment variables which set the screen size. +.PP +The \fBuse_env\fP and \fBuse_tioctl\fP routines combine as +summarized here: +.TS +center tab(/); +l l l +_ _ _ +lw7 lw7 lw40. +\fIuse_env\fR/\fIuse_tioctl\fR/\fISummary\fR +TRUE/FALSE/T{ +This is the default behavior. +ncurses uses operating system calls +unless overridden by $LINES or $COLUMNS environment variables. +T} +TRUE/TRUE/T{ +ncurses updates $LINES and $COLUMNS based on operating system calls. +T} +FALSE/TRUE/T{ +ncurses ignores $LINES and $COLUMNS, uses operating system calls to obtain size. +T} +FALSE/FALSE/T{ +ncurses relies on the terminal database to determine size. +T} +.TE .PP The \fBputwin\fR routine writes all data associated with window \fIwin\fR into the file to which \fIfilep\fR points. This information can be later retrieved @@ -145,7 +209,8 @@ data. It returns a pointer to the new window. The \fBdelay_output\fR routine inserts an \fIms\fR millisecond pause in output. This routine should not be used extensively because padding characters are used rather than a CPU pause. -If no padding character is specified, this uses \fBnapms\fR to perform the delay. +If no padding character is specified, +this uses \fBnapms\fR to perform the delay. .PP The \fBflushinp\fR routine throws away any typeahead that has been typed by the user and has not yet been read by the program. @@ -183,12 +248,13 @@ the parameter is in the range 128\-159, i.e., a C1 control code. If \fBuse_legacy_coding\fP has been called with a \fB2\fP parameter, \fBunctrl\fP returns the parameter, i.e., a one-character string with the parameter as the first character. -Otherwise, it returns ``~@'', ``~A'', etc., analogous to ``^@'', ``^A'', C0 controls. +Otherwise, it returns \*(``~@\*('', \*(``~A\*('', etc., +analogous to \*(``^@\*('', \*(``^A\*('', C0 controls. .IP X/Open Curses does not document whether \fBunctrl\fP can be called before initializing curses. This implementation permits that, -and returns the ``~@'', etc., values in that case. +and returns the \*(``~@\*('', etc., values in that case. .bP parameter values outside the 0 to 255 range. \fBunctrl\fP returns a null pointer. @@ -214,17 +280,17 @@ change the output of \fBunctrl\fP. Likewise, the \fBmeta\fP function allows the caller to change the output of \fBkeyname\fP, i.e., it determines whether to use the `M\-' prefix -for ``meta'' keys (codes in the range 128 to 255). +for \*(``meta\*('' keys (codes in the range 128 to 255). Both \fBuse_legacy_coding\fP and \fBmeta\fP succeed only after curses is initialized. X/Open Curses does not document the treatment of codes 128 to 159. -When treating them as ``meta'' keys +When treating them as \*(``meta\*('' keys (or if \fBkeyname\fP is called before initializing curses), -this implementation returns strings ``M\-^@'', ``M\-^A'', etc. +this implementation returns strings \*(``M\-^@\*('', \*(``M\-^A\*('', etc. .PP The \fBkeyname\fP function may return the names of user-defined string capabilities which are defined in the terminfo entry via the \fB\-x\fP -option of \fBtic\fP. +option of \fB@TIC@\fP. This implementation automatically assigns at run-time keycodes to user-defined strings which begin with "k". The keycodes start at KEY_MAX, but are not guaranteed to be @@ -233,8 +299,8 @@ merged from all terminal descriptions which have been loaded. The \fBuse_extended_names\fP function controls whether this data is loaded when the terminal description is read by the library. .PP -The \fBnofilter\fP routine is specific to ncurses. -It was not supported on Version 7, BSD or System V implementations. +The \fBnofilter\fP and \fBuse_tioctl\fP routines are specific to ncurses. +They were not supported on Version 7, BSD or System V implementations. It is recommended that any code depending on ncurses extensions be conditioned using NCURSES_VERSION. .SH SEE ALSO diff --git a/man/curs_variables.3x b/man/curs_variables.3x index 8cfee5290e5c..efbe192a4882 100644 --- a/man/curs_variables.3x +++ b/man/curs_variables.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 2010 Free Software Foundation, Inc. * +.\" Copyright (c) 2010,2013 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 * @@ -26,7 +26,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_variables.3x,v 1.4 2010/12/04 18:38:55 tom Exp $ +.\" $Id: curs_variables.3x,v 1.6 2013/12/21 18:41:32 tom Exp $ .TH curs_variables 3X "" .de bP .IP \(bu 4 @@ -74,7 +74,7 @@ This page summarizes variables provided by the \fBcurses\fP library. A more complete description is given in the \fBcurses\fP(3X) manual page. .PP Depending on the configuration, these may be actual variables, -or macros (see \fBcurs_threads\fR(3X)) +or macros (see \fBcurs_threads\fR(3X) and \fBcurs_opaque\fR(3X)) which provide read-only access to \fIcurses\fP's state. In either case, applications should treat them as read-only to avoid confusing the library. @@ -129,7 +129,8 @@ ESCDELAY and TABSIZE are extensions, not provided in most other implementations of curses. .SH SEE ALSO \fBcurses\fR(3X), +\fBcurs_opaque\fR(3X), +\fBcurs_terminfo\fR(3X), \fBcurs_threads\fR(3X), \fBterm_variables\fR(3X), -\fBterminfo\fR(3X), \fBterminfo\fR(\*n). diff --git a/man/form_field.3x b/man/form_field.3x index 7a39a0ccc839..19a8b88ef984 100644 --- a/man/form_field.3x +++ b/man/form_field.3x @@ -1,6 +1,6 @@ '\" t .\"*************************************************************************** -.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 1998-2010,2012 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 * @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: form_field.3x,v 1.10 2010/12/04 18:40:45 tom Exp $ +.\" $Id: form_field.3x,v 1.11 2012/11/03 23:03:59 tom Exp $ .TH form_field 3X "" .SH NAME \fBform_field\fR \- make and break connections between fields and forms @@ -52,7 +52,7 @@ The function \fBfield_count\fR returns the count of fields in \fIform\fR. .PP The function \fBmove_field\fR moves the given field (which must be disconnected) to a specified location on the screen. -.SH RETURN VALUES +.SH RETURN VALUE The function \fBform_fields\fR returns a pointer (which may be \fBNULL\fR). It does not set errno. .PP diff --git a/man/form_variables.3x b/man/form_variables.3x index 49f28762082d..f4af349b1699 100644 --- a/man/form_variables.3x +++ b/man/form_variables.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 2010 Free Software Foundation, Inc. * +.\" Copyright (c) 2010,2013 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 * @@ -26,7 +26,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: form_variables.3x,v 1.3 2010/12/04 18:38:55 tom Exp $ +.\" $Id: form_variables.3x,v 1.4 2013/06/22 17:58:32 tom Exp $ .TH form_variables 3X "" .ds n 5 .na @@ -45,7 +45,6 @@ .SH SYNOPSIS .nf \fB#include \fR -.br .PP \fBFIELDTYPE * TYPE_ALNUM;\fR \fBFIELDTYPE * TYPE_ALPHA;\fR @@ -54,7 +53,6 @@ \fBFIELDTYPE * TYPE_IPV4;\fR \fBFIELDTYPE * TYPE_NUMERIC;\fR \fBFIELDTYPE * TYPE_REGEXP;\fR -.br .fi .SH DESCRIPTION These are building blocks for the form library, diff --git a/man/infocmp.1m b/man/infocmp.1m index bfc3cc315c14..294abe3eb693 100644 --- a/man/infocmp.1m +++ b/man/infocmp.1m @@ -1,6 +1,6 @@ '\" t .\"*************************************************************************** -.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 1998-2012,2013 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 * @@ -27,9 +27,12 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: infocmp.1m,v 1.46 2010/12/04 18:40:45 tom Exp $ +.\" $Id: infocmp.1m,v 1.53 2013/02/02 22:07:35 tom Exp $ .TH @INFOCMP@ 1M "" .ds n 5 +.de bP +.IP \(bu 4 +.. .ds d @TERMINFO@ .SH NAME \fB@INFOCMP@\fR \- compare or print out \fIterminfo\fR descriptions @@ -37,10 +40,12 @@ \fB@INFOCMP@\fR [\fB\-\ 1\ C\ +D\ E\ F\ G\ I\ +K\ L\ T\ U\ @@ -69,32 +74,40 @@ x\ \fB@INFOCMP@\fR can be used to compare a binary \fBterminfo\fR entry with other terminfo entries, rewrite a \fBterminfo\fR description to take advantage of the \fBuse=\fR terminfo field, or print out a \fBterminfo\fR description from the -binary file (\fBterm\fR) in a variety of formats. In all cases, the boolean +binary file (\fBterm\fR) in a variety of formats. +In all cases, the boolean fields will be printed first, followed by the numeric fields, followed by the string fields. .SS Default Options If no options are specified and zero or one \fItermnames\fR are specified, the -\fB\-I\fR option will be assumed. If more than one \fItermname\fR is specified, +\fB\-I\fR option will be assumed. +If more than one \fItermname\fR is specified, the \fB\-d\fR option will be assumed. .SS Comparison Options [\-d] [\-c] [\-n] \fB@INFOCMP@\fR compares the \fBterminfo\fR description of the first terminal \fItermname\fR with each of the descriptions given by the entries for the other -terminal's \fItermnames\fR. If a capability is defined for only one of the +terminal's \fItermnames\fR. +If a capability is defined for only one of the terminals, the value returned will depend on the type of the capability: \fBF\fR for boolean variables, \fB\-1\fR for integer variables, and \fBNULL\fR for string variables. .PP The \fB\-d\fR option produces a list of each capability that is different -between two entries. This option is useful to show the difference between two +between two entries. +This option is useful to show the difference between two entries, created by different people, for the same or similar terminals. .PP The \fB\-c\fR option produces a list of each capability that is common between -two entries. Capabilities that are not set are ignored. This option can be +two or more entries. +Capabilities that are not set are ignored. +This option can be used as a quick check to see if the \fB\-u\fR option is worth using. .PP -The \fB\-n\fR option produces a list of each capability that is in neither -entry. If no \fItermnames\fR are given, the environment variable \fBTERM\fR -will be used for both of the \fItermnames\fR. This can be used as a quick +The \fB\-n\fR option produces a list of each capability that is in none of +the given entries. +If no \fItermnames\fR are given, the environment variable \fBTERM\fR +will be used for both of the \fItermnames\fR. +This can be used as a quick check to see if anything was left out of a description. .SS Source Listing Options [\-I] [\-L] [\-C] [\-r] The \fB\-I\fR, \fB\-L\fR, and \fB\-C\fR options will produce a source listing for @@ -107,6 +120,7 @@ l l . \fB\-L\fR/use the long C variable name listed in <\fBterm.h\fR> \fB\-C\fR/use the \fBtermcap\fR names \fB\-r\fR/when using \fB\-C\fR, put out all capabilities in \fBtermcap\fR form +\fB\-K\fR/modifies the \fB\-C\fP option, improving BSD-compatibility. .TE .PP If no \fItermnames\fR are given, the environment variable \fBTERM\fR will be @@ -114,26 +128,48 @@ used for the terminal name. .PP The source produced by the \fB\-C\fR option may be used directly as a \fBtermcap\fR entry, but not all parameterized strings can be changed to -the \fBtermcap\fR format. \fB@INFOCMP@\fR will attempt to convert most of the +the \fBtermcap\fR format. +\fB@INFOCMP@\fR will attempt to convert most of the parameterized information, and anything not converted will be plainly marked in -the output and commented out. These should be edited by hand. +the output and commented out. +These should be edited by hand. +.PP +For best results when converting to \fBtermcap\fP format, +you should use both \fB\-C\fP and \fB\-r\fP. +Normally a termcap description is limited to 1023 bytes. +@INFOCMP@ trims away less essential parts to make it fit. +If you are converting to one of the (rare) termcap implementations +which accept an unlimited size of termcap, +you may want to add the \fB\-T\fP option. +More often however, you must help the termcap implementation, +and trim excess whitespace (use the \fB\-0\fP option for that). .PP All padding information for strings will be collected together and placed -at the beginning of the string where \fBtermcap\fR expects it. Mandatory +at the beginning of the string where \fBtermcap\fR expects it. +Mandatory padding (padding information with a trailing '/') will become optional. .PP All \fBtermcap\fR variables no longer supported by \fBterminfo\fR, but which -are derivable from other \fBterminfo\fR variables, will be output. Not all +are derivable from other \fBterminfo\fR variables, will be output. +Not all \fBterminfo\fR capabilities will be translated; only those variables which were -part of \fBtermcap\fR will normally be output. Specifying the \fB\-r\fR option +part of \fBtermcap\fR will normally be output. +Specifying the \fB\-r\fR option will take off this restriction, allowing all capabilities to be output in \fItermcap\fR form. +Normally you would use both the \fB\-C\fP and \fB\-r\fP options. +The actual format used incorporates some improvements for escaped characters +from terminfo format. +For a stricter BSD-compatible translation, use the \fB\-K\fR option +rather than \fB\-C\fP. .PP Note that because padding is collected to the beginning of the capability, not -all capabilities are output. Mandatory padding is not supported. Because +all capabilities are output. +Mandatory padding is not supported. +Because \fBtermcap\fR strings are not as flexible, it is not always possible to convert -a \fBterminfo\fR string capability into an equivalent \fBtermcap\fR format. A -subsequent conversion of the \fBtermcap\fR file back into \fBterminfo\fR format +a \fBterminfo\fR string capability into an equivalent \fBtermcap\fR format. +A subsequent conversion of the \fBtermcap\fR file back into \fBterminfo\fR format will not necessarily reproduce the original \fBterminfo\fR source. .PP @@ -156,27 +192,33 @@ l l l. .SS Use= Option [\-u] The \fB\-u\fR option produces a \fBterminfo\fR source description of the first terminal \fItermname\fR which is relative to the sum of the descriptions given -by the entries for the other terminals \fItermnames\fR. It does this by +by the entries for the other terminals \fItermnames\fR. +It does this by analyzing the differences between the first \fItermname\fR and the other \fItermnames\fR and producing a description with \fBuse=\fR fields for the -other terminals. In this manner, it is possible to retrofit generic terminfo -entries into a terminal's description. Or, if two similar terminals exist, but +other terminals. +In this manner, it is possible to retrofit generic terminfo +entries into a terminal's description. +Or, if two similar terminals exist, but were coded at different times or by different people so that each description is a full description, using \fB@INFOCMP@\fR will show what can be done to change one description to be relative to the other. .PP A capability will get printed with an at-sign (@) if it no longer exists in the first \fItermname\fR, but one of the other \fItermname\fR entries contains a -value for it. A capability's value gets printed if the value in the first +value for it. +A capability's value gets printed if the value in the first \fItermname\fR is not found in any of the other \fItermname\fR entries, or if the first of the other \fItermname\fR entries that has this capability gives a different value for the capability than that in the first \fItermname\fR. .PP -The order of the other \fItermname\fR entries is significant. Since the -terminfo compiler \fBtic\fR does a left-to-right scan of the capabilities, +The order of the other \fItermname\fR entries is significant. +Since the +terminfo compiler \fB@TIC@\fR does a left-to-right scan of the capabilities, specifying two \fBuse=\fR entries that contain differing entries for the same capabilities will produce different results depending on the order that the -entries are given in. \fB@INFOCMP@\fR will flag any such inconsistencies between +entries are given in. +\fB@INFOCMP@\fR will flag any such inconsistencies between the other \fItermname\fR entries as they are found. .PP Alternatively, specifying a capability \fIafter\fR a \fBuse=\fR entry that @@ -187,29 +229,48 @@ description. .PP Another error that does not cause incorrect compiled files, but will slow down the compilation time, is specifying extra \fBuse=\fR fields that are -superfluous. \fB@INFOCMP@\fR will flag any other \fItermname use=\fR fields that +superfluous. +\fB@INFOCMP@\fR will flag any other \fItermname use=\fR fields that were not needed. .SS Changing Databases [\-A \fIdirectory\fR] [\-B \fIdirectory\fR] -The location of the compiled \fBterminfo\fR database is taken from the -environment variable \fBTERMINFO\fR . If the variable is not defined, or the -terminal is not found in that location, the system \fBterminfo\fR database, -in \fB@TERMINFO@\fR, will be used. The options \fB\-A\fR -and \fB\-B\fR may be used to override this location. The \fB\-A\fR option will -set \fBTERMINFO\fR for the first \fItermname\fR and the \fB\-B\fR option will -set \fBTERMINFO\fR for the other \fItermnames\fR. With this, it is possible to +Like other \fBncurses\fP utilities, +@INFOCMP@ looks for the terminal descriptions in several places. +You can use the \fBTERMINFO\fP and \fBTERMINFO_DIRS\fP environment variables +to override the compiled-in default list of places to search +(see \fBcurses\fP(3X) for details). +.PP +You can also use the options \fB\-A\fR +and \fB\-B\fR to override the list of places to search +when comparing terminal descriptions: +.bP +The \fB\-A\fR option sets the location for the first \fItermname\fR +.bP +The \fB\-B\fR option sets the location for the other \fItermnames\fR. +.PP +Using these options, it is possible to compare descriptions for a terminal with the same name located in two different -databases. This is useful for comparing descriptions for the same terminal +databases. +For instance, +you can use this feature for comparing descriptions for the same terminal created by different people. .SS Other Options .TP 5 +\fB\-0\fR +causes the fields to be printed on one line, without wrapping. +.TP 5 \fB\-1\fR -causes the fields to be printed out one to a line. Otherwise, +causes the fields to be printed out one to a line. +Otherwise, the fields will be printed several to a line to a maximum width of 60 characters. .TP \fB\-a\fR tells \fB@INFOCMP@\fP to retain commented-out capabilities rather than discarding -them. Capabilities are commented by prefixing them with a period. +them. +Capabilities are commented by prefixing them with a period. +.TP +\fB\-D\fR +tells \fB@INFOCMP@\fP to print the database locations that it knows about, and exit. .TP 5 \fB\-E\fR Dump the capabilities of the given terminal as tables, needed in @@ -231,12 +292,15 @@ This option is useful for preparing versions of the curses library hardwired for a given terminal type. .TP 5 \fB\-F\fR -compare terminfo files. This assumes that two following arguments are -filenames. The files are searched for pairwise matches between +compare terminfo files. +This assumes that two following arguments are filenames. +The files are searched for pairwise matches between entries, with two entries considered to match if any of their names do. The report printed to standard output lists entries with no matches in -the other file, and entries with more than one match. For entries -with exactly one match it includes a difference report. Normally, +the other file, and entries with more than one match. +For entries +with exactly one match it includes a difference report. +Normally, to reduce the volume of the report, use references are not resolved before looking for differences, but resolution can be forced by also specifying \fB\-r\fR. @@ -255,14 +319,17 @@ rather than their decimal equivalents. .TP 5 \fB\-i\fR Analyze the initialization (\fBis1\fR, \fBis2\fR, \fBis3\fR), and reset -(\fBrs1\fR, \fBrs2\fR, \fBrs3\fR), strings in the entry. For each string, the +(\fBrs1\fR, \fBrs2\fR, \fBrs3\fR), strings in the entry. +For each string, the code tries to analyze it into actions in terms of the other capabilities in the entry, certain X3.64/ISO 6429/ECMA\-48 capabilities, and certain DEC VT-series private modes (the set of recognized special sequences has been selected for -completeness over the existing terminfo database). Each report line consists +completeness over the existing terminfo database). +Each report line consists of the capability name, followed by a colon and space, followed by a printable expansion of the capability string with sections matching recognized actions -translated into {}-bracketed descriptions. Here is a list of the DEC/ANSI +translated into {}-bracketed descriptions. +Here is a list of the DEC/ANSI special sequences recognized: i. .TS @@ -308,7 +375,8 @@ DEC[+\-]ARM/auto-repeat mode .sp It also recognizes a SGR action corresponding to ANSI/ISO 6429/ECMA Set Graphics Rendition, with the values NORMAL, BOLD, UNDERLINE, BLINK, and -REVERSE. All but NORMAL may be prefixed with `+' (turn on) or `\-' (turn off). +REVERSE. +All but NORMAL may be prefixed with `+' (turn on) or `\-' (turn off). .PP An SGR0 designates an empty highlight sequence (equivalent to {SGR:NORMAL}). .TP 5 @@ -323,12 +391,15 @@ Make the comparison listing shorter by omitting subheadings, and using "\-" for absent capabilities, "@" for canceled rather than "NULL". .TP 5 \fB\-R\fR\fIsubset\fR -Restrict output to a given subset. This option is for use with archaic +Restrict output to a given subset. +This option is for use with archaic versions of terminfo like those on SVr1, Ultrix, or HP/UX that do not support the full set of SVR4/XSI Curses terminfo; and variants such as AIX -that have their own extensions incompatible with SVr4/XSI. Available terminfo +that have their own extensions incompatible with SVr4/XSI. +Available terminfo subsets are "SVr1", "Ultrix", "HP", and "AIX"; see \fBterminfo\fR(\*n) for -details. You can also choose the subset "BSD" which selects only capabilities +details. +You can also choose the subset "BSD" which selects only capabilities with termcap equivalents recognized by 4.4BSD. .TP \fB\-s \fR\fI[d|i|l|c]\fR @@ -362,7 +433,7 @@ This is mainly useful for testing and analysis, since the compiled descriptions are limited (e.g., 1023 for termcap, 4096 for terminfo). .TP \fB\-t\fR -tells \fBtic\fP to discard commented-out capabilities. +tells \fB@TIC@\fP to discard commented-out capabilities. Normally when translating from terminfo to termcap, untranslatable capabilities are commented-out. .TP 5 @@ -385,13 +456,15 @@ changes the output to \fIwidth\fR characters. \fB\-x\fR print information for user-defined capabilities. These are extensions to the terminfo repertoire which can be loaded -using the \fB\-x\fR option of \fBtic\fP. +using the \fB\-x\fR option of \fB@TIC@\fP. .SH FILES .TP 20 \*d Compiled terminal description database. .SH EXTENSIONS The +\fB\-0\fR, +\fB\-1\fR, \fB\-E\fR, \fB\-F\fR, \fB\-G\fR, @@ -410,7 +483,8 @@ The options are not supported in SVr4 curses. .PP The \fB\-r\fR option's notion of `termcap' capabilities is System V Release 4's. -Actual BSD curses versions will have a more restricted set. To see only the +Actual BSD curses versions will have a more restricted set. +To see only the 4.4BSD set, use \fB\-r\fR \fB\-RBSD\fR. .SH BUGS The \fB\-F\fR option of \fB@INFOCMP@\fR(1M) should be a \fB@TOE@\fR(1M) mode. @@ -421,6 +495,8 @@ The \fB\-F\fR option of \fB@INFOCMP@\fR(1M) should be a \fB@TOE@\fR(1M) mode. \fB@TOE@\fR(1M), \fBcurses\fR(3X), \fBterminfo\fR(\*n). +.sp +http://invisible-island.net/ncurses/tctest.html .PP This describes \fBncurses\fR version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@). diff --git a/man/manhtml.aliases b/man/manhtml.aliases new file mode 100644 index 000000000000..a4ae047a14c6 --- /dev/null +++ b/man/manhtml.aliases @@ -0,0 +1,16 @@ +# $Id: manhtml.aliases,v 1.1 2013/12/21 21:44:52 tom Exp $ +# Items in this list will be linked to the corresponding manpages by man2html +addch(3X) curs_addch(3X) +delscreen(3X) curs_initscr(3X) +filter(3X) curs_util(3X) +form_fieldtype(3X) form_fieldtype(3X) +getch(3X) curs_getch(3X) +infocmp(1) infocmp(1M) +initscr(3X) curs_initscr(3X) +newterm(3X) curs_initscr(3X) +set_fieldtype(3X) form_fieldtype(3X) +set_term(3X) curs_initscr(3X) +setupterm(3X) curs_terminfo(3X) +tic(1) tic(1M) +use_env(3X) curs_util(3X) +vidputs(3X) curs_terminfo(3X) diff --git a/man/manhtml.externs b/man/manhtml.externs new file mode 100644 index 000000000000..d26b6127a445 --- /dev/null +++ b/man/manhtml.externs @@ -0,0 +1,24 @@ +# $Id: manhtml.externs,v 1.3 2013/12/21 22:11:29 tom Exp $ +# Items in this list will not be linked by man2html +conflict(1) +csh(1) +ded(1) +environ(7) +getty(1) +nvi(1) +printf(3) +profile(5) +putc(3) +putwc(3) +read(2) +rogue(1) +scanf(3) +sh(1) +sscanf(3) +stdio(3) +stty(1) +system(3) +termio(7) +tty(4) +ttys(5) +wcwidth(3) diff --git a/man/menu_items.3x b/man/menu_items.3x index a9c578346485..04b00ad76772 100644 --- a/man/menu_items.3x +++ b/man/menu_items.3x @@ -1,6 +1,6 @@ '\" t .\"*************************************************************************** -.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 1998-2010,2012 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 * @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: menu_items.3x,v 1.9 2010/12/04 18:40:45 tom Exp $ +.\" $Id: menu_items.3x,v 1.10 2012/11/03 23:03:59 tom Exp $ .TH menu_items 3X "" .SH NAME \fBmenu_items\fR \- make and break connections between items and menus @@ -47,7 +47,7 @@ The function \fBset_menu_items\fR changes the item pointer array of the given The function \fBmenu_items\fR returns the item array of the given menu. .PP The function \fBitem_count\fR returns the count of items in \fImenu\fR. -.SH RETURN VALUES +.SH RETURN VALUE The function \fBmenu_items\fR returns a pointer (which may be \fBNULL\fR). It does not set errno. .PP diff --git a/man/ncurses.3x b/man/ncurses.3x index 4acfc050101a..6a5aa7c0c2fe 100644 --- a/man/ncurses.3x +++ b/man/ncurses.3x @@ -1,6 +1,6 @@ '\" t .\"*************************************************************************** -.\" Copyright (c) 1998-2010,2011 Free Software Foundation, Inc. * +.\" Copyright (c) 1998-2012,2013 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 * @@ -27,9 +27,13 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: ncurses.3x,v 1.103 2011/02/05 23:21:29 tom Exp $ +.\" $Id: ncurses.3x,v 1.112 2013/07/20 19:29:59 tom Exp $ .hy 0 .TH ncurses 3X "" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' .de bP .IP \(bu 4 .. @@ -43,7 +47,7 @@ .SH DESCRIPTION The \fBncurses\fR library routines give the user a terminal-independent method of updating character screens with reasonable optimization. -This implementation is ``new curses'' (ncurses) and +This implementation is \*(``new curses\*('' (ncurses) and is the approved replacement for 4.4BSD classic curses, which has been discontinued. This describes \fBncurses\fR @@ -55,8 +59,10 @@ and XPG4 (X/Open Portability Guide) curses (also known as XSI curses). XSI stands for X/Open System Interfaces Extension. The \fBncurses\fR library is freely redistributable in source form. Differences from the SVr4 -curses are summarized under the \fBEXTENSIONS\fP and \fBPORTABILITY\fP sections below and -described in detail in the respective \fBEXTENSIONS\fP, \fBPORTABILITY\fP and \fBBUGS\fP sections +curses are summarized under the +\fBEXTENSIONS\fP and \fBPORTABILITY\fP sections below and +described in detail in the respective +\fBEXTENSIONS\fP, \fBPORTABILITY\fP and \fBBUGS\fP sections of individual man pages. .PP The \fBncurses\fR library also provides many useful extensions, @@ -108,9 +114,9 @@ Most programs would additionally use the sequence: .sp Before a \fBcurses\fR program is run, the tab stops of the terminal should be set and its initialization strings, if defined, must be output. -This can be done by executing the \fBtput init\fR command +This can be done by executing the \fB@TPUT@ init\fR command after the shell environment variable \fBTERM\fR has been exported. -\fBtset(1)\fR is usually responsible for doing this. +\fB@TSET@(1)\fR is usually responsible for doing this. [See \fBterminfo\fR(\*n) for further details.] .PP The \fBncurses\fR library permits manipulation of data structures, @@ -637,6 +643,7 @@ use_default_colors/\fBdefault_colors\fR(3X)* use_env/\fBcurs_util\fR(3X) use_extended_names/\fBcurs_extend\fR(3X)* use_legacy_coding/\fBlegacy_coding\fR(3X)* +use_tioctl/\fBcurs_util\fR(3X) vid_attr/\fBcurs_terminfo\fR(3X) vid_puts/\fBcurs_terminfo\fR(3X) vidattr/\fBcurs_terminfo\fR(3X) @@ -734,9 +741,16 @@ Routines that return an integer return \fBERR\fR upon failure and an integer value other than \fBERR\fR upon successful completion, unless otherwise noted in the routine descriptions. .PP +As a general rule, routines check for null pointers passed as parameters, +and handle this as an error. +.PP All macros return the value of the \fBw\fR version, except \fBsetscrreg\fR, \fBwsetscrreg\fR, \fBgetyx\fR, \fBgetbegyx\fR, and \fBgetmaxyx\fR. -The return values of \fBsetscrreg\fR, \fBwsetscrreg\fR, \fBgetyx\fR, \fBgetbegyx\fR, and +The return values of +\fBsetscrreg\fR, +\fBwsetscrreg\fR, +\fBgetyx\fR, +\fBgetbegyx\fR, and \fBgetmaxyx\fR are undefined (i.e., these should not be used as the right-hand side of assignment statements). .PP @@ -747,9 +761,9 @@ runtime behavior of the \fBncurses\fR library. The most important ones have been already discussed in detail. .TP 5 BAUDRATE -The debugging library checks this environment symbol when the application +The debugging library checks this environment variable when the application has redirected output to a file. -The symbol's numeric value is used for the baudrate. +The variable's numeric value is used for the baudrate. If no value is found, \fBncurses\fR uses 9600. This allows testers to construct repeatable test-cases that take into account costs that depend on baudrate. @@ -757,7 +771,7 @@ that take into account costs that depend on baudrate. CC When set, change occurrences of the command_character (i.e., the \fBcmdch\fP capability) -of the loaded terminfo entries to the value of this symbol. +of the loaded terminfo entries to the value of this variable. Very few terminfo entries provide this feature. .IP Because this name is also used in development environments to represent @@ -786,7 +800,9 @@ For best results, \fBlines\fR and \fBcols\fR should not be specified in a terminal description for terminals which are run as emulations. .IP Use the \fBuse_env\fR function to disable all use of external environment -(including system calls) to determine the screen size. +(but not including system calls) to determine the screen size. +Use the \fBuse_tioctl\fR function to update \fBCOLUMNS\fP or \fBLINES\fP +to match the screen size obtained from system calls or the terminal database. .TP 5 ESCDELAY Specifies the total time, in milliseconds, for which ncurses will @@ -837,8 +853,8 @@ platforms: .br 3 = middle. .sp -This symbol lets you customize the mouse. -The symbol must be three numeric digits 1\-3 in any order, e.g., 123 or 321. +This variable lets you customize the mouse. +The variable must be three numeric digits 1\-3 in any order, e.g., 123 or 321. If it is not specified, \fBncurses\fR uses 132. .TP 5 NCURSES_ASSUMED_COLORS @@ -899,19 +915,44 @@ have delay times embedded. You may wish to use these descriptions, but not want to pay the performance penalty. .IP -Set the NCURSES_NO_PADDING symbol to disable all but mandatory +Set the NCURSES_NO_PADDING environment variable to disable all but mandatory padding. Mandatory padding is used as a part of special control sequences such as \fIflash\fR. .TP 5 NCURSES_NO_SETBUF -Normally \fBncurses\fR enables buffered output during terminal initialization. -This is done (as in SVr4 curses) for performance reasons. +This setting is obsolete. +Before changes +.RS +.bP +started with 5.9 patch 20120825 +and +.bP +continued +though 5.9 patch 20130126 +.RE +.IP +\fBncurses\fR enabled buffered output during terminal initialization. +This was done (as in SVr4 curses) for performance reasons. For testing purposes, both of \fBncurses\fR and certain applications, -this feature is made optional. +this feature was made optional. Setting the NCURSES_NO_SETBUF variable -disables output buffering, leaving the output in the original (usually +disabled output buffering, leaving the output in the original (usually line buffered) mode. +.IP +In the current implementation, +ncurses performs its own buffering and does not require this workaround. +It does not modify the buffering of the standard output. +.IP +The reason for the change was to make the behavior for interrupts and +other signals more robust. +One drawback is that certain nonconventional programs would mix +ordinary stdio calls with ncurses calls and (usually) work. +This is no longer possible since ncurses is not using +the buffered standard output but its own output (to the same file descriptor). +As a special case, the low-level calls such as \fBputp\fP still use the +standard output. +But high-level curses calls do not. .TP 5 NCURSES_NO_UTF8_ACS During initialization, the \fBncurses\fR library @@ -933,20 +974,22 @@ disables the special check for "linux" and "screen". .IP As an alternative to the environment variable, ncurses checks for an extended terminfo capability \fBU8\fP. -This is a numeric capability which can be compiled using \fBtic\ \-x\fP. +This is a numeric capability which can be compiled using \fB@TIC@\ \-x\fP. For example .RS 5 +.ft CW .sp .nf # linux console, if patched to provide working # VT100 shift-in/shift-out, with corresponding font. linux-vt100|linux console with VT100 line-graphics, - U8#0, use=linux, + U8#0, use=linux, .sp # uxterm with vt100Graphics resource set to false xterm-utf8|xterm relying on UTF-8 line-graphics, - U8#1, use=xterm, + U8#1, use=xterm, .fi +.ft .RE .IP The name "U8" is chosen to be two characters, @@ -955,7 +998,7 @@ termcap interface. .TP 5 NCURSES_TRACE During initialization, the \fBncurses\fR debugging library -checks the NCURSES_TRACE symbol. +checks the NCURSES_TRACE environment variable. If it is defined, to a numeric value, \fBncurses\fR calls the \fBtrace\fR function, using that value as the argument. .IP @@ -973,9 +1016,10 @@ If the \fBncurses\fR library has been configured with \fItermcap\fR support, \fBncurses\fR will check for a terminal's description in termcap form if it is not available in the terminfo database. .IP -The TERMCAP symbol contains either a terminal description (with +The TERMCAP environment variable contains either a terminal description (with newlines stripped out), -or a file name telling where the information denoted by the TERM symbol exists. +or a file name telling where the information denoted by +the TERM environment variable exists. In either case, setting it directs \fBncurses\fR to ignore the usual place for this information, e.g., /etc/termcap. .TP 5 @@ -988,33 +1032,51 @@ The complete list of directories in order follows: .bP the last directory to which \fBncurses\fR wrote, if any, is searched first .bP -the directory specified by the TERMINFO symbol +the directory specified by the TERMINFO environment variable .bP $HOME/.terminfo .bP -directories listed in the TERMINFO_DIRS symbol +directories listed in the TERMINFO_DIRS environment variable .bP one or more directories whose names are configured and compiled into the -ncurses library, e.g., -@TERMINFO@ +ncurses library, i.e., +.RS +.bP +@TERMINFO_DIRS@ (corresponding to the TERMINFO_DIRS variable) +.bP +@TERMINFO@ (corresponding to the TERMINFO variable) +.RE .RE .TP 5 TERMINFO_DIRS Specifies a list of directories to search for terminal descriptions. The list is separated by colons (i.e., ":") on Unix, semicolons on OS/2 EMX. -All of the terminal descriptions are in terminfo form, which makes -a subdirectory named for the first letter of the terminal names therein. +.IP +All of the terminal descriptions are in terminfo form. +Normally these are stored in a directory tree, +using subdirectories named by the first letter of the terminal names therein. +.IP +If \fBncurses\fP is built with a hashed database, +then each entry in this list can also be the path of the corresponding +database file. +.IP +If \fBncurses\fP is built with a support for reading termcap files +directly, then an entry in this list may be the path of a termcap file. .TP 5 TERMPATH If TERMCAP does not hold a file name then \fBncurses\fR checks -the TERMPATH symbol. -This is a list of filenames separated by spaces or colons (i.e., ":") on Unix, semicolons on OS/2 EMX. -If the TERMPATH symbol is not set, \fBncurses\fR looks in the files +the TERMPATH environment variable. +This is a list of filenames separated by spaces or colons (i.e., ":") on Unix, +semicolons on OS/2 EMX. +.IP +If the TERMPATH environment variable is not set, +\fBncurses\fR looks in the files /etc/termcap, /usr/share/misc/termcap and $HOME/.termcap, in that order. .PP The library may be configured to disregard the following variables when the current user is the superuser (root), or if the application uses setuid or setgid permissions: +.IP $TERMINFO, $TERMINFO_DIRS, $TERMPATH, as well as $HOME. .SH ALTERNATE CONFIGURATIONS Several different configurations are possible, @@ -1042,8 +1104,9 @@ It also omits a symbolic link which would allow you to use \fB\-lcurses\fP to build executables. .TP 5 \-\-enable\-widec -The configure script renames the library and (if the \fB\-\-disable\-overwrite\fP -option is used) puts the header files in a different subdirectory. +The configure script renames the library and +(if the \fB\-\-disable\-overwrite\fP option is used) +puts the header files in a different subdirectory. All of the library names have a "w" appended to them, i.e., instead of .RS @@ -1093,8 +1156,8 @@ directory containing initialization files for the terminal capability database @TERMINFO@ terminal capability database .SH SEE ALSO -\fBterminfo\fR(\*n) and related pages whose names begin "curs_" for detailed routine -descriptions. +\fBterminfo\fR(\*n) and related pages whose names begin +"curs_" for detailed routine descriptions. .br \fBcurs_variables\fR(3X) .SH EXTENSIONS @@ -1144,6 +1207,15 @@ A small number of local differences (that is, individual differences between the XSI Curses and \fBncurses\fR calls) are described in \fBPORTABILITY\fR sections of the library man pages. .PP +Unlike other implementations, this one checks parameters such as pointers +to WINDOW structures to ensure they are not null. +The main reason for providing this behavior is to guard against programmer +error. +The standard interface does not provide a way for the library +to tell an application which of several possible errors were detected. +Relying on this (or some other) extension will adversely affect the +portability of curses applications. +.PP This implementation also contains several extensions: .bP The routine \fBhas_key\fR is not part of XPG4, nor is it present in SVr4. diff --git a/man/resizeterm.3x b/man/resizeterm.3x index ddb47e76bf92..25a760c70a87 100644 --- a/man/resizeterm.3x +++ b/man/resizeterm.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 1998-2005,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 1998-2012,2013 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 * @@ -26,9 +26,9 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" Author: Thomas E. Dickey 1996-2005 +.\" Author: Thomas E. Dickey 1996-on .\" -.\" $Id: resizeterm.3x,v 1.14 2010/12/04 18:38:55 tom Exp $ +.\" $Id: resizeterm.3x,v 1.17 2013/06/22 20:41:54 tom Exp $ .TH resizeterm 3X "" .SH NAME \fBis_term_resized\fR, @@ -48,7 +48,8 @@ It provides callers with a hook into the \fBncurses\fR data to resize windows, primarily for use by programs running in an X Window terminal (e.g., xterm). The function \fBresizeterm\fR resizes the standard and current windows to the specified dimensions, and adjusts other bookkeeping data used by -the \fBncurses\fR library that record the window dimensions. +the \fBncurses\fR library that record the window dimensions +such as the \fBLINES\fP and \fBCOLS\fP variables. .LP Most of the work is done by the inner function \fBresize_term\fR. The outer function \fBresizeterm\fR adds bookkeeping for the SIGWINCH handler. @@ -64,7 +65,7 @@ A support function \fBis_term_resized\fR is provided so that applications can check if the \fBresize_term\fR function would modify the window structures. It returns TRUE if the windows would be modified, and FALSE otherwise. .SH RETURN VALUE -Except as notes, these function return +Except as noted, these functions return the integer \fBERR\fR upon failure and \fBOK\fR on success. They will fail if either of the dimensions are less than or equal to zero, or if an error occurs while (re)allocating memory for the windows. @@ -75,7 +76,7 @@ context where \fBmalloc\fR or \fBrealloc\fR may have been interrupted, since it uses those functions. .PP If ncurses is configured to supply its own SIGWINCH handler, -the \fBresizeterm\fR function ungetch's a \fBKEY_RESIZE\fR which +the \fBresizeterm\fR function \fBungetch\fP's a \fBKEY_RESIZE\fR which will be read on the next call to \fBgetch\fR. This is used to alert an application that the screen size has changed, and that it should repaint special features such as pads that cannot @@ -86,9 +87,8 @@ this overrides the library's use of the window size obtained from the operating system. Thus, even if a SIGWINCH is received, no screen size change may be recorded. -In that case, no \fBKEY_RESIZE\fP is queued for the next call to \fBgetch\fP; -an \fBERR\fP will be returned instead. .SH SEE ALSO +\fBcurs_getch\fR(3X), \fBcurs_variables\fR(3X), \fBwresize\fR(3X). .SH AUTHOR diff --git a/man/tabs.1 b/man/tabs.1 index c867db511667..f6b797d777cd 100644 --- a/man/tabs.1 +++ b/man/tabs.1 @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 2008-2009,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 2008-2011,2013 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 * @@ -26,19 +26,18 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: tabs.1,v 1.8 2010/12/04 18:40:45 tom Exp $ +.\" $Id: tabs.1,v 1.11 2013/06/22 18:11:57 tom Exp $ .TH @TABS@ 1 "" .ds n 5 .SH NAME -\fBtabs\fR \- set tabs on a terminal +\fB@TABS@\fR \- set tabs on a terminal .SH SYNOPSIS -\fBtabs\fR [\fB\-v\fR[\fIn\fR]] [\fB\-ahuUV\fR] \fIfile...\fR -.br +\fB@TABS@\fR [\fIoptions\fR]] \fI[tabstop-list]\fR .SH DESCRIPTION .PP -The \fBtabs\fP program clears and sets tab-stops on the terminal. +The \fB@TABS@\fP program clears and sets tab-stops on the terminal. This uses the terminfo \fIclear_all_tabs\fP and \fIset_tab\fP capabilities. -If either is absent, \fBtabs\fP is unable to clear/set tab-stops. +If either is absent, \fB@TABS@\fP is unable to clear/set tab-stops. The terminal should be configured to use hard tabs, e.g., .sp .RS @@ -48,8 +47,8 @@ stty tab0 .SS General Options .TP 5 .BI \-T "name" -Tell \fBtabs\fP which terminal type to use. -If this option is not given, \fBtabs\fP will use the \fB$TERM\fP +Tell \fB@TABS@\fP which terminal type to use. +If this option is not given, \fB@TABS@\fP will use the \fB$TERM\fP environment variable. If that is not set, it will use the \fIansi+tabs\fP entry. .TP 5 @@ -59,10 +58,13 @@ The first data line shows the expected tab-stops marked with asterisks. The second data line shows the actual tab-stops, marked with asterisks. .TP 5 .B \-n -This option tells \fBtabs\fP to check the options and run any debugging +This option tells \fB@TABS@\fP to check the options and run any debugging option, but not to modify the terminal settings. +.TP +\fB\-V\fR +reports the version of ncurses which was used in this program, and exits. .PP -The \fBtabs\fP program processes a single list of tab stops. +The \fB@TABS@\fP program processes a single list of tab stops. The last option to be processed which defines a list is the one that determines the list to be processed. .SS Implicit Lists diff --git a/man/term.7 b/man/term.7 index 78aa095a8829..cee8a012f85f 100644 --- a/man/term.7 +++ b/man/term.7 @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 1998-2007,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 1998-2010,2011 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 * @@ -26,7 +26,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: term.7,v 1.22 2010/12/04 18:41:07 tom Exp $ +.\" $Id: term.7,v 1.23 2011/12/17 23:32:17 tom Exp $ .TH term 7 .ds n 5 .ds d @TERMINFO@ @@ -55,7 +55,7 @@ can almost always be avoided by explicitly exporting `vt100' (assuming you are in fact using a VT100-superset console, terminal, or terminal emulator.) .PP In any case, you are free to override the system \fBTERM\fR setting to your -taste in your shell profile. The \fBtset\fP(1) utility may be of assistance; +taste in your shell profile. The \fB@TSET@\fP(1) utility may be of assistance; you can give it a set of rules for deducing or requesting a terminal type based on the tty device and baud rate. .PP diff --git a/man/term_variables.3x b/man/term_variables.3x index 58b7cfea2df3..4cf9a0c89921 100644 --- a/man/term_variables.3x +++ b/man/term_variables.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 2010 Free Software Foundation, Inc. * +.\" Copyright (c) 2011,2013 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 * @@ -26,7 +26,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: term_variables.3x,v 1.2 2010/12/04 18:38:55 tom Exp $ +.\" $Id: term_variables.3x,v 1.4 2013/12/21 22:17:39 tom Exp $ .TH term_variables 3X "" .ds n 5 .na @@ -110,7 +110,7 @@ use as a parameter to \fBset_term\fP, for switching between screens. Alternatively, one can save the return value from \fBnewterm\fP or \fBsetupterm\fP to reuse in \fBset_term\fP. .SS Terminfo Names -The \fBtic\fP(1) and \fBinfocmp\fP(1) programs use lookup tables for +The \fB@TIC@\fP(1) and \fB@INFOCMP@\fP(1) programs use lookup tables for the long and short names of terminfo capabilities, as well as the corresponding names for termcap capabilities. These are available to other applications, @@ -134,7 +134,10 @@ strcodes. On initialization of the curses or terminfo interfaces, \fBsetupterm\fP copies the terminal name to the array \fBttytype\fP. .SH NOTES -The low-level terminfo interface is initialized using \fBsetupterm\fR(3X). +The low-level terminfo interface is initialized using +.hy 0 +\fBsetupterm\fR(3X). +.hy The upper-level curses interface uses the low-level terminfo interface, internally. .SH PORTABILITY @@ -146,8 +149,9 @@ Other implementations may have comparable variables. Some implementations provide the variables in their libraries, but omit them from the header files. .SH SEE ALSO +.hy 0 \fBcurses\fR(3X), \fBcurs_terminfo\fR(3X), \fBcurs_threads\fR(3X), -\fBterminfo\fR(3X), \fBterminfo\fR(\*n). +.hy diff --git a/man/terminfo.head b/man/terminfo.head index da8284c2f63b..c4cc072baeb0 100644 --- a/man/terminfo.head +++ b/man/terminfo.head @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 1998-2009,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 1998-2012,2013 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 * @@ -26,10 +26,17 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: terminfo.head,v 1.18 2010/07/31 16:08:48 tom Exp $ +.\" $Id: terminfo.head,v 1.21 2013/03/09 22:11:36 tom Exp $ .TH terminfo 5 "" "" "File Formats" .ds n 5 .ds d @TERMINFO@ +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.IP \(bu 4 +.. .SH NAME terminfo \- terminal capability data base .SH SYNOPSIS @@ -74,7 +81,7 @@ the result can be read by \fB@TIC@\fP. Terminal names (except for the last, verbose entry) should be chosen using the following conventions. The particular piece of hardware making up the terminal should -have a root name, thus ``hp2621''. +have a root name, thus \*(``hp2621\*(''. This name should not contain hyphens. Modes that the hardware can be in, or user preferences, should be indicated by appending a hyphen and a mode suffix. @@ -102,6 +109,6 @@ l l l. .TE .PP For more on terminal naming conventions, see the \fBterm(7)\fR manual page. -.SS Capabilities +.SS Predefined Capabilities .\" Head of terminfo man page ends here .ps -1 diff --git a/man/terminfo.tail b/man/terminfo.tail index 4b56e91be314..ec076483fe83 100644 --- a/man/terminfo.tail +++ b/man/terminfo.tail @@ -1,8 +1,51 @@ -.\" $Id: terminfo.tail,v 1.53 2010/12/04 18:38:55 tom Exp $ +.\" $Id: terminfo.tail,v 1.68 2013/11/09 15:20:48 tom Exp $ .\" Beginning of terminfo.tail file .\" This file is part of ncurses. .\" See "terminfo.head" for copyright. .ps +1 +.SS User-Defined Capabilities +. +The preceding section listed the \fIpredefined\fP capabilities. +They deal with some special features for terminals no longer +(or possibly never) produced. +Occasionally there are special features of newer terminals which +are awkward or impossible to represent by reusing the predefined +capabilities. +.PP +\fBncurses\fP addresses this limitation by allowing user-defined capabilities. +The \fB@TIC@\fP and \fB@INFOCMP@\fP programs provide +the \fB\-x\fP option for this purpose. +When \fB\-x\fP is set, +\fB@TIC@\fP treats unknown capabilities as user-defined. +That is, if \fB@TIC@\fP encounters a capability name +which it does not recognize, +it infers its type (boolean, number or string) from the syntax +and makes an extended table entry for that capability. +The \fBuse_extended_names\fP function makes this information +conditionally available to applications. +The ncurses library provides the data leaving most of the behavior +to applications: +.bP +User-defined capability strings whose name begins +with \*(``k\*('' are treated as function keys. +.bP +The types (boolean, number, string) determined by \fB@TIC@\fP +can be inferred by successful calls on \fBtigetflag\fP, etc. +.bP +If the capability name happens to be two characters, +the capability is also available through the termcap interface. +.PP +While termcap is said to be extensible because it does not use a predefined set +of capabilities, +in practice it has been limited to the capabilities defined by +terminfo implementations. +As a rule, +user-defined capabilities intended for use by termcap applications should +be limited to booleans and numbers to avoid running past the 1023 byte +limit assumed by termcap implementations and their applications. +In particular, providing extended sets of function keys (past the 60 +numbered keys and the handful of special named keys) is best done using +the longer names available using terminfo. . .SS A Sample Entry . @@ -10,42 +53,54 @@ The following entry, describing an ANSI-standard terminal, is representative of what a \fBterminfo\fR entry for a modern terminal typically looks like. .PP .nf -.in -2 -.ta .3i .ft CW \s-2ansi|ansi/pc-term compatible with color, - mc5i, - colors#8, ncv#3, pairs#64, - cub=\\E[%p1%dD, cud=\\E[%p1%dB, cuf=\\E[%p1%dC, - cuu=\\E[%p1%dA, dch=\\E[%p1%dP, dl=\\E[%p1%dM, - ech=\\E[%p1%dX, el1=\\E[1K, hpa=\\E[%p1%dG, ht=\\E[I, - ich=\\E[%p1%d@, il=\\E[%p1%dL, indn=\\E[%p1%dS, .indn=\\E[%p1%dT, - kbs=^H, kcbt=\\E[Z, kcub1=\\E[D, kcud1=\\E[B, - kcuf1=\\E[C, kcuu1=\\E[A, kf1=\\E[M, kf10=\\E[V, - kf11=\\E[W, kf12=\\E[X, kf2=\\E[N, kf3=\\E[O, kf4=\\E[P, - kf5=\\E[Q, kf6=\\E[R, kf7=\\E[S, kf8=\\E[T, kf9=\\E[U, - kich1=\\E[L, mc4=\\E[4i, mc5=\\E[5i, nel=\\r\\E[S, - op=\\E[37;40m, rep=%p1%c\\E[%p2%{1}%\-%db, - rin=\\E[%p1%dT, s0ds=\\E(B, s1ds=\\E)B, s2ds=\\E*B, - s3ds=\\E+B, setab=\\E[4%p1%dm, setaf=\\E[3%p1%dm, - setb=\\E[4%?%p1%{1}%=%t4%e%p1%{3}%=%t6%e%p1%{4}%=%t1%e%p1%{6}%=%t3%e%p1%d%;m, - setf=\\E[3%?%p1%{1}%=%t4%e%p1%{3}%=%t6%e%p1%{4}%=%t1%e%p1%{6}%=%t3%e%p1%d%;m, - sgr=\\E[0;10%?%p1%t;7%;%?%p2%t;4%;%?%p3%t;7%;%?%p4%t;5%;%?%p6%t;1%;%?%p7%t;8%;%?%p8%t;11%;%?%p9%t;12%;m, - sgr0=\\E[0;10m, tbc=\\E[2g, u6=\\E[%d;%dR, u7=\\E[6n, - u8=\\E[?%[;0123456789]c, u9=\\E[c, vpa=\\E[%p1%dd,\s+2 -.in +2 + am, mc5i, mir, msgr, + colors#8, cols#80, it#8, lines#24, ncv#3, pairs#64, + acsc=+\\020\\,\\021-\\030.^Y0\\333`\\004a\\261f\\370g\\361h\\260 + j\\331k\\277l\\332m\\300n\\305o~p\\304q\\304r\\304s_t\\303 + u\\264v\\301w\\302x\\263y\\363z\\362{\\343|\\330}\\234~\\376, + bel=^G, blink=\\E[5m, bold=\\E[1m, cbt=\\E[Z, clear=\\E[H\\E[J, + cr=^M, cub=\\E[%p1%dD, cub1=\\E[D, cud=\\E[%p1%dB, cud1=\\E[B, + cuf=\\E[%p1%dC, cuf1=\\E[C, cup=\\E[%i%p1%d;%p2%dH, + cuu=\\E[%p1%dA, cuu1=\\E[A, dch=\\E[%p1%dP, dch1=\\E[P, + dl=\\E[%p1%dM, dl1=\\E[M, ech=\\E[%p1%dX, ed=\\E[J, el=\\E[K, + el1=\\E[1K, home=\\E[H, hpa=\\E[%i%p1%dG, ht=\\E[I, hts=\\EH, + ich=\\E[%p1%d@, il=\\E[%p1%dL, il1=\\E[L, ind=^J, + indn=\\E[%p1%dS, invis=\\E[8m, kbs=^H, kcbt=\\E[Z, kcub1=\\E[D, + kcud1=\\E[B, kcuf1=\\E[C, kcuu1=\\E[A, khome=\\E[H, kich1=\\E[L, + mc4=\\E[4i, mc5=\\E[5i, nel=\\r\\E[S, op=\\E[39;49m, + rep=%p1%c\\E[%p2%{1}%-%db, rev=\\E[7m, rin=\\E[%p1%dT, + rmacs=\\E[10m, rmpch=\\E[10m, rmso=\\E[m, rmul=\\E[m, + s0ds=\\E(B, s1ds=\\E)B, s2ds=\\E*B, s3ds=\\E+B, + setab=\\E[4%p1%dm, setaf=\\E[3%p1%dm, + sgr=\\E[0;10%?%p1%t;7%; + %?%p2%t;4%; + %?%p3%t;7%; + %?%p4%t;5%; + %?%p6%t;1%; + %?%p7%t;8%; + %?%p9%t;11%;m, + sgr0=\\E[0;10m, smacs=\\E[11m, smpch=\\E[11m, smso=\\E[7m, + smul=\\E[4m, tbc=\\E[3g, u6=\\E[%i%d;%dR, u7=\\E[6n, + u8=\\E[?%[;0123456789]c, u9=\\E[c, vpa=\\E[%i%p1%dd, .fi .ft R .PP Entries may continue onto multiple lines by placing white space at the beginning of each line except the first. -Comments may be included on lines beginning with ``#''. +Comments may be included on lines beginning with \*(``#\*(''. Capabilities in .I terminfo are of three types: +.bP Boolean capabilities which indicate that the terminal has -some particular feature, numeric capabilities giving the size of the terminal -or the size of particular delays, and string +some particular feature, +.bP +numeric capabilities giving the size of the terminal +or the size of particular delays, and +.bP +string capabilities, which give a sequence which can be used to perform particular terminal operations. .PP @@ -58,15 +113,15 @@ ANSI-standard terminals have (i.e., an automatic return and line-feed when the end of a line is reached) is indicated by the capability \fBam\fR. Hence the description of ansi includes \fBam\fR. -Numeric capabilities are followed by the character `#' and then a positive value. +Numeric capabilities are followed by the character \*(``#\*('' and then a positive value. Thus \fBcols\fR, which indicates the number of columns the terminal has, -gives the value `80' for ansi. +gives the value \*(``80\*('' for ansi. Values for numeric capabilities may be specified in decimal, octal or hexadecimal, using the C programming language conventions (e.g., 255, 0377 and 0xff or 0xFF). .PP Finally, string valued capabilities, such as \fBel\fR (clear to end of line -sequence) are given by the two-character code, an `=', and then a string -ending at the next following `,'. +sequence) are given by the two-character code, an \*(``=\*('', and then a string +ending at the next following \*(``,\*(''. .PP A number of escape sequences are provided in the string valued capabilities for easy encoding of characters there. @@ -75,14 +130,29 @@ map to an \s-1ESCAPE\s0 character, \fB^x\fR maps to a control-x for any appropriate x, and the sequences \fB\en \el \er \et \eb \ef \es\fR give a newline, line-feed, return, tab, backspace, form-feed, and space. -Other escapes include \fB\e^\fR for \fB^\fR, +Other escapes include +.bP +\fB\e^\fR for \fB^\fR, +.bP \fB\e\e\fR for \fB\e\fR, +.bP \fB\e\fR, for comma, +.bP \fB\e:\fR for \fB:\fR, +.bP and \fB\e0\fR for null. -(\fB\e0\fR will produce \e200, which does not terminate a string but behaves +.IP +\fB\e0\fR will produce \e200, which does not terminate a string but behaves as a null character on most terminals, providing CS7 is specified. -See stty(1).) +See stty(1). +.IP +The reason for this quirk is to maintain binary compatibility of the +compiled terminfo files with other implementations, +e.g., the SVr4 systems, which document this. +Compiled terminfo files use null-terminated strings, with no lengths. +Modifying this would require a new binary format, +which would not work with other implementations. +.PP Finally, characters may be given as three octal digits after a \fB\e\fR. .PP A delay in milliseconds may appear anywhere in a string capability, enclosed in @@ -90,8 +160,8 @@ $<..> brackets, as in \fBel\fP=\eEK$<5>, and padding characters are supplied by .I tputs to provide this delay. The delay must be a number with at most one decimal -place of precision; it may be followed by suffixes `*' or '/' or both. -A `*' +place of precision; it may be followed by suffixes \*(``*\*('' or \*(``/\*('' or both. +A \*(``*\*('' indicates that the padding required is proportional to the number of lines affected by the operation, and the amount given is the per-affected-unit padding required. @@ -100,7 +170,7 @@ number of .IR lines affected.) Normally, padding is advisory if the device has the \fBxon\fR capability; it is used for cost computation but does not trigger delays. -A `/' +A \*(``/\*('' suffix indicates that the padding is mandatory and forces a delay of the given number of milliseconds even on devices for which \fBxon\fR is present to indicate flow control. @@ -115,27 +185,36 @@ in the example above. .PP .SS Fetching Compiled Descriptions .PP +The \fBncurses\fP library searches for terminal descriptions in several places. +It uses only the first description found. +The library has a compiled-in list of places to search +which can be overridden by environment variables. +Before starting to search, +\fBncurses\fP eliminates duplicates in its search list. +.bP If the environment variable TERMINFO is set, it is interpreted as the pathname of a directory containing the compiled description you are working on. -Only -that directory is searched. -.PP -If TERMINFO is not set, the \fBncurses\fR version of the terminfo reader code -will instead look in the directory \fB$HOME/.terminfo\fR +Only that directory is searched. +.bP +If TERMINFO is not set, +\fBncurses\fR will instead look in the directory \fB$HOME/.terminfo\fR for a compiled description. -If it fails to find one there, and the environment variable TERMINFO_DIRS is -set, it will interpret the contents of that variable as a list of colon- -separated directories to be searched (an empty entry is interpreted as a -command to search \fI\*d\fR). -If no description is found in any of the -TERMINFO_DIRS directories, the fetch fails. -.PP -If neither TERMINFO nor TERMINFO_DIRS is set, the last place tried will be the -system terminfo directory, \fI\*d\fR. -.PP -(Neither the \fB$HOME/.terminfo\fR lookups nor TERMINFO_DIRS extensions are -supported under stock System V terminfo/curses.) -.PP +.bP +Next, if the environment variable TERMINFO_DIRS is set, +\fBncurses\fR will interpret the contents of that variable +as a list of colon-separated directories (or database files) to be searched. +.IP +An empty directory name (i.e., if the variable begins or ends +with a colon, or contains adacent colons) +is interpreted as the system location \fI\*d\fR. +.bP +Finally, \fBncurses\fP searches these compiled-in locations: +.RS +.bP +a list of directories (@TERMINFO_DIRS@), and +.bP +the system terminfo directory, \fI\*d\fR (the compiled-in default). +.RE .SS Preparing Descriptions .PP We now outline how to prepare descriptions of terminals. @@ -154,7 +233,7 @@ or bugs in the screen-handling code of the test program. .PP To get the padding for insert line right (if the terminal manufacturer did not document it) a severe test is to edit a large file at 9600 baud, -delete 16 or so lines from the middle of the screen, then hit the `u' +delete 16 or so lines from the middle of the screen, then hit the \*(``u\*('' key several times quickly. If the terminal messes up, more padding is usually needed. A similar test can be used for insert character. @@ -198,7 +277,7 @@ given as and .BR cud1 . These local cursor motions should not alter the text they pass over, -for example, you would not normally use `\fBcuf1\fP=\ ' because the +for example, you would not normally use \*(``\fBcuf1\fP=\ \*('' because the space would erase the character moved over. .PP A very important point here is that the local cursor motions encoded @@ -275,9 +354,10 @@ Thus the model 33 teletype is described as .ft CW .\".in -2 \s-133\||\|tty33\||\|tty\||\|model 33 teletype, - bel=^G, cols#72, cr=^M, cud1=^J, hc, ind=^J, os,\s+1 + bel=^G, cols#72, cr=^M, cud1=^J, hc, ind=^J, os,\s+1 .\".in +2 .ft R +.fi .PP while the Lear Siegler \s-1ADM-3\s0 is described as .PP @@ -286,8 +366,8 @@ while the Lear Siegler \s-1ADM-3\s0 is described as .ft CW .\".in -2 \s-1adm3\||\|3\||\|lsi adm3, - am, bel=^G, clear=^Z, cols#80, cr=^M, cub1=^H, cud1=^J, - ind=^J, lines#24,\s+1 + am, bel=^G, clear=^Z, cols#80, cr=^M, cub1=^H, cud1=^J, + ind=^J, lines#24,\s+1 .\".in +2 .ft R .fi @@ -296,9 +376,8 @@ while the Lear Siegler \s-1ADM-3\s0 is described as .PP Cursor addressing and other strings requiring parameters in the terminal are described by a -parameterized string capability, with -.IR printf (3) -like escapes \fB%x\fR in it. +parameterized string capability, +with \fIprintf\fP-like escapes such as \fI%x\fR in it. For example, to address the cursor, the .B cup capability is given, using two parameters: @@ -321,34 +400,34 @@ e.g., in the \fBsgr\fP string. The \fB%\fR encodings have the following meanings: .PP .TP 5 -\s-1%% -outputs `%' +\fB%%\fP +outputs \*(``%\*('' .TP -%\fI[[\fP:\fI]flags][width[.precision]][\fPdoxXs\fI]\fP -as in \fBprintf\fP, flags are [\-+#] and space. -Use a `:' to allow the next character to be a `\-' flag, +\fB%\fP\fI[[\fP:\fI]flags][width[.precision]][\fP\fBdoxXs\fP\fI]\fP +as in \fBprintf\fP, flags are \fI[\-+#]\fP and \fIspace\fP. +Use a \*(``:\*('' to allow the next character to be a \*(``\-\*('' flag, avoiding interpreting "%\-" as an operator. .TP -%c +\f(CW%c\fP print pop() like %c in \fBprintf\fP .TP -%s +\fB%s\fP print pop() like %s in \fBprintf\fP .TP -%p[1\-9] +\fB%p\fP\fI[1\-9]\fP push \fIi\fP'th parameter .TP -%P[a\-z] -set dynamic variable [a\-z] to pop() +\fB%P\fP\fI[a\-z]\fP +set dynamic variable \fI[a\-z]\fP to pop() .TP -%g[a\-z] -get dynamic variable [a\-z] and push it +\fB%g\fP\fI[a\-z]/\fP +get dynamic variable \fI[a\-z]\fP and push it .TP -%P[A\-Z] -set static variable [a\-z] to pop() +\fB%P\fP\fI[A\-Z]\fP +set static variable \fI[a\-z]\fP to \fIpop()\fP .TP -%g[A\-Z] -get static variable [a\-z] and push it +\fB%g\fP\fI[A\-Z]\fP +get static variable \fI[a\-z]\fP and push it .IP The terms "static" and "dynamic" are misleading. Historically, these are simply two different sets of variables, @@ -356,48 +435,48 @@ whose values are not reset between calls to \fBtparm\fP. However, that fact is not documented in other implementations. Relying on it will adversely impact portability to other implementations. .TP -%'\fIc\fP' +\fB%'\fP\fIc\fP\fB'\fP char constant \fIc\fP .TP -%{\fInn\fP} +\fB%{\fP\fInn\fP\fB}\fP integer constant \fInn\fP .TP -%l +\fB%l\fP push strlen(pop) .TP -%+ %\- %* %/ %m -arithmetic (%m is mod): push(pop() op pop()) +\fB%+\fP, \fB%\-\fP, \fB%*\fP, \fB%/\fP, \fB%m\fP +arithmetic (%m is mod): \fIpush(pop() op pop())\fP .TP -%& %| %^ -bit operations (AND, OR and exclusive-OR): push(pop() op pop()) +\fB%&\fP, \fB%|\fP, \fB%^\fP +bit operations (AND, OR and exclusive-OR): \fIpush(pop() op pop())\fP .TP -%= %> %< -logical operations: push(pop() op pop()) +\fB%=\fP, \fB%>\fP, \fB%<\fP +logical operations: \fIpush(pop() op pop())\fP .TP -%A, %O +\fB%A\fP, \fB%O\fP logical AND and OR operations (for conditionals) .TP -%! %~ +\fB%!\fP, \fB%~\fP unary operations (logical and bit complement): push(op pop()) .TP -%i +\fB%i\fP add 1 to first two parameters (for ANSI terminals) .TP -%? \fIexpr\fP %t \fIthenpart\fP %e \fIelsepart\fP %; +\fB%?\fP \fIexpr\fP \fB%t\fP \fIthenpart\fP \fB%e\fP \fIelsepart\fP \fB%;\fP This forms an if-then-else. -The %e \fIelsepart\fP is optional. -Usually the %? \fIexpr\fP part pushes a value onto the stack, -and %t pops it from the stack, testing if it is nonzero (true). -If it is zero (false), control passes to the %e (else) part. +The \fB%e\fP \fIelsepart\fP is optional. +Usually the \fB%?\fP \fIexpr\fP part pushes a value onto the stack, +and \fB%t\fP pops it from the stack, testing if it is nonzero (true). +If it is zero (false), control passes to the \fB%e\fP (else) part. .IP It is possible to form else-if's a la Algol 68: .RS -%? c\d1\u %t b\d1\u %e c\d2\u %t b\d2\u %e c\d3\u %t b\d3\u %e c\d4\u %t b\d4\u %e %; +\fB%?\fP c\d1\u \fB%t\fP b\d1\u \fB%e\fP c\d2\u \fB%t\fP b\d2\u \fB%e\fP c\d3\u \fB%t\fP b\d3\u \fB%e\fP c\d4\u \fB%t\fP b\d4\u \fB%e\fP \fB%;\fP .RE .IP where c\di\u are conditions, b\di\u are bodies. .IP -Use the \fB\-f\fP option of \fBtic\fP or \fB@INFOCMP@\fP to see +Use the \fB\-f\fP option of \fB@TIC@\fP or \fB@INFOCMP@\fP to see the structure of if-then-else's. Some strings, e.g., \fBsgr\fP can be very complicated when written on one line. @@ -405,7 +484,7 @@ The \fB\-f\fP option splits the string into lines with the parts indented. .PP Binary operations are in postfix form with the operands in the usual order. That is, to get x\-5 one would use "%gx%{5}%-". -%P and %g variables are +\fB%P\fP and \fB%g\fP variables are persistent across escape-string evaluations. .PP Consider the HP2645, which, to get to row 3 and column 12, needs @@ -429,7 +508,7 @@ This turns out to be essential for the Ann Arbor 4080.) .PP A final example is the \s-1LSI ADM\s0-3a, which uses row and column offset by a blank character, thus \*(lqcup=\eE=%p1%' '%+%c%p2%' '%+%c\*(rq. -After sending `\eE=', this pushes the first parameter, pushes the +After sending \*(``\eE=\*('', this pushes the first parameter, pushes the ASCII value for a space (32), adds them (pushing the sum on the stack in place of the two previous values) and outputs that value as a character. Then the same is done for the second parameter. @@ -593,6 +672,7 @@ Other terminals, such as the Concept 100 and the Perkin Elmer Owl, make a distinction between typed and untyped blanks on the screen, shifting upon an insert or delete only to an untyped blank on the screen which is either eliminated, or expanded to two untyped blanks. +.PP You can determine the kind of terminal you have by clearing the screen and then typing text separated by cursor motions. @@ -608,6 +688,7 @@ shifts over to the \*(lqdef\*(rq which then move together around the end of the current line and onto the next as you insert, you have the second type of terminal, and should give the capability \fBin\fR, which stands for \*(lqinsert null\*(rq. +.PP While these are two logically separate attributes (one line versus multi-line insert mode, and special treatment of untyped spaces) we have seen no terminals whose insert mode cannot be described with the single attribute. @@ -642,7 +723,7 @@ If post insert padding is needed, give this as a number of milliseconds in \fBip\fR (a string option). Any other sequence which may need to be sent after an insert of a single character may also be given in \fBip\fR. -If your terminal needs both to be placed into an `insert mode' and +If your terminal needs both to be placed into an \*(``insert mode\*('' and a special code to precede each inserted character, then both .BR smir / rmir and @@ -792,6 +873,7 @@ either standout or reverse modes are turned on. .PP Writing out the above sequences, along with their dependencies yields .PP +.ne 11 .TS center; l l l @@ -799,6 +881,7 @@ l l l lw18 lw14 lw18. \fBsequence when to output terminfo translation\fP +.ft CW \\E[0 always \\E[0 ;1 if p1 or p6 %?%p1%p6%|%t;1%; ;4 if p2 %?%p2%|%t;4%; @@ -807,14 +890,17 @@ lw18 lw14 lw18. ;8 if p7 %?%p7%|%t;8%; m always m ^N or ^O if p9 ^N, else ^O %?%p9%t^N%e^O%; +.ft R .TE .PP Putting this all together into the sgr sequence gives: .PP +.ft CW .nf - sgr=\\E[0%?%p1%p6%|%t;1%;%?%p2%t;4%;%?%p1%p3%|%t;7%; - %?%p4%t;5%;%?%p7%t;8%;m%?%p9%t\\016%e\\017%;, + sgr=\\E[0%?%p1%p6%|%t;1%;%?%p2%t;4%;%?%p4%t;5%; + %?%p1%p3%|%t;7%;%?%p7%t;8%;m%?%p9%t\\016%e\\017%;, .fi +.ft R .PP Remember that if you specify sgr, you must also specify sgr0. Also, some implementations rely on sgr being given if sgr0 is, @@ -824,9 +910,9 @@ which have no sgr string. The only drawback to adding an sgr string is that termcap also assumes that sgr0 does not exit alternate character set mode. .PP -Terminals with the ``magic cookie'' glitch +Terminals with the \*(``magic cookie\*('' glitch .RB ( xmc ) -deposit special ``cookies'' when they receive mode-setting sequences, +deposit special \*(``cookies\*('' when they receive mode-setting sequences, which affect the display algorithm rather than having extra bits for each character. Some terminals, such as the HP 2621, automatically leave standout @@ -871,6 +957,7 @@ to the unshifted HP 2621 keys). If the keypad can be set to transmit or not transmit, give these codes as \fBsmkx\fR and \fBrmkx\fR. Otherwise the keypad is assumed to always transmit. +.PP The codes sent by the left arrow, right arrow, up arrow, down arrow, and home keys can be given as \fBkcub1, kcuf1, kcuu1, kcud1, \fRand\fB khome\fR respectively. @@ -878,41 +965,60 @@ If there are function keys such as f0, f1, ..., f10, the codes they send can be given as \fBkf0, kf1, ..., kf10\fR. If these keys have labels other than the default f0 through f10, the labels can be given as \fBlf0, lf1, ..., lf10\fR. +.PP The codes transmitted by certain other special keys can be given: +.bP .B kll (home down), +.bP .B kbs (backspace), +.bP .B ktbc (clear all tabs), +.bP .B kctab (clear the tab stop in this column), +.bP .B kclr (clear screen or erase key), +.bP .B kdch1 (delete character), +.bP .B kdl1 (delete line), +.bP .B krmir (exit insert mode), +.bP .B kel (clear to end of line), +.bP .B ked (clear to end of screen), +.bP .B kich1 (insert character or enter insert mode), +.bP .B kil1 (insert line), +.bP .B knp (next page), +.bP .B kpp (previous page), +.bP .B kind (scroll forward/down), +.bP .B kri (scroll backward/up), +.bP .B khts (set a tab stop in this column). +.PP In addition, if the keypad has a 3 by 3 array of keys including the four arrow keys, the other five keys can be given as .BR ka1 , @@ -956,7 +1062,7 @@ If the terminal has hardware tabs, the command to advance to the next tab stop can be given as .B ht (usually control I). -A ``back-tab'' command which moves leftward to the preceding tab stop can +A \*(``back-tab\*('' command which moves leftward to the preceding tab stop can be given as .BR cbt . By convention, if the teletype modes indicate that tabs are being @@ -974,7 +1080,7 @@ the numeric parameter .B it is given, showing the number of spaces the tabs are set to. This is normally used by the -.IR tset +.IR @TSET@ command to determine whether to set the mode for hardware tab expansion, and whether to set the tab stops. If the terminal has tab stops that can be saved in non-volatile memory, @@ -1131,7 +1237,7 @@ Only the first character of the string is used. .PP .SS Status Lines -Some terminals have an extra `status line' which is not normally used by +Some terminals have an extra \*(``status line\*('' which is not normally used by software (and thus not counted in the terminal's \fBlines\fR capability). .PP The simplest case is a status line which is cursor-addressable but not @@ -1223,7 +1329,7 @@ character pairs right to left in sequence; these become the ACSC string. .PP .SS Color Handling .PP -Most color terminals are either `Tektronix-like' or `HP-like'. +Most color terminals are either \*(``Tektronix-like\*('' or \*(``HP-like\*(''. Tektronix-like terminals have a predefined set of N colors (where N usually 8), and can set character-cell foreground and background characters independently, mixing them @@ -1303,6 +1409,7 @@ magenta \fBCOLOR_MAGENTA\fR 5 max,0,max yellow \fBCOLOR_YELLOW\fR 6 max,max,0 white \fBCOLOR_WHITE\fR 7 max,max,max .TE +.PP It is important to not confuse the two sets of color capabilities; otherwise red/blue will be interchanged on the display. .PP @@ -1339,18 +1446,25 @@ attributes understood by \fBcurses\fR is as follows: .PP .TS center; -l c c -lw25 lw2 lw10. -\fBAttribute Bit Decimal\fR -A_STANDOUT 0 1 -A_UNDERLINE 1 2 -A_REVERSE 2 4 -A_BLINK 3 8 -A_DIM 4 16 -A_BOLD 5 32 -A_INVIS 6 64 -A_PROTECT 7 128 -A_ALTCHARSET 8 256 +l l l l +lw20 lw2 lw10 lw10. +\fBAttribute Bit Decimal Set by\fR +A_STANDOUT 0 1 sgr +A_UNDERLINE 1 2 sgr +A_REVERSE 2 4 sgr +A_BLINK 3 8 sgr +A_DIM 4 16 sgr +A_BOLD 5 32 sgr +A_INVIS 6 64 sgr +A_PROTECT 7 128 sgr +A_ALTCHARSET 8 256 sgr +A_HORIZONTAL 9 512 sgr1 +A_LEFT 10 1024 sgr1 +A_LOW 11 2048 sgr1 +A_RIGHT 12 4096 sgr1 +A_TOP 13 8192 sgr1 +A_VERTICAL 14 16384 sgr1 +A_ITALIC 15 32768 sitm .TE .PP For example, on many IBM PC consoles, the underline attribute collides with the @@ -1389,7 +1503,7 @@ this can be indicated with the parameterized string .BR rep . The first parameter is the character to be repeated and the second is the number of times to repeat it. -Thus, tparm(repeat_char, 'x', 10) is the same as `xxxxxxxxxx'. +Thus, tparm(repeat_char, 'x', 10) is the same as \*(``xxxxxxxxxx\*(''. .PP If the terminal has a settable command character, such as the \s-1TEKTRONIX\s+1 4025, this can be indicated with @@ -1420,13 +1534,13 @@ how to talk to the terminal. .I virtual terminal descriptions for which the escape sequences are known.) .PP -If the terminal has a ``meta key'' which acts as a shift key, +If the terminal has a \*(``meta key\*('' which acts as a shift key, setting the 8th bit of any character transmitted, this fact can be indicated with .BR km . Otherwise, software will assume that the 8th bit is parity and it will usually be cleared. -If strings exist to turn this ``meta mode'' on and off, they +If strings exist to turn this \*(``meta mode\*('' on and off, they can be given as .B smm and @@ -1470,7 +1584,7 @@ is in effect. .PP .SS Glitches and Braindamage .PP -Hazeltine terminals, which do not allow `~' characters to be displayed should +Hazeltine terminals, which do not allow \*(``~\*('' characters to be displayed should indicate \fBhz\fR. .PP Terminals which ignore a line-feed immediately after an \fBam\fR wrap, @@ -1485,10 +1599,10 @@ is required to get rid of standout .PP Teleray terminals, where tabs turn all characters moved over to blanks, should indicate \fBxt\fR (destructive tabs). -Note: the variable indicating this is now `dest_tabs_magic_smso'; in +Note: the variable indicating this is now \*(``dest_tabs_magic_smso\*(''; in older versions, it was teleray_glitch. This glitch is also taken to mean that it is not possible to position -the cursor on top of a ``magic cookie'', +the cursor on top of a \*(``magic cookie\*('', that to erase standout mode it is instead necessary to use delete and insert line. The ncurses implementation ignores this glitch. @@ -1499,7 +1613,7 @@ or control C characters, has indicating that the f1 key is used for escape and f2 for control C. (Only certain Superbees have this problem, depending on the ROM.) Note that in older terminfo versions, this capability was called -`beehive_glitch'; it is now `no_esc_ctl_c'. +\*(``beehive_glitch\*(''; it is now \*(``no_esc_ctl_c\*(''. .PP Other specific terminal problems may be corrected by adding more capabilities of the form \fBx\fR\fIx\fR. @@ -1524,8 +1638,10 @@ those brought in by \fBuse\fR references. A capability can be canceled by placing \fBxx@\fR to the left of the use reference that imports it, where \fIxx\fP is the capability. For example, the entry +.RS .PP - 2621\-nl, smkx@, rmkx@, use=2621, +2621\-nl, smkx@, rmkx@, use=2621, +.RE .PP defines a 2621\-nl that does not have the \fBsmkx\fR or \fBrmkx\fR capabilities, and hence does not turn on the function key labels when in visual mode. @@ -1570,19 +1686,15 @@ length of the entry as it exists in /etc/termcap, minus the backslash-newline pairs, which \fBtgetent()\fP strips out while reading it. Some termcap libraries strip off the final newline, too (GNU termcap does not). Now suppose: -.TP 5 -* +.bP a termcap entry before expansion is more than 1023 bytes long, -.TP 5 -* +.bP and the application has only allocated a 1k buffer, -.TP 5 -* +.bP and the termcap library (like the one in BSD/OS 1.1 and GNU) reads the whole entry into the buffer, no matter what its length, to see if it is the entry it wants, -.TP 5 -* +.bP and \fBtgetent()\fP is searching for a terminal type that either is the long entry, appears in the termcap file after the long entry, or does not appear in the file at all (so that \fBtgetent()\fP has to search @@ -1625,6 +1737,11 @@ of terminfo (under HP\-UX and AIX) which diverged from System V terminfo after SVr1, and have added extension capabilities to the string table that (in the binary format) collide with System V and XSI Curses extensions. .SH EXTENSIONS +.PP +Searching for terminal descriptions in +\fB$HOME/.terminfo\fR and TERMINFO_DIRS +is not supported by older implementations. +.PP Some SVr4 \fBcurses\fR implementations, and all previous to SVr4, do not interpret the %A and %O operators in parameter strings. .PP @@ -1652,6 +1769,15 @@ The \fBncurses\fR wants to interpret it as \fBKEY_MOUSE\fR, for use by terminals and emulators like xterm that can return mouse-tracking information in the keyboard-input stream. .PP +X/Open Curses does not mention italics. +Portable applications must assume that numeric capabilities are +signed 16-bit values. +This includes the \fIno_color_video\fP (ncv) capability. +The 32768 mask value used for italics with ncv can be confused with +an absent or cancelled ncv. +If italics should work with colors, +then the ncv value must be specified, even if it is zero. +.PP Different commercial ports of terminfo and curses support different subsets of the XSI Curses standard and (in some cases) different extension sets. Here @@ -1666,9 +1792,9 @@ capability (\fBset_pglen\fR). .PP \fBSVr1, Ultrix\fR \-\- These support a restricted subset of terminfo capabilities. -The booleans -end with \fBxon_xoff\fR; the numerics with \fBwidth_status_line\fR; and the -strings with \fBprtr_non\fR. +The booleans end with \fBxon_xoff\fR; +the numerics with \fBwidth_status_line\fR; +and the strings with \fBprtr_non\fR. .PP \fBHP/UX\fR \-\- Supports the SVr1 subset, plus the SVr[234] numerics \fBnum_labels\fR, diff --git a/man/tic.1m b/man/tic.1m index cf4147fc110f..5c3a63fa9cbd 100644 --- a/man/tic.1m +++ b/man/tic.1m @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 1998-2012,2013 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 * @@ -26,19 +26,29 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: tic.1m,v 1.47 2010/12/04 18:38:55 tom Exp $ +.\" $Id: tic.1m,v 1.58 2013/07/20 19:31:25 tom Exp $ .TH @TIC@ 1M "" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' .ds n 5 .ds d @TERMINFO@ +.de bP +.IP \(bu 4 +.. .SH NAME -\fBtic\fR \- the \fIterminfo\fR entry-description compiler +\fB@TIC@\fR \- the \fIterminfo\fR entry-description compiler .SH SYNOPSIS -\fBtic\fR +\fB@TIC@\fR [\fB\-\ +0\ 1\ C\ +D\ G\ I\ +K\ L\ N\ T\ @@ -61,31 +71,69 @@ x\ \fIfile\fR .br .SH DESCRIPTION -The command \fBtic\fR translates a \fBterminfo\fR file from source +The \fB@TIC@\fR command translates a \fBterminfo\fR file from source format into compiled format. The compiled format is necessary for use with the library routines in \fBncurses\fR(3X). .PP -The results are normally placed in the system terminfo -directory \fB\*d\fR. -There are two ways to change this behavior. +As described in \fBterm\fR(\*n), the database may be either a directory +tree (one file per terminal entry) or a hashed database (one record per entry). +The \fB@TIC@\fR command writes only one type of entry, +depending on how it was built: +.bP +For directory trees, the top-level directory, e.g., /usr/share/terminfo, +specifies the location of the database. +.bP +For hashed databases, a filename is needed. +If the given file is not found by that name, +but can be found by adding the suffix ".db", +then that is used. +.IP +The default name for the hashed database is the same as the +default directory name (only adding a ".db" suffix). .PP -First, you may override the system default by setting the variable -\fBTERMINFO\fR in your shell environment to a valid (existing) directory name. +In either case (directory or hashed database), +\fB@TIC@\fP will create the container if it does not exist. +For a directory, this would be the "terminfo" leaf, +versus a "terminfo.db" file. .PP -Secondly, if \fBtic\fR cannot get access to \fI\*d\fR or your TERMINFO -directory, it looks for the directory \fI$HOME/.terminfo\fR; if that directory -exists, the entry is placed there. +The results are normally placed in the system terminfo database \fB\*d\fR. +The compiled terminal description can be placed +in a different terminfo database. +There are two ways to achieve this: +.bP +First, you may override the system default either by +using the \fB\-o\fP option, +or by setting the variable \fBTERMINFO\fR +in your shell environment to a valid database location. +.bP +Secondly, if \fB@TIC@\fR cannot write in \fI\*d\fR +or the location specified using your TERMINFO variable, +it looks for the directory \fI$HOME/.terminfo\fR +(or hashed database \fI$HOME/.terminfo.db)\fR; +if that location exists, the entry is placed there. .PP -Libraries that read terminfo entries are expected to check for a TERMINFO -directory first, look at \fI$HOME/.terminfo\fR if TERMINFO is not set, and -finally look in \fI\*d\fR. +Libraries that read terminfo entries are expected to check in succession +.bP +a location specified with the TERMINFO environment variable, +.bP +\fI$HOME/.terminfo\fR, +.bP +directories listed in the TERMINFO_DIRS environment variable, +.bP +a compiled-in list of directories (@TERMINFO_DIRS@), and +.bP +the system terminfo database (\fI\*d\fR). +.SS OPTIONS +.TP +\fB\-0\fR +restricts the output to a single line .TP \fB\-1\fR restricts the output to a single column .TP \fB\-a\fR -tells \fBtic\fP to retain commented-out capabilities rather than discarding +tells \fB@TIC@\fP to retain commented-out capabilities rather than discarding them. Capabilities are commented by prefixing them with a period. This sets the \fB\-x\fR option, because it treats the commented-out @@ -101,16 +149,30 @@ names, but also translates terminfo strings to termcap format. Capabilities that are not translatable are left in the entry under their terminfo names but commented out with two preceding dots. +The actual format used incorporates some improvements for escaped characters +from terminfo format. +For a stricter BSD-compatible translation, add the \fB\-K\fR option. .TP \fB\-c\fR -tells \fBtic\fP to only check \fIfile\fR for errors, including syntax problems and +tells \fB@TIC@\fP to only check \fIfile\fR for errors, including syntax problems and bad use links. If you specify \fB\-C\fR (\fB\-I\fR) with this option, the code will print warnings about entries which, after use resolution, are more than 1023 (4096) bytes long. -Due to a fixed buffer length in older termcap -libraries (and a documented limit in terminfo), these entries may cause core -dumps. +Due to a fixed buffer length in older termcap libraries, +as well as buggy checking for the buffer length +(and a documented limit in terminfo), +these entries may cause core +dumps with other implementations. +.TP +\fB\-D\fR +tells \fB@TIC@\fP to print the database locations that it knows about, and exit. +The first location shown is the one to which it would write compiled +terminal descriptions. +If \fB@TIC@\fP is not able to find a writable database location +according to the rules summarized above, +it will print a diagnostic and exit with an error rather than +printing a list of database locations. .TP \fB\-e \fR\fInames\fR Limit writes and translations to the following comma-separated list of @@ -137,6 +199,10 @@ rather than their decimal equivalents. \fB\-I\fR Force source translation to terminfo format. .TP +\fB\-K\fR +Suppress some longstanding ncurses extensions to termcap format, +e.g., "\\s" for space. +.TP \fB\-L\fR Force source translation to terminfo format using the long C variable names listed in <\fBterm.h\fR> @@ -155,9 +221,8 @@ This option forces a more literal translation that also preserves the obsolete capabilities. .TP \fB\-o\fR\fIdir\fR -Write compiled entries to given directory. -Overrides the TERMINFO environment -variable. +Write compiled entries to given database location. +Overrides the TERMINFO environment variable. .TP \fB\-R\fR\fIsubset\fR Restrict output to a given subset. @@ -177,7 +242,7 @@ version 1.3 or BSD termcap through 4.3BSD) that does not handle multiple tc capabilities per entry. .TP \fB\-s\fR -Summarize the compile by showing the directory into which entries +Summarize the compile by showing the database location into which entries are written, and the number of entries which are compiled. .TP \fB\-T\fR @@ -186,12 +251,12 @@ This is mainly useful for testing and analysis, since the compiled descriptions are limited (e.g., 1023 for termcap, 4096 for terminfo). .TP \fB\-t\fR -tells \fBtic\fP to discard commented-out capabilities. +tells \fB@TIC@\fP to discard commented-out capabilities. Normally when translating from terminfo to termcap, untranslatable capabilities are commented-out. .TP 5 \fB\-U\fR -tells \fBtic\fP to not post-process the data after parsing the source file. +tells \fB@TIC@\fP to not post-process the data after parsing the source file. Normally, it infers data which is commonly missing in older terminfo data, or in termcaps. .TP @@ -200,31 +265,13 @@ reports the version of ncurses which was used in this program, and exits. .TP \fB\-v\fR\fIn\fR specifies that (verbose) output be written to standard error trace -information showing \fBtic\fR's progress. +information showing \fB@TIC@\fR's progress. The optional parameter \fIn\fR is a number from 1 to 10, inclusive, indicating the desired level of detail of information. If \fIn\fR is omitted, the default level is 1. If \fIn\fR is specified and greater than 1, the level of detail is increased. -.TP -\fB\-w\fR\fIn\fR -specifies the width of the output. -The parameter is optional. -If it is omitted, it defaults to 60. -.TP -\fB\-x\fR -Treat unknown capabilities as user-defined. -That is, if you supply a capability name which \fBtic\fP does not recognize, -it will infer its type (boolean, number or string) from the syntax and -make an extended table entry for that. -User-defined capability strings -whose name begins with ``k'' are treated as function keys. -.TP -\fIfile\fR -contains one or more \fBterminfo\fR terminal descriptions in source -format [see \fBterminfo\fR(\*n)]. -Each description in the file -describes the capabilities of a particular terminal. +.RS .PP The debug flag levels are as follows: .TP @@ -232,7 +279,7 @@ The debug flag levels are as follows: Names of files created and linked .TP 2 -Information related to the ``use'' facility +Information related to the \*(``use\*('' facility .TP 3 Statistics from the hashing algorithm @@ -250,19 +297,42 @@ List of tokens encountered by scanner All values computed in construction of the hash table .LP If the debug level \fIn\fR is not given, it is taken to be one. +.RE +.TP +\fB\-w\fR\fIn\fR +specifies the width of the output. +The parameter is optional. +If it is omitted, it defaults to 60. +.TP +\fB\-x\fR +Treat unknown capabilities as user-defined. +That is, if you supply a capability name which \fB@TIC@\fP does not recognize, +it will infer its type (boolean, number or string) from the syntax and +make an extended table entry for that. +User-defined capability strings +whose name begins with \*(``k\*('' are treated as function keys. +.SS PARAMETERS +.TP +\fIfile\fR +contains one or more \fBterminfo\fR terminal descriptions in source +format [see \fBterminfo\fR(\*n)]. +Each description in the file +describes the capabilities of a particular terminal. +.IP +If \fIfile\fR is \*(``-\*('', then the data is read from the standard input. +The \fIfile\fR parameter may also be the path of a character-device. +.SS PROCESSING .PP -All but one of the capabilities recognized by \fBtic\fR are documented +All but one of the capabilities recognized by \fB@TIC@\fR are documented in \fBterminfo\fR(\*n). The exception is the \fBuse\fR capability. .PP When a \fBuse\fR=\fIentry\fR\-\fIname\fR field is discovered in a -terminal entry currently being compiled, \fBtic\fR reads in the binary +terminal entry currently being compiled, \fB@TIC@\fR reads in the binary from \fB\*d\fR to complete the entry. (Entries created from \fIfile\fR will be used first. -If the environment variable -\fBTERMINFO\fR is set, that directory is searched instead of -\fB\*d\fR.) \fBtic\fR duplicates the capabilities in +\fB@TIC@\fR duplicates the capabilities in \fIentry\fR\-\fIname\fR for the current entry, with the exception of those capabilities that explicitly are defined in the current entry. .PP @@ -272,9 +342,6 @@ capabilities in \fIentry\fR_\fIname\fR_\fI2\fR must also appear in \fBentry_name_1\fR before \fBuse=\fR for these capabilities to be canceled in \fBentry_name_1\fR. .PP -If the environment variable \fBTERMINFO\fR is set, the compiled -results are placed there instead of \fB\*d\fR. -.PP Total compiled entries cannot exceed 4096 bytes. The name field cannot exceed 512 bytes. @@ -282,14 +349,14 @@ Terminal names exceeding the maximum alias length (32 characters on systems with long filenames, 14 characters otherwise) will be truncated to the maximum alias length and a warning message will be printed. .SH COMPATIBILITY -There is some evidence that historic \fBtic\fR implementations treated +There is some evidence that historic \fB@TIC@\fR implementations treated description fields with no whitespace in them as additional aliases or short names. -This \fBtic\fR does not do that, but it does warn when +This \fB@TIC@\fR does not do that, but it does warn when description fields may be treated that way and check them for dangerous characters. .SH EXTENSIONS -Unlike the stock SVr4 \fBtic\fR command, this implementation can actually +Unlike the SVr4 \fB@TIC@\fR command, this implementation can actually compile termcap sources. In fact, entries in terminfo and termcap syntax can be mixed in a single source file. @@ -298,16 +365,20 @@ termcap names taken to be equivalent to terminfo names. .PP The SVr4 manual pages are not clear on the resolution rules for \fBuse\fR capabilities. -This implementation of \fBtic\fR will find \fBuse\fR targets anywhere +This implementation of \fB@TIC@\fR will find \fBuse\fR targets anywhere in the source file, or anywhere in the file tree rooted at \fBTERMINFO\fR (if -\fBTERMINFO\fR is defined), or in the user's \fI$HOME/.terminfo\fR directory -(if it exists), or (finally) anywhere in the system's file tree of +\fBTERMINFO\fR is defined), +or in the user's \fI$HOME/.terminfo\fR database +(if it exists), +or (finally) anywhere in the system's file tree of compiled entries. .PP -The error messages from this \fBtic\fR have the same format as GNU C +The error messages from this \fB@TIC@\fR have the same format as GNU C error messages, and can be parsed by GNU Emacs's compile facility. .PP The +\fB\-0\fR, +\fB\-1\fR, \fB\-C\fR, \fB\-G\fR, \fB\-I\fR, @@ -329,7 +400,7 @@ are not supported under SVr4. The SVr4 \fB\-c\fR mode does not report bad use links. .PP System V does not compile entries to or read entries from your -\fI$HOME/.terminfo\fR directory unless TERMINFO is explicitly set to it. +\fI$HOME/.terminfo\fR database unless TERMINFO is explicitly set to it. .SH FILES .TP 5 \fB\*d/?/*\fR @@ -340,6 +411,7 @@ Compiled terminal description database. \fB@INFOTOCAP@\fR(1M), \fB@TOE@\fR(1M), \fBcurses\fR(3X), +\fBterm\fR(\*n). \fBterminfo\fR(\*n). .PP This describes \fBncurses\fR diff --git a/man/toe.1m b/man/toe.1m index c8eb4812aca6..26af319b66a5 100644 --- a/man/toe.1m +++ b/man/toe.1m @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 1998-2008,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 1998-2010,2011 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 * @@ -26,19 +26,19 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: toe.1m,v 1.23 2010/12/04 18:40:45 tom Exp $ +.\" $Id: toe.1m,v 1.26 2012/01/01 00:40:51 tom Exp $ .TH @TOE@ 1M "" .ds n 5 .ds d @TERMINFO@ .SH NAME -\fBtoe\fR \- table of (terminfo) entries +\fB@TOE@\fR \- table of (terminfo) entries .SH SYNOPSIS -\fBtoe\fR [\fB\-v\fR[\fIn\fR]] [\fB\-ahuUV\fR] \fIfile...\fR +\fB@TOE@\fR [\fB\-v\fR[\fIn\fR]] [\fB\-ahsuUV\fR] \fIfile...\fR .br .SH DESCRIPTION .PP With no options, -\fBtoe\fR lists all available terminal types by primary name +\fB@TOE@\fR lists all available terminal types by primary name with descriptions. File arguments specify the directories to be scanned; if no such arguments are given, @@ -52,6 +52,15 @@ There are other options intended for use by terminfo file maintainers: \fB\-a\fR report on all of the terminal databases which ncurses would search, rather than only the first one that it finds. +.IP +If the \fB\-s\fR is also given, \fB@TOE@\fR +adds a column to the report, +showing (like \fBconflict\fP(1)) which entries which +belong to a given terminal database. +An "*" marks entries which differ, and "+" marks equivalent entries. +.TP +\fB\-s\fR +sort the output by the entry names. .TP \fB\-u\fR \fIfile\fR says to write a report to the standard output, @@ -78,7 +87,7 @@ followed by a newline. .TP \fB\-v\fR\fIn\fR specifies that (verbose) output be written to standard error, -showing \fBtoe\fR's progress. +showing \fB@TOE@\fR's progress. The optional parameter \fIn\fR is a number from 1 to 10, interpreted as for \fB@TIC@\fR(1M). .TP diff --git a/man/tput.1 b/man/tput.1 index 665c71199d28..a1b81bcb08c5 100644 --- a/man/tput.1 +++ b/man/tput.1 @@ -1,6 +1,6 @@ '\" t .\"*************************************************************************** -.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 1998-2011,2012 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 * @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: tput.1,v 1.29 2010/12/04 18:41:07 tom Exp $ +.\" $Id: tput.1,v 1.32 2012/07/14 21:06:45 tom Exp $ .TH @TPUT@ 1 "" .ds d @TERMINFO@ .ds n 1 @@ -77,11 +77,12 @@ For a complete list of capabilities and the \fIcapname\fR associated with each, see \fBterminfo\fR(5). .TP \fB\-T\fR\fItype\fR -indicates the \fItype\fR of terminal. Normally this option is +indicates the \fItype\fR of terminal. +Normally this option is unnecessary, because the default is taken from the environment -variable \fBTERM\fR. If \fB\-T\fR is specified, then the shell -variables \fBLINES\fR and \fBCOLUMNS\fR will be ignored,and the -operating system will not be queried for the actual screen size. +variable \fBTERM\fR. +If \fB\-T\fR is specified, then the shell +variables \fBLINES\fR and \fBCOLUMNS\fR will also be ignored. .TP \fIcapname\fR indicates the capability from the \fBterminfo\fR database. When @@ -159,7 +160,7 @@ name in the first line of the terminal's description in the .PP If \fB@TPUT@\fR is invoked by a link named \fBreset\fR, this has the same effect as \fB@TPUT@ reset\fR. -See \fBtset\fR for comparison, which has similar behavior. +See \fB@TSET@\fR for comparison, which has similar behavior. .SH EXAMPLES .TP 5 \fB@TPUT@ init\fR @@ -275,7 +276,7 @@ In that case, the exit code is set to 4 + \fBerrno\fR. .PP Any other exit code indicates an error; see the DIAGNOSTICS section. .SH DIAGNOSTICS -\fBtput\fR prints the following error messages and sets the corresponding exit +\fB@TPUT@\fR prints the following error messages and sets the corresponding exit codes. .PP .ne 15 @@ -303,17 +304,29 @@ AT&T/USL curses before SVr4. .PP X/Open documents only the operands for \fBclear\fP, \fBinit\fP and \fBreset\fP. In this implementation, \fBclear\fP is part of the \fIcapname\fR support. -Other implementations of \fBtput\fP on +Other implementations of \fB@TPUT@\fP on SVr4-based systems such as Solaris, IRIX64 and HPUX as well as others such as AIX and Tru64 provide support for \fIcapname\fR operands. +.PP A few platforms such as FreeBSD and NetBSD recognize termcap names rather -than terminfo capability names in their respective \fBtput\fP commands. +than terminfo capability names in their respective \fB@TPUT@\fP commands. +.PP +Most implementations which provide support for \fIcapname\fR operands +use the \fItparm\fP function to expand parameters in it. +That function expects a mixture of numeric and string parameters, +requiring \fB@TPUT@\fP to know which type to use. +This implementation uses a table to determine that for +the standard \fIcapname\fR operands, and an internal library +function to analyze nonstandard \fIcapname\fR operands. +Other implementations may simply guess that an operand containing only digits +is intended to be a number. .SH SEE ALSO \fB@CLEAR@\fR(1), \fBstty\fR(1), \fBtabs\fR(\*n), -\fBterminfo\fR(5). +\fBterminfo\fR(5), +\fBcurs_termcap\fR(3X). .PP This describes \fBncurses\fR version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@). diff --git a/man/tset.1 b/man/tset.1 index 9743f5b5a7c8..e151e7532f41 100644 --- a/man/tset.1 +++ b/man/tset.1 @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 1998-2008,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 1998-2011,2013 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 * @@ -26,12 +26,16 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: tset.1,v 1.25 2010/12/04 18:38:55 tom Exp $ +.\" $Id: tset.1,v 1.29 2013/12/21 22:15:53 tom Exp $ .TH @TSET@ 1 "" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' .SH NAME -\fBtset\fR, \fBreset\fR \- terminal initialization +\fB@TSET@\fR, \fBreset\fR \- terminal initialization .SH SYNOPSIS -\fBtset\fR [\fB\-IQVcqrsw\fR] [\fB\-\fR] [\fB\-e\fR \fIch\fR] [\fB\-i\fR \fIch\fR] [\fB\-k\fR \fIch\fR] [\fB\-m\fR \fImapping\fR] [\fIterminal\fR] +\fB@TSET@\fR [\fB\-IQVcqrsw\fR] [\fB\-\fR] [\fB\-e\fR \fIch\fR] [\fB\-i\fR \fIch\fR] [\fB\-k\fR \fIch\fR] [\fB\-m\fR \fImapping\fR] [\fIterminal\fR] .br \fBreset\fR [\fB\-IQVcqrsw\fR] [\fB\-\fR] [\fB\-e\fR \fIch\fR] [\fB\-i\fR \fIch\fR] [\fB\-k\fR \fIch\fR] [\fB\-m\fR \fImapping\fR] [\fIterminal\fR] .SH DESCRIPTION @@ -49,13 +53,13 @@ error output device in the \fI/etc/ttys\fR file. \fIgetty\fR does this job by setting \fBTERM\fR according to the type passed to it by \fI/etc/inittab\fR.) .PP -4. The default terminal type, ``unknown''. +4. The default terminal type, \*(``unknown\*(''. .PP If the terminal type was not specified on the command-line, the \fB\-m\fR option mappings are then applied (see the section .B TERMINAL TYPE MAPPING for more information). -Then, if the terminal type begins with a question mark (``?''), the +Then, if the terminal type begins with a question mark (\*(``?\*(''), the user is prompted for confirmation of the terminal type. An empty response confirms the type, or, another type can be entered to specify a new type. Once the terminal type has been determined, the terminfo @@ -72,7 +76,7 @@ Use the \fB\-c\fP or \fB\-w\fP option to select only the window sizing versus the other initialization. If neither option is given, both are assumed. .PP -When invoked as \fBreset\fR, \fBtset\fR sets cooked and echo modes, +When invoked as \fBreset\fR, \fB@TSET@\fR sets cooked and echo modes, turns off cbreak and raw modes, turns on newline translation and resets any unset special characters to their default values before doing the terminal initialization described above. This is useful @@ -89,6 +93,7 @@ The options are as follows: .TP 5 .B \-c Set control characters and modes. +.TP 5 .B \-e Set the erase character to \fIch\fR. .TP @@ -109,7 +114,7 @@ for more information. .TP .B \-Q Do not display any values for the erase, interrupt and line kill characters. -Normally \fBtset\fR displays the values for control characters which +Normally \fB@TSET@\fR displays the values for control characters which differ from the system's default values. .TP .B \-q @@ -137,7 +142,7 @@ unless \fBsetupterm\fP is not able to detect the window size. .PP The arguments for the \fB\-e\fR, \fB\-i\fR, and \fB\-k\fR options may either be entered as actual characters or by using the `hat' -notation, i.e., control-h may be specified as ``^H'' or ``^h''. +notation, i.e., control-h may be specified as \*(``^H\*('' or \*(``^h\*(''. . .SH SETTING THE ENVIRONMENT It is often desirable to enter the terminal type and information about @@ -146,35 +151,41 @@ This is done using the \fB\-s\fR option. .PP When the \fB\-s\fR option is specified, the commands to enter the information into the shell's environment are written to the standard output. If -the \fBSHELL\fR environmental variable ends in ``csh'', the commands +the \fBSHELL\fR environmental variable ends in \*(``csh\*('', the commands are for \fBcsh\fR, otherwise, they are for \fBsh\fR. Note, the \fBcsh\fR commands set and unset the shell variable \fBnoglob\fR, leaving it unset. The following line in the \fB.login\fR or \fB.profile\fR files will initialize the environment correctly: .sp - eval \`tset \-s options ... \` + eval \`@TSET@ \-s options ... \` . .SH TERMINAL TYPE MAPPING When the terminal is not hardwired into the system (or the current system information is incorrect) the terminal type derived from the \fI/etc/ttys\fR file or the \fBTERM\fR environmental variable is often something generic like \fBnetwork\fR, \fBdialup\fR, or \fBunknown\fR. -When \fBtset\fR is used in a startup script it is often desirable to +When \fB@TSET@\fR is used in a startup script it is often desirable to provide information about the type of terminal used on such ports. .PP The purpose of the \fB\-m\fR option is to map from some set of conditions to a terminal type, that is, to -tell \fBtset\fR -``If I'm on this port at a particular speed, guess that I'm on that -kind of terminal''. +tell \fB@TSET@\fR +\*(``If I'm on this port at a particular speed, +guess that I'm on that kind of terminal\*(''. .PP The argument to the \fB\-m\fR option consists of an optional port type, an optional operator, an optional baud rate specification, an optional -colon (``:'') character and a terminal type. The port type is a -string (delimited by either the operator or the colon character). The -operator may be any combination of ``>'', ``<'', ``@'', and ``!''; ``>'' -means greater than, ``<'' means less than, ``@'' means equal to -and ``!'' inverts the sense of the test. +colon (\*(``:\*('') character and a terminal type. The port type is a +string (delimited by either the operator or the colon character). +The operator may be any combination of +\*(``>\*('', +\*(``<\*('', +\*(``@\*('', +and \*(``!\*(''; +\*(``>\*('' means greater than, +\*(``<\*('' means less than, +\*(``@\*('' means equal to and +\*(``!\*('' inverts the sense of the test. The baud rate is specified as a number and is compared with the speed of the standard error output (which should be the control terminal). The terminal type is a string. @@ -204,53 +215,57 @@ terminal. No whitespace characters are permitted in the \fB\-m\fR option argument. Also, to avoid problems with meta-characters, it is suggested that the entire \fB\-m\fR option argument be placed within single quote characters, -and that \fBcsh\fR users insert a backslash character (``\e'') before -any exclamation marks (``!''). +and that \fBcsh\fR users insert a backslash character (\*(``\e\*('') before +any exclamation marks (\*(``!\*(''). .SH HISTORY -The \fBtset\fR command appeared in BSD 3.0. The \fBncurses\fR implementation +The \fB@TSET@\fR command appeared in BSD 3.0. The \fBncurses\fR implementation was lightly adapted from the 4.4BSD sources for a terminfo environment by Eric S. Raymond . .SH COMPATIBILITY -The \fBtset\fR utility has been provided for backward-compatibility with BSD +The \fB@TSET@\fR utility has been provided for backward-compatibility with BSD environments (under most modern UNIXes, \fB/etc/inittab\fR and \fIgetty\fR(1) can set \fBTERM\fR appropriately for each dial-up line; this obviates what was -\fBtset\fR's most important use). This implementation behaves like 4.4BSD +\fB@TSET@\fR's most important use). This implementation behaves like 4.4BSD tset, with a few exceptions specified here. .PP -The \fB\-S\fR option of BSD tset no longer works; it prints an error message to stderr -and dies. The \fB\-s\fR option only sets \fBTERM\fR, not \fBTERMCAP\fP. Both these -changes are because the \fBTERMCAP\fR variable is no longer supported under -terminfo-based \fBncurses\fR, which makes \fBtset \-S\fR useless (we made it die -noisily rather than silently induce lossage). +The \fB\-S\fR option of BSD tset no longer works; +it prints an error message to stderr and dies. +The \fB\-s\fR option only sets \fBTERM\fR, not \fBTERMCAP\fP. +Both of these changes are because the \fBTERMCAP\fR variable +is no longer supported under terminfo-based \fBncurses\fR, +which makes \fB@TSET@ \-S\fR useless +(we made it die noisily rather than silently induce lossage). .PP There was an undocumented 4.4BSD feature that invoking tset via a link named `TSET` (or via any other name beginning with an upper-case letter) set the terminal to use upper-case only. This feature has been omitted. .PP The \fB\-A\fR, \fB\-E\fR, \fB\-h\fR, \fB\-u\fR and \fB\-v\fR -options were deleted from the \fBtset\fR +options were deleted from the \fB@TSET@\fR utility in 4.4BSD. None of them were documented in 4.3BSD and all are of limited utility at best. The \fB\-a\fR, \fB\-d\fR, and \fB\-p\fR options are similarly not documented or useful, but were retained as they appear to be in widespread use. It is strongly recommended that any usage of these -three options be changed to use the \fB\-m\fR option instead. The -\fB\-n\fP option remains, but has no effect. The \fB\-adnp\fR options are therefore -omitted from the usage summary above. +three options be changed to use the \fB\-m\fR option instead. +The \fB\-n\fP option remains, but has no effect. +The \fB\-adnp\fR options are therefore omitted from the usage summary above. .PP -It is still permissible to specify the \fB\-e\fR, \fB\-i\fR, and \fB\-k\fR options without -arguments, although it is strongly recommended that such usage be fixed to +It is still permissible to specify the \fB\-e\fR, \fB\-i\fR, +and \fB\-k\fR options without arguments, +although it is strongly recommended that such usage be fixed to explicitly specify the character. .PP -As of 4.4BSD, executing \fBtset\fR as \fBreset\fR no longer implies the \fB\-Q\fR -option. Also, the interaction between the \- option and the \fIterminal\fR -argument in some historic implementations of \fBtset\fR has been removed. +As of 4.4BSD, +executing \fB@TSET@\fR as \fBreset\fR no longer implies the \fB\-Q\fR option. +Also, the interaction between the \- option and the \fIterminal\fR +argument in some historic implementations of \fB@TSET@\fR has been removed. .SH ENVIRONMENT -The \fBtset\fR command uses these environment variables: +The \fB@TSET@\fR command uses these environment variables: .TP 5 SHELL -tells \fBtset\fP whether to initialize \fBTERM\fP using \fBsh\fP or +tells \fB@TSET@\fP whether to initialize \fBTERM\fP using \fBsh\fP or \fBcsh\fP syntax. .TP 5 TERM @@ -260,7 +275,7 @@ Each terminal type is distinct, though many are similar. TERMCAP may denote the location of a termcap database. If it is not an absolute pathname, e.g., begins with a `/', -\fBtset\fP removes the variable from the environment before looking +\fB@TSET@\fP removes the variable from the environment before looking for the terminal description. .SH FILES .TP 5 @@ -270,6 +285,7 @@ system port name to terminal type mapping database (BSD versions only). @TERMINFO@ terminal capability database .SH SEE ALSO +.hy 0 csh(1), sh(1), stty(1), @@ -278,6 +294,7 @@ tty(4), terminfo(5), ttys(5), environ(7) +.hy .PP This describes \fBncurses\fR version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@). -- cgit v1.2.3