X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_util.3x;h=31411319d61b60e63b1da61a350a3634d8258951;hp=3d33e1994e5586c1006787cf46b400af0e32d4cc;hb=a3754ea95eea6118bd49f0507f35a7ef15b41a6c;hpb=5e36f11feab6f790e0cc6f2c882a67b7b65e3b6b

diff --git a/man/curs_util.3x b/man/curs_util.3x
index 3d33e199..31411319 100644
--- a/man/curs_util.3x
+++ b/man/curs_util.3x
@@ -1,5 +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            *
@@ -26,7 +27,7 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_util.3x,v 1.33 2011/12/17 23:31:30 tom Exp $
+.\" $Id: curs_util.3x,v 1.36 2012/07/21 18:51:10 tom Exp $
 .TH curs_util 3X ""
 .de bP
 .IP \(bu 4
@@ -44,6 +45,7 @@
 \fBputwin\fR,
 \fBunctrl\fR,
 \fBuse_env\fR,
+\fBuse_tioctl\fR,
 \fBwunctrl\fR \- miscellaneous \fBcurses\fR utility routines
 .ad
 .hy
@@ -64,6 +66,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
@@ -123,16 +127,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
@@ -233,8 +291,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