X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Ftput.1;h=7e20fbed5b2046759171e50c829f648788ae8509;hp=10e47b7b32161fd469994ff62fa590b542a9d23e;hb=5925150381bb42a4d8c7116d62c348a7b84309f3;hpb=cccf831ed7c83410c7f6cec2a43e71e9c4278b4c diff --git a/man/tput.1 b/man/tput.1 index 10e47b7b..7e20fbed 100644 --- a/man/tput.1 +++ b/man/tput.1 @@ -1,6 +1,7 @@ '\" t .\"*************************************************************************** -.\" Copyright (c) 1998-2017,2018 Free Software Foundation, Inc. * +.\" Copyright 2018,2020 Thomas E. Dickey * +.\" Copyright 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 * @@ -27,7 +28,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: tput.1,v 1.58 2018/05/19 21:07:46 tom Exp $ +.\" $Id: tput.1,v 1.64 2020/04/25 21:52:49 tom Exp $ .TH @TPUT@ 1 "" .ds d @TERMINFO@ .ds n 1 @@ -226,7 +227,8 @@ Otherwise, \fBreset\fR acts identically to \fBinit\fR. \fBlongname\fR If the terminal database is present and an entry for the user's terminal exists (see \fB\-T\fR\fItype\fR above), then the long name -of the terminal will be put out. The long name is the last +of the terminal will be put out. +The long name is the last name in the first line of the terminal's description in the \fBterminfo\fR database [see \fBterm\fR(5)]. .SS Aliases @@ -252,13 +254,14 @@ The \fBreset\fP program is usually an alias for \fB@TSET@\fP, because of this difference with resetting terminal modes and special characters. .PP With the changes made for ncurses 6.1, the \fIreset\fP feature of the -two programs is (mostly) the same. A few differences remain: +two programs is (mostly) the same. +A few differences remain: .bP The \fB@TSET@\fP program waits one second when resetting, in case it happens to be a hardware terminal. .bP The two programs write the terminal initialization strings -to different streams (i.e.,. the standard error for \fB@TSET@\fP and the +to different streams (i.e., the standard error for \fB@TSET@\fP and the standard output for \fB@TPUT@\fP). .IP \fBNote:\fP although these programs write to different streams, @@ -269,6 +272,27 @@ If \fB@TPUT@\fR is invoked by a link named \fBinit\fR, this has the same effect as \fB@TPUT@ init\fR. Again, you are less likely to use that link because another program named \fBinit\fP has a more well-established use. +.SS Terminal Size +.PP +Besides the special commands (e.g., \fBclear\fP), +@TPUT@ treats certain terminfo capabilities specially: +\fBlines\fP and \fBcols\fP. +@TPUT@ calls \fBsetupterm\fP(3X) to obtain the terminal size: +.bP +first, it gets the size from the terminal database +(which generally is not provided for terminal emulators +which do not have a fixed window size) +.bP +then it asks the operating system for the terminal's size +(which generally works, unless connecting via a serial line which +does not support \fINAWS\fP: negotiations about window size). +.bP +finally, it inspects the environment variables \fBLINES\fP and \fBCOLUMNS\fP +which may override the terminal size. +.PP +If the \fB\-T\fP option is given +@TPUT@ ignores the environment variables by calling \fBuse_tioctl(TRUE)\fP, +relying upon the operating system (or finally, the terminal database). .SH EXAMPLES .TP 5 \fB@TPUT@ init\fR @@ -299,7 +323,8 @@ Print the number of columns for the 450 terminal. \fBbold=`@TPUT@ smso` offbold=`@TPUT@ rmso`\fR Set the shell variables \fBbold\fR, to begin stand-out mode sequence, and \fBoffbold\fR, to end standout mode sequence, -for the current terminal. This might be followed by a +for the current terminal. +This might be followed by a prompt: \fBecho "${bold}Please type in your name: ${offbold}\\c"\fR .TP 5 \fB@TPUT@ hc\fR @@ -354,7 +379,8 @@ and if any errors are found, will set the exit code to 4 plus the number of lines with errors. If no errors are found, the exit code is \fB0\fR. No indication of which line failed can be given so -exit code \fB1\fR will never appear. Exit codes \fB2\fR, \fB3\fR, and +exit code \fB1\fR will never appear. +Exit codes \fB2\fR, \fB3\fR, and \fB4\fR retain their usual interpretation. If the \fB\-S\fR option is not used, the exit code depends on the type of \fIcapname\fR: @@ -437,7 +463,7 @@ AT&T or BSD: Ross Ridge's \fImytinfo\fP package, published on \fIcomp.sources.unix\fP in December 1992. Ridge's program made more sophisticated use of the terminal capabilities than the BSD program. -Eric Raymond used the \fBtput\fP program +Eric Raymond used that \fBtput\fP program (and other parts of \fImytinfo\fP) in ncurses in June 1995. Using the portions dealing with terminal capabilities almost without change, @@ -538,6 +564,27 @@ While it is certainly possible to write a \fBtput\fP program without using curses, none of the systems which have a curses implementation provide a \fBtput\fP utility which does not provide the \fIcapname\fP feature. +.PP +X/Open Curses Issue 7 (2009) is the first version to document utilities. +However that part of X/Open Curses does not follow existing practice +(i.e., Unix features documented in SVID 3): +.bP +It assigns exit code 4 to \*(``invalid operand\*('', +which may be the same as \fIunknown capability\fP. +For instance, the source code for Solaris' xcurses uses the term +\*(``invalid\*('' in this case. +.bP +It assigns exit code 255 to a numeric variable that is not specified in +the terminfo database. +That likely is a documentation error, +confusing the \fB\-1\fP written to the standard output for an absent +or cancelled numeric value versus an (unsigned) exit code. +.PP +The various Unix systems (AIX, HPUX, Solaris) use the same exit-codes +as ncurses. +.PP +NetBSD curses documents different exit codes which do not correspond +to either ncurses or X/Open. .SH SEE ALSO \fB@CLEAR@\fR(\*n), \fBstty\fR(1),