Linux Cubed Series 3: Developer Tools

home *** CD-ROM | disk | FTP | other *** search

/ Linux Cubed Series 3: Developer Tools / Linux Cubed Series 3 - Developer Tools.iso / utils / terminal / tput10a.taz / tput10a / usr / emacs / info / tput.info

Wrap

Text File | 1992-12-23 | 23.0 KB | 608 lines

Info file: tput.info, -*-Text-*- produced by texinfo-format-buffer from file: tput.texinfo This file documents the the GNU `tput' command for translating terminal capability names into escape and control codes for a particular terminal. Copyright (C) 1989-1991 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation. File: tput.info, Node: Top, Next: , Prev: (dir), Up: (dir) `tput': Portable Terminal Control for Shell Scripts *************************************************** The `tput' command translates the terminal-independent name of a terminal capability into its actual value for the terminal type being used. This allows shell scripts to do things like clear the screen, underline text, and center text no matter how wide the screen is. `tput' takes as an argument the name of a Unix System V terminfo capability, which it translates into the equivalent termcap capability name (*Note Capabilities::, for a list of the equivalencies). There are three types of terminfo (and termcap) capabilities: string, Boolean, and numeric. String capabilities either cause a special effect on the terminal when they are displayed or are the value sent by a special key on the terminal (the latter type are probably of no use in shell scripts). Numeric and Boolean capabilities give information about the terminal such as how many columns wide it is or whether whether it has a meta key. *Note Output::, for more detailed information on the three types of capabilities. The format of the `tput' command is illustrated below, with the optional portions in square brackets, `[...]': tput [-T TERMINAL-TYPE] [+terminal=TERMINAL-TYPE] CAPABILITY [PARAMETER ...] Here is an example of how to clear the terminal screen using `tput': tput clear * Menu: * Using tput:: Using the `tput' command. * Output:: Output and exit status. * More Examples:: More examples of using `tput'. * Capabilities:: Summary of terminfo capabilities. * Error Messages:: Error messages produced by `tput'. * Notes:: Miscellaneous information about `tput'. File: tput.info, Node: Using tput, Next: Output, Up: Top Using the `tput' Command ======================== The format of the `tput' command is illustrated below, with the optional portions in square brackets, `[...]': tput [-T TERMINAL-TYPE] [+terminal=TERMINAL-TYPE] CAPABILITY [PARAMETER ...] Some string capabilities accept parameters, such as the number of lines to delete or the column to move to. These parameters are specified on the command line following the capability name. They are always numbers. `-T TERMTYPE' `+terminal=TERMTYPE' This option indicates the type of terminal. By default, this value is taken from the `TERM' environment variable. Below are some example uses of `tput'. *Note Capabilities::, for a complete list of the functions that `tput' can cause terminals to perform. Note that not all terminals can perform any given function. *Note More Examples::, for some more complex samples of `tput' use. The following command moves the cursor to row 10, column 30 of the screen: tput cup 10 30 The following command makes the cursor invisible: tput civis The following command makes the cursor visible again: tput cnorm The following command deletes 10 lines below and including the one on which the cursor is positioned: tput dl 10 File: tput.info, Node: Output, Next: More Examples, Prev: Using tput, Up: Top Output and Exit Status ====================== The `tput' command produces different kinds of output for each of the three types of terminal capabilities: string, numeric, and Boolean. If the terminfo capability given on the command line is a string capability, `tput' displays its value and exits with a status of 0. If the capability is not defined for the terminal type being used, `tput' produces no output and exits with a status of 1. If the capability is a numeric capability, `tput' displays its value (an integer). If the capability is not defined for the terminal type being used, `tput' displays the value `-1'. The exit status is always 0 for numeric capabilities, unless an error occurs (*Note Notes:: for a complete list of the possible exit status values). If the capability is a Boolean capability, `tput' produces no output and exits with status 0 if the capability is defined for the terminal type being used, or status 1 if the capability is not defined. *Note Definitions of the Terminal Capabilities: (termcap)Capabilities, for a more detailed description of termcap capabilities. The values of numeric capabilities should be saved into shell variables so they can be used later without having to run `tput' again. Here is how it can be done: For the Bourne, Bourne-again, and Korn shells: To set an environment variable: COLUMNS=`tput cols` export COLUMNS To set a local variable: tabwidth=`tput it` For the C shell: To set an environment variable: setenv COLUMNS `tput cols` To set a local variable: set tabwidth = `tput it` The values of string capabilities can be saved in shell variables in the same way, then displayed later using the `echo' command. Since `echo' is built into most shells, it runs more quickly than `tput' does. However, using `echo' instead of `tput' to display string values can cause problems for capabilities that use padding, because null padding characters cannot be passed as arguments to commands, including `echo'. File: tput.info, Node: More Examples, Next: Capabilities, Prev: Output, Up: Top Yet More Examples ================= Here are some more advanced examples of using `tput'; most involve some shell programming. Because the C shell's flow control (decision making) constructs differ from those of the other shells, these examples do not work under the C shell. The following sequence of commands prints `I am infalible' and then crosses it out on terminals that can overstrike, and prints `I am on strike' on terminals that cannot. if tput os; then echo 'I am infalible\r- -- ---------' else echo 'I am on strike' fi The following example is a shell script that centers a line of text given as command line arguments. An alternative approach would be to have `tput' send the `rep' terminfo capability to print the multiple spaces instead of using the `while' loop. COLUMNS=`tput cols` export COLUMNS # Get screen width. echo "$@" | awk ' { spaces = ('$COLUMNS' - length) / 2 while (spaces-- > 0) printf (" ") print }' The following commands cause the terminal to save the current cursor position, print `Hello, World' centered in the screen in reverse video, then return to the original cursor position. COLUMNS=`tput cols` LINES=`tput lines` line=`expr $LINES / 2` column=`expr $ $COLUMNS - 6 $ / 2` tput sc tput cup $line $column tput rev echo 'Hello, World' tput sgr0 tput rc File: tput.info, Node: Capabilities, Next: Error Messages, Prev: More Examples, Up: Top Capabilities ============ Boolean Capabilities -------------------- Name Termcap Description Equiv. am am Has automatic margins bw bw `cub1' wraps from column 0 to last column chts HC Cursor is hard to see da da Display may be retained above screen db db Display may be retained below screen eo eo Can erase overstrikes with a blank eslok es Using escape on status line is ok gn gn Generic line type (e.g., `dialup', `switch') hc hc Hardcopy terminal hs hs Has a status line hz hz Hazeltine; cannot print tildes in in Insert mode distinguishes nulls km km Has a meta key (a shift that sets parity bit) mc5i 5i Data sent to printer does not echo on screen mir mi Safe to move while in insert mode msgr ms Safe to move in standout modes npc NP No pad character is needed nrrmc NR `smcup' does not reverse `rmcup' nxon nx Padding does not work; xon/xoff is required os os Overstrikes ul ul Underline character overstrikes xenl xn Newline ignored after 80 columns (Concept) xhp xs Standout is not erased by overwriting (HP) xon xo Uses xon/xoff handshaking xsb xb Beehive (f1=escape, f2=ctrl-c) xt xt Tabs are destructive, magic `smso' (t1061) Numeric Capabilities -------------------- Name Termcap Description Equiv. cols co Number of columns in a line it it Width of initial tab settings lh lh Number of rows in each label lines li Number of lines on screen or page lm lm Lines of memory if > `lines'; 0 means varies lw lw Number of columns in each label nlab Nl Number of labels on screen (start at 1) pb pb Lowest baud rate where padding is needed vt vt Virtual terminal number (CB/Unix) wsl ws Number of columns in status line xmc sg Number of blanks left by `smso' or `rmso' String Capabilities ------------------- In the following table, `(P)' following an explanation means that the capability takes one or more parameters (and is evaluated by the `tparam' function, or in the case of `cup', `tgoto'); `(*)' means that padding may be based on the number of lines affected; and `#n' refers to the `n'th parameter. Name Termcap Description Equiv. acsc ac Graphic character set pairs aAbBcC - default vt100 bel bl Ring bell (beep) blink mb Begin blinking mode bold md Begin double intensity mode cbt bt Back tab civis vi Make cursor invisible clear cl Clear screen (*) cmdch CC Settable command character in prototype cnorm ve Make cursor normal (undo `cvvis' & `civis)' cr cr Carriage return (*) csr cs Change scrolling region to lines #1 through #2 (P) cub LE Move cursor left #1 spaces (P) cub1 le Move cursor left one space cud DO Move cursor down #1 lines (P*) cud1 do Move cursor down one line cuf RI Move cursor right #1 spaces (P*) cuf1 nd Move cursor right one space cup cm Move cursor to row #1, column #2 of screen (P) cuu UP Move cursor up #1 lines (P*) cuu1 up Move cursor up one line cvvis vs Make cursor very visible dch DC Delete #1 characters (P*) dch1 dc Delete one character (*) dim mh Begin half intensity mode dl DL Delete #1 lines (P*) dl1 dl Delete one line (*) dsl ds Disable status line ech ec Erase #1 characters (P) ed cd Clear to end of display (*) el ce Clear to end of line el1 cb Clear to beginning of line, inclusive enacs eA Enable alternate character set ff ff Form feed for hardcopy terminal (*) flash vb Visible bell (must not move cursor) fsl fs Return from status line hd hd Move cursor down one-half line home ho Home cursor (if no `cup') hpa ch Move cursor to column #1 (P) ht ta Tab to next 8 space hardware tab stop hts st Set a tab in all rows, current column hu hu Move cursor up one-half line ich IC Insert #1 blank characters (P*) ich1 ic Insert one blank character if if Name of file containing initialization string il AL Add #1 new blank lines (P*) il1 al Add one new blank line (*) ind sf Scroll forward (up) one line indn SF Scroll forward #1 lines (P) invis mk Begin invisible text mode ip ip Insert pad after character inserted (*) iprog iP Path of program for initialization is1 i1 Terminal initialization string is2 is Terminal initialization string is3 i3 Terminal initialization string kBEG &9 Shifted beginning key kCAN &0 Shifted cancel key kCMD *1 Shifted command key kCPY *2 Shifted copy key kCRT *3 Shifted create key kDC *4 Shifted delete char key kDL *5 Shifted delete line key kEND *7 Shifted end key kEOL *8 Shifted clear line key kEXT *9 Shifted exit key kFND *0 Shifted find key kHLP #1 Shifted help key kHOM #2 Shifted home key kIC #3 Shifted input key kLFT #4 Shifted left arrow key kMOV %b Shifted move key kMSG %a Shifted message key kNXT %c Shifted next key kOPT %d Shifted options key kPRT %f Shifted print key kPRV %e Shifted prev key kRDO %g Shifted redo key kRES %j Shifted resume key kRIT %i Shifted right arrow kRPL %h Shifted replace key kSAV !1 Shifted save key kSPD !2 Shifted suspend key kUND !3 Shifted undo key ka1 K1 Upper left of keypad ka3 K3 Upper right of keypad kb2 K2 Center of keypad kbeg @1 Beginning key kbs kb Backspace key kc1 K4 Lower left of keypad kc3 K5 Lower right of keypad kcan @2 Cancel key kcbt kB Back tab key kclo @3 Close key kclr kC Clear screen or erase key kcmd @4 Command key kcpy @5 Copy key kcrt @6 Create key kctab kt Clear tab key kcub1 kl Left arrow key kcud1 kd Down arrow key kcuf1 kr Right arrow key kcuu1 ku Up arrow key kdch1 kD Delete character key kdl1 kL Delete line key ked kS Clear to end of screen key kel kE Clear to end of line key kend @7 End key kent @8 Enter/send key (unreliable) kext @9 Exit key kf0 k0 Function key f0 kf1 k1 Function key f1 kf10 k; Function key f10 kf11 F1 Function key f11 kf12 F2 Function key f12 kf13 F3 Function key f13 kf14 F4 Function key f14 kf15 F5 Function key f15 kf16 F6 Function key f16 kf17 F7 Function key f17 kf18 F8 Function key f18 kf19 F9 Function key f19 kf2 k2 Function key f2 kf20 FA Function key f20 kf21 FB Function key f21 kf22 FC Function key f22 kf23 FD Function key f23 kf24 FE Function key f24 kf25 FF Function key f25 kf26 FG Function key f26 kf27 FH Function key f27 kf28 FI Function key f28 kf29 FJ Function key f29 kf3 k3 Function key f3 kf30 FK Function key f30 kf31 FL Function key f31 kf32 FM Function key f32 kf33 FN Function key f13 kf34 FO Function key f34 kf35 FP Function key f35 kf36 FQ Function key f36 kf37 FR Function key f37 kf38 FS Function key f38 kf39 FT Function key f39 kf4 k4 Function key f4 kf40 FU Function key f40 kf41 FV Function key f41 kf42 FW Function key f42 kf43 FX Function key f43 kf44 FY Function key f44 kf45 FZ Function key f45 kf46 Fa Function key f46 kf47 Fb Function key f47 kf48 Fc Function key f48 kf49 Fd Function key f49 kf5 k5 Function key f5 kf50 Fe Function key f50 kf51 Ff Function key f51 kf52 Fg Function key f52 kf53 Fh Function key f53 kf54 Fi Function key f54 kf55 Fj Function key f55 kf56 Fk Function key f56 kf57 Fl Function key f57 kf58 Fm Function key f58 kf59 Fn Function key f59 kf6 k6 Function key f6 kf60 Fo Function key f60 kf61 Fp Function key f61 kf62 Fq Function key f62 kf63 Fr Function key f63 kf7 k7 Function key f7 kf8 k8 Function key f8 kf9 k9 Function key f9 kfnd @0 Find key khlp %1 Help key khome kh Home key khts kT Set tab key kich1 kI Ins char/enter ins mode key kil1 kA Insert line key kind kF Scroll forward/down key kll kH Home down key kmov %4 Move key kmrk %2 Mark key kmsg %3 Message key knp kN Next page key knxt %5 Next object key kopn %6 Open key kopt %7 Options key kpp kP Previous page key kprt %9 Print or copy key kprv %8 Previous object key krdo %0 Redo key kref &1 Reference key kres &5 Resume key krfr &2 Refresh key kri kR Scroll backward/up key krmir kM `rmir' or `smir' in insert mode krpl &3 Replace key krst &4 Restart key ksav &6 Save key kslt *6 Select key kspd &7 Suspend key ktbc ka Clear all tabs key kund &8 Undo key lf0 l0 Label on function key f0 if not `f0' lf1 l1 Label on function key f1 if not `f1' lf10 la Label on function key f10 if not `f10' lf2 l2 Label on function key f2 if not `f2' lf3 l3 Label on function key f3 if not `f3' lf4 l4 Label on function key f4 if not `f4' lf5 l5 Label on function key f5 if not `f5' lf6 l6 Label on function key f6 if not `f6' lf7 l7 Label on function key f7 if not `f7' lf8 l8 Label on function key f8 if not `f8' lf9 l9 Label on function key f9 if not `f9' ll ll Go to last line, first column (if no `cup') mc0 ps Print screen contents mc4 pf Turn printer off mc5 po Turn printer on mc5p pO Turn printer on for #1 bytes (P) mgc MC Clear left and right soft margins mrcup CM Move cursor to row #1, column #2 of memory (P) nel nw Newline (like cr followed by lf) pad pc Pad character (rather than nul) pfkey pk Program function key #1 to type string #2 (P) pfloc pl Program function key #1 to execute string #2 (P) pfx px Program function key #1 to transmit string #2 (P) pln pn Program label #1 to show string #2 (P) prot mp Begin protected mode rc rc Restore cursor to position of last `sc' rep rp Repeat character #1, #2 times (P*) rev mr Begin reverse video mode rf rf Name of file containing reset string rfi RF Send next input character (for ptys) ri sr Scroll backward (down) one line rin SR Scroll backward #1 lines (P) rmacs ae End alternate character set rmam RA Turn off automatic margins rmcup te String to end programs that use `cup' rmdc ed End delete mode rmir ei End insert mode rmkx ke End keypad transmit mode rmln LF Turn off soft labels rmm mo End meta mode rmp rP Like `ip' but when in replace mode rmso se End standout mode rmul ue End underscore mode rmxon RX Turn off xon/xoff handshaking rs1 r1 Reset terminal to sane modes rs2 r2 Reset terminal to sane modes rs3 r3 Reset terminal to sane modes sc sc Save cursor position sgr sa Define video attributes #1 through #9 (P) sgr0 me Turn off all attributes smacs as Begin alternate character set smam SA Turn on automatic margins smcup ti String to begin programs that use `cup' smdc dm Begin delete mode smgl ML Set soft left margin to #1 (P) smgr MR Set soft right margin to #1 (P) smir im Begin insert mode smkx ks Begin keypad transmit mode smln LO Turn on soft labels smm mm Begin meta mode (8th bit set) smso so Begin standout mode smul us Begin underscore mode smxon SX Turn on xon/xoff handshaking tbc ct Clear all tab stops tsl ts Go to status line, column #1 (P) uc uc Underscore one character and move past it vpa cv Move cursor to row #1 (P) wind wi Set window to lines #1-#2, columns #3-#4 (P) xoffc XF xoff character xonc XN xon character File: tput.info, Node: Error Messages, Next: Notes, Prev: Capabilities, Up: Top Error Messages ============== `tput' displays various error messages if problems occur. In addition, it exits with one of the following status values: 0 Normal status; the given capability is present. 1 The given Boolean or string capability is not present. 2 Usage error; `tput' was given invalid arguments. 3 The terminal type given (either in the `TERM' environment variable or by the `-T' switch) is unknown, or the termcap database can not be read. 4 The given capability is unknown. File: tput.info, Node: Notes, Prev: Error Messages, Up: Top Notes ===== Terminfo is a database that is similar to termcap but which has different capability names and is stored in a different format. The GNU `tput' command takes a terminfo name as an argument to make it compatible with the Unix System V `tput' command; there is no equivalent command, using termcap, in Berkeley Unix. Bugs ---- The `longname', `init', and `reset' options of the System V `tput' command are not implemented; however, the `tset' command can perform the latter two functions. Author ------ David MacKenzie wrote the GNU `tput' command.