]> ncurses.scripts.mit.edu Git - ncurses.git/blobdiff - doc/html/man/tput.1.html
projects / ncurses.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
ncurses 6.0 - patch 20170204
[ncurses.git] / doc / html / man / tput.1.html
diff --git a/doc/html/man/tput.1.html b/doc/html/man/tput.1.html
index f754de3cc43cc516e812114a65d710c07eb624fe..a6888a1f0c657dacc861bf5c63c570611235c886 100644 (file)
--- a/doc/html/man/tput.1.html
+++ b/doc/html/man/tput.1.html
@@ -1,7 +1,7 @@
 <!-- 
   * t
   ****************************************************************************
 <!-- 
   * t
   ****************************************************************************
-  * Copyright (c) 1998-2012,2016 Free Software Foundation, Inc.              *
+  * Copyright (c) 1998-2016,2017 Free Software Foundation, Inc.              *
   *                                                                          *
   * Permission is hereby granted, free of charge, to any person obtaining a  *
   * copy of this software and associated documentation files (the            *
   *                                                                          *
   * Permission is hereby granted, free of charge, to any person obtaining a  *
   * copy of this software and associated documentation files (the            *
@@ -27,7 +27,7 @@
   * sale, use or other dealings in this Software without prior written       *
   * authorization.                                                           *
   ****************************************************************************
   * sale, use or other dealings in this Software without prior written       *
   * authorization.                                                           *
   ****************************************************************************
-  * @Id: tput.1,v 1.44 2016/08/20 23:40:31 tom Exp @
+  * @Id: tput.1,v 1.54 2017/01/29 00:51:08 tom Exp @
 -->
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
 <HTML>
 -->
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
 <HTML>
@@ -107,61 +107,109 @@
 
               Again, <STRONG>tput</STRONG> uses a table and the presence of param-
               eters  in  its  input  to  decide  whether  to  use
 
               Again, <STRONG>tput</STRONG> uses a table and the presence of param-
               eters  in  its  input  to  decide  whether  to  use
-              <STRONG><A HREF="tparm.3x.html">tparm(3x)</A></STRONG>, and how to interpret the parameters.
+              <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG>, and how to interpret the parameters.
 
        <STRONG>-V</STRONG>     reports the version of ncurses which  was  used  in
               this program, and exits.
 
 
 </PRE><H3><a name="h3-Commands">Commands</a></H3><PRE>
 
        <STRONG>-V</STRONG>     reports the version of ncurses which  was  used  in
               this program, and exits.
 
 
 </PRE><H3><a name="h3-Commands">Commands</a></H3><PRE>
+       A  few  commands  (<STRONG>init</STRONG>,  <STRONG>reset</STRONG> and <STRONG>longname</STRONG>) are special;
+       they are defined by the <STRONG>tput</STRONG> program.  The others are  the
+       names of <EM>capabilities</EM> from the terminal database (see <STRONG>ter-</STRONG>
+       <STRONG><A HREF="terminfo.5.html">minfo(5)</A></STRONG> for a list).  Although <STRONG>init</STRONG>  and  <STRONG>reset</STRONG>  resemble
+       capability  names,  <STRONG>tput</STRONG> uses several capabilities to per-
+       form these special functions.
+
        <EM>capname</EM>
        <EM>capname</EM>
-              indicates  the  capability  from the <STRONG>terminfo</STRONG> data-
-              base.  When <STRONG>termcap</STRONG> support  is  compiled  in,  the
-              <STRONG>termcap</STRONG> name for the capability is also accepted.
+              indicates the capability from  the  terminal  data-
+              base.
 
               If  the  capability  is a string that takes parame-
               ters, the arguments following the  capability  will
               be used as parameters for the string.
 
 
               If  the  capability  is a string that takes parame-
               ters, the arguments following the  capability  will
               be used as parameters for the string.
 
-              Most  parameters  are numbers.  Only a few terminfo
+              Most  parameters  are numbers.  Only a few terminal
               capabilities require string parameters; <STRONG>tput</STRONG> uses a
               table to decide which to pass as strings.  Normally
               capabilities require string parameters; <STRONG>tput</STRONG> uses a
               table to decide which to pass as strings.  Normally
-              <STRONG>tput</STRONG> uses <STRONG><A HREF="tparm.3x.html">tparm(3x)</A></STRONG> to  perform  the  substitution.
+              <STRONG>tput</STRONG> uses <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG> to  perform  the  substitution.
               If no parameters are given for the capability, <STRONG>tput</STRONG>
               writes the string without performing the  substitu-
               tion.
 
               If no parameters are given for the capability, <STRONG>tput</STRONG>
               writes the string without performing the  substitu-
               tion.
 
-       <STRONG>init</STRONG>   If  the  <STRONG>terminfo</STRONG>  database is present and an entry
+       <STRONG>init</STRONG>   If  the  terminal  database is present and an entry
               for the user's terminal exists (see <STRONG>-T</STRONG><EM>type</EM>, above),
               the following will occur:
 
               for the user's terminal exists (see <STRONG>-T</STRONG><EM>type</EM>, above),
               the following will occur:
 
-              (1)  if   present,  the  terminal's  initialization
-                   strings will be output as detailed in the <STRONG>ter-</STRONG>
-                   <STRONG><A HREF="terminfo.5.html">minfo(5)</A></STRONG> section on <EM>Tabs</EM> <EM>and</EM> <EM>Initialization</EM>,
+              (1)  first,  <STRONG>tput</STRONG>  retrieves  the  current terminal
+                   mode settings for your terminal.  It does this
+                   by successively testing
+
+                   <STRONG>o</STRONG>   the standard error,
+
+                   <STRONG>o</STRONG>   standard output,
+
+                   <STRONG>o</STRONG>   standard input and
+
+                   <STRONG>o</STRONG>   ultimately "/dev/tty"
+
+                   to obtain terminal settings.  Having retrieved
+                   these  settings,  <STRONG>tput</STRONG>  remembers  which  file
+                   descriptor to use when updating settings.
 
 
-              (2)  any  delays  (e.g.,  newline) specified in the
-                   entry will be set in the tty driver,
+              (2)  if the window size cannot be obtained from the
+                   operating system, but the terminal description
+                   (or environment, e.g., <STRONG>LINES</STRONG> and <STRONG>COLUMNS</STRONG> vari-
+                   ables specify this), update the operating sys-
+                   tem's notion of the window size.
 
 
-              (3)  tabs  expansion  will  be  turned  on  or  off
-                   according  to  the specification in the entry,
-                   and
+              (3)  the terminal modes will be updated:
 
 
-              (4)  if tabs are not expanded, standard  tabs  will
-                   be set (every 8 spaces).
+                   <STRONG>o</STRONG>   any  delays  (e.g.,  newline) specified in
+                       the entry will be set in the tty driver,
+
+                   <STRONG>o</STRONG>   tabs expansion will be turned  on  or  off
+                       according  to  the  specification  in  the
+                       entry, and
+
+                   <STRONG>o</STRONG>   if tabs are not  expanded,  standard  tabs
+                       will be set (every 8 spaces).
+
+              (4)  if   present,  the  terminal's  initialization
+                   strings will be output as detailed in the <STRONG>ter-</STRONG>
+                   <STRONG><A HREF="terminfo.5.html">minfo(5)</A></STRONG> section on <EM>Tabs</EM> <EM>and</EM> <EM>Initialization</EM>,
+
+              (5)  output is flushed.
 
               If an entry does not contain the information needed
               for any of these  activities,  that  activity  will
               silently be skipped.
 
 
               If an entry does not contain the information needed
               for any of these  activities,  that  activity  will
               silently be skipped.
 
-       <STRONG>reset</STRONG>  Instead  of putting out initialization strings, the
-              terminal's reset strings will be output if  present
-              (<STRONG>rs1</STRONG>,  <STRONG>rs2</STRONG>, <STRONG>rs3</STRONG>, <STRONG>rf</STRONG>).  If the reset strings are not
-              present, but initialization strings are,  the  ini-
-              tialization  strings  will  be  output.  Otherwise,
-              <STRONG>reset</STRONG> acts identically to <STRONG>init</STRONG>.
+       <STRONG>reset</STRONG>  This is similar to <STRONG>init</STRONG>, with two differences:
+
+              (1)  before  any other initialization, the terminal
+                   modes will be reset to a "sane" state:
+
+                   <STRONG>o</STRONG>   set cooked and echo modes,
+
+                   <STRONG>o</STRONG>   turn off cbreak and raw modes,
+
+                   <STRONG>o</STRONG>   turn on newline translation and
+
+                   <STRONG>o</STRONG>   reset  any  unset  special  characters  to
+                       their default values
+
+              (2)  Instead of putting out <EM>initialization</EM> strings,
+                   the terminal's <EM>reset</EM> strings will be output if
+                   present  (<STRONG>rs1</STRONG>,  <STRONG>rs2</STRONG>,  <STRONG>rs3</STRONG>,  <STRONG>rf</STRONG>).  If the <EM>reset</EM>
+                   strings are not  present,  but  <EM>initialization</EM>
+                   strings  are,  the <EM>initialization</EM> strings will
+                   be output.
+
+              Otherwise, <STRONG>reset</STRONG> acts identically to <STRONG>init</STRONG>.
 
        <STRONG>longname</STRONG>
 
        <STRONG>longname</STRONG>
-              If the <STRONG>terminfo</STRONG> database is present  and  an  entry
+              If the terminal database is present  and  an  entry
               for  the user's terminal exists (see <STRONG>-T</STRONG><EM>type</EM> above),
               then the long name of the terminal will be put out.
               The long name is the last name in the first line of
               for  the user's terminal exists (see <STRONG>-T</STRONG><EM>type</EM> above),
               then the long name of the terminal will be put out.
               The long name is the last name in the first line of
@@ -170,26 +218,46 @@
 
 
 </PRE><H3><a name="h3-Aliases">Aliases</a></H3><PRE>
 
 
 </PRE><H3><a name="h3-Aliases">Aliases</a></H3><PRE>
-       <STRONG>tput</STRONG>  handles  the  <STRONG>init</STRONG>  and <STRONG>reset</STRONG> commands specially: it
-       allows for the possibility that it is invoked  by  a  link
+       <STRONG>tput</STRONG> handles the <STRONG>clear</STRONG>, <STRONG>init</STRONG> and <STRONG>reset</STRONG> commands specially:
+       it allows for the possibility that it is invoked by a link
        with those names.
 
        If  <STRONG>tput</STRONG>  is  invoked  by a link named <STRONG>reset</STRONG>, this has the
        same effect as  <STRONG>tput</STRONG>  <STRONG>reset</STRONG>.   The  <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG>  utility  also
        with those names.
 
        If  <STRONG>tput</STRONG>  is  invoked  by a link named <STRONG>reset</STRONG>, this has the
        same effect as  <STRONG>tput</STRONG>  <STRONG>reset</STRONG>.   The  <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG>  utility  also
-       treats a link named <STRONG>reset</STRONG> specially:
+       treats a link named <STRONG>reset</STRONG> specially.
 
 
-       <STRONG>o</STRONG>   That  utility  resets  the  terminal modes and special
-           characters (not done here).
+       Before  ncurses 6.1, the two utilities were different from
+       each other:
 
 
-       <STRONG>o</STRONG>   On the other hand, tset's repertoire of terminal capa-
-           bilities  for  resetting the terminal is more limited,
+       <STRONG>o</STRONG>   <STRONG>tset</STRONG> utility reset  the  terminal  modes  and  special
+           characters (not done with <STRONG>tput</STRONG>).
+
+       <STRONG>o</STRONG>   On the other hand, <STRONG>tset</STRONG>'s repertoire of terminal capa-
+           bilities for resetting the terminal was more  limited,
            i.e., only <STRONG>reset_1string</STRONG>, <STRONG>reset_2string</STRONG> and <STRONG>reset_file</STRONG>
            in contrast to the tab-stops and margins which are set
            by this utility.
 
            i.e., only <STRONG>reset_1string</STRONG>, <STRONG>reset_2string</STRONG> and <STRONG>reset_file</STRONG>
            in contrast to the tab-stops and margins which are set
            by this utility.
 
-       <STRONG>o</STRONG>   The <STRONG>reset</STRONG> program is usually an alias for tset, due to
-           the  resetting  of  terminal modes and special charac-
-           ters.
+       <STRONG>o</STRONG>   The  <STRONG>reset</STRONG>  program  is  usually  an  alias  for <STRONG>tset</STRONG>,
+           because of this  difference  with  resetting  terminal
+           modes and special characters.
+
+       With  the  changes made for ncurses 6.1, the <EM>reset</EM> feature
+       of the two programs is (mostly) the same.  A  few  differ-
+       ences remain:
+
+       <STRONG>o</STRONG>   The  <STRONG>tset</STRONG>  program waits one second when resetting, in
+           case it happens to be a hardware terminal.
+
+       <STRONG>o</STRONG>   The two programs  write  the  terminal  initialization
+           strings  to  different  streams  (i.e.,.  the standard
+           error for <STRONG>tset</STRONG> and the standard output for <STRONG>tput</STRONG>).
+
+           <STRONG>Note:</STRONG>  although  these  programs  write  to  different
+           streams,  redirecting their output to a file will cap-
+           ture only part of their actions.  The changes  to  the
+           terminal  modes  are  not  affected by redirecting the
+           output.
 
        If <STRONG>tput</STRONG> is invoked by a link named <STRONG>init</STRONG>, this has the same
        effect  as  <STRONG>tput</STRONG>  <STRONG>init</STRONG>.  Again, you are less likely to use
 
        If <STRONG>tput</STRONG> is invoked by a link named <STRONG>init</STRONG>, this has the same
        effect  as  <STRONG>tput</STRONG>  <STRONG>init</STRONG>.  Again, you are less likely to use
@@ -332,9 +400,7 @@
        AT&amp;T  System  V  provided  a different <STRONG>tput</STRONG> command, whose
        <STRONG>init</STRONG> and <STRONG>reset</STRONG>  subcommands (more than half  the  program)
        were incorporated from the <STRONG>reset</STRONG> feature of BSD <STRONG>tset</STRONG> writ-
        AT&amp;T  System  V  provided  a different <STRONG>tput</STRONG> command, whose
        <STRONG>init</STRONG> and <STRONG>reset</STRONG>  subcommands (more than half  the  program)
        were incorporated from the <STRONG>reset</STRONG> feature of BSD <STRONG>tset</STRONG> writ-
-       ten by Eric Allman.  Later the corresponding  source  code
-       for  <EM>reset</EM>  was  removed  from the BSD <STRONG>tset</STRONG> (in June 1993,
-       released in 4.4BSD-Lite a year later).
+       ten by Eric Allman.
 
        Keith Bostic replaced the BSD <STRONG>tput</STRONG> command in 1989 with  a
        new  implementation  based  on  the  AT&amp;T System V program
 
        Keith Bostic replaced the BSD <STRONG>tput</STRONG> command in 1989 with  a
        new  implementation  based  on  the  AT&amp;T System V program
@@ -351,12 +417,22 @@
        Both of these appeared in 4.4BSD,  becoming  the  "modern"
        BSD implementation of <STRONG>tput</STRONG>.
 
        Both of these appeared in 4.4BSD,  becoming  the  "modern"
        BSD implementation of <STRONG>tput</STRONG>.
 
+       This  implementation of <STRONG>tput</STRONG> began from a different source
+       than AT&amp;T or BSD: Ross Ridge's <EM>mytinfo</EM> package,  published
+       on  <EM>comp.sources.unix</EM>  in  December 1992.  Ridge's program
+       made more sophisticated use of the  terminal  capabilities
+       than  the BSD program.  Eric Raymond used the <STRONG>tput</STRONG> program
+       (and other parts of <EM>mytinfo</EM>)  in  ncurses  in  June  1995.
+       Using  the  portions  dealing  with  terminal capabilities
+       almost without change, Raymond made  improvements  to  the
+       way the command-line parameters were handled.
+
 
 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
        This  implementation of <STRONG>tput</STRONG> differs from AT&amp;T <STRONG>tput</STRONG> in two
        important areas:
 
 
 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
        This  implementation of <STRONG>tput</STRONG> differs from AT&amp;T <STRONG>tput</STRONG> in two
        important areas:
 
-       <STRONG>o</STRONG>   tput <EM>capname</EM> writes to the standard output.  That need
+       <STRONG>o</STRONG>   <STRONG>tput</STRONG> <EM>capname</EM> writes to the standard output.  That need
            not  be  a regular terminal.  However, the subcommands
            which manipulate terminal modes may not use the  stan-
            dard output.
            not  be  a regular terminal.  However, the subcommands
            which manipulate terminal modes may not use the  stan-
            dard output.
@@ -368,11 +444,11 @@
            "/dev/tty" and finally just assumes a 1200Bd terminal.
            When updating terminal modes, it ignores errors.
 
            "/dev/tty" and finally just assumes a 1200Bd terminal.
            When updating terminal modes, it ignores errors.
 
-           Until changes made after ncurses  6.0,  tput  did  not
-           modify  terminal  modes.   tput  now  uses  a  similar
-           scheme, using functions shared with  tset  (and  ulti-
+           Until changes made after ncurses  6.0,  <STRONG>tput</STRONG>  did  not
+           modify  terminal  modes.   <STRONG>tput</STRONG>  now  uses  a  similar
+           scheme, using functions shared with  <STRONG>tset</STRONG>  (and  ulti-
            mately  based  on the 4.4BSD <STRONG>tset</STRONG>).  If it is not able
            mately  based  on the 4.4BSD <STRONG>tset</STRONG>).  If it is not able
-           to open a terminal, e.g., when running in  <STRONG>cron</STRONG>,  tput
+           to open a terminal, e.g., when running in  <STRONG>cron</STRONG>,  <STRONG>tput</STRONG>
            will return an error.
 
        <STRONG>o</STRONG>   AT&amp;T  <STRONG>tput</STRONG> guesses the type of its <EM>capname</EM> operands by
            will return an error.
 
        <STRONG>o</STRONG>   AT&amp;T  <STRONG>tput</STRONG> guesses the type of its <EM>capname</EM> operands by
@@ -389,6 +465,22 @@
            an internal library function  to  analyze  nonstandard
            <EM>capname</EM> operands.
 
            an internal library function  to  analyze  nonstandard
            <EM>capname</EM> operands.
 
+       This  implementation (unlike others) can accept both <EM>term-</EM>
+       <EM>cap</EM> and <EM>terminfo</EM> names for the <EM>capname</EM> feature, if <EM>termcap</EM>
+       support  is  compiled in.  However, the predefined <EM>termcap</EM>
+       and <EM>terminfo</EM> names have two ambiguities in this case  (and
+       the <EM>terminfo</EM> name is assumed):
+
+       <STRONG>o</STRONG>   The  <EM>termcap</EM>  name <STRONG>dl</STRONG> corresponds to the <EM>terminfo</EM> name
+           <STRONG>dl1</STRONG> (delete one line).
+           The <EM>terminfo</EM> name <STRONG>dl</STRONG> corresponds to the  <EM>termcap</EM>  name
+           <STRONG>DL</STRONG> (delete a given number of lines).
+
+       <STRONG>o</STRONG>   The  <EM>termcap</EM>  name <STRONG>ed</STRONG> corresponds to the <EM>terminfo</EM> name
+           <STRONG>rmdc</STRONG> (end delete mode).
+           The <EM>terminfo</EM> name <STRONG>ed</STRONG> corresponds to the  <EM>termcap</EM>  name
+           <STRONG>cd</STRONG> (clear to end of screen).
+
        The  <STRONG>longname</STRONG>  and <STRONG>-S</STRONG> options, and the parameter-substitu-
        tion features used in the <STRONG>cup</STRONG> example, were not  supported
        in  BSD curses before 4.3reno (1989) or in AT&amp;T/USL curses
        The  <STRONG>longname</STRONG>  and <STRONG>-S</STRONG> options, and the parameter-substitu-
        tion features used in the <STRONG>cup</STRONG> example, were not  supported
        in  BSD curses before 4.3reno (1989) or in AT&amp;T/USL curses
@@ -438,7 +530,7 @@
        <STRONG><A HREF="clear.1.html">clear(1)</A></STRONG>,    <STRONG>stty(1)</STRONG>,   <STRONG><A HREF="tabs.1.html">tabs(1)</A></STRONG>,   <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG>,   <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>,
        <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>.
 
        <STRONG><A HREF="clear.1.html">clear(1)</A></STRONG>,    <STRONG>stty(1)</STRONG>,   <STRONG><A HREF="tabs.1.html">tabs(1)</A></STRONG>,   <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG>,   <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>,
        <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>.
 
-       This describes <STRONG>ncurses</STRONG> version 6.0 (patch 20160820).
+       This describes <STRONG>ncurses</STRONG> version 6.0 (patch 20170204).
 
 
 
 
 
 
ncurses, with patches starting at ncurses-5.6; new users should use https://github.com/ThomasDickey/ncurses-snapshots/