Return to termcap-1 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / contrib / emacs-18.55 / info

Annotation of 43BSDReno/contrib/emacs-18.55/info/termcap-1, revision 1.1

1.1     ! root        1: Info file: termcap,    -*-Text-*-
        !             2: produced by texinfo-format-buffer
        !             3: from file: termcap.texinfo
        !             4: 
        !             5: This file documents the termcap library of the GNU system.
        !             6: 
        !             7: Copyright (C) 1988 Free Software Foundation, Inc.
        !             8: 
        !             9: Permission is granted to make and distribute verbatim copies of
        !            10: this manual provided the copyright notice and this permission notice
        !            11: are preserved on all copies.
        !            12: 
        !            13: Permission is granted to copy and distribute modified versions of this
        !            14: manual under the conditions for verbatim copying, provided that the entire
        !            15: resulting derived work is distributed under the terms of a permission
        !            16: notice identical to this one.
        !            17: 
        !            18: Permission is granted to copy and distribute translations of this manual
        !            19: into another language, under the above conditions for modified versions,
        !            20: except that this permission notice may be stated in a translation approved
        !            21: by the Foundation.
        !            22: 
        !            23: 
        !            24: 
        !            25: 
        !            26: File: termcap  Node: Top, Prev: (DIR), Up: (DIR), Next: Introduction
        !            27: 
        !            28: * Menu:
        !            29: 
        !            30: * Introduction::What is termcap?  Why this manual?
        !            31: * Library::     The termcap library functions.
        !            32: * Data Base::   What terminal descriptions in `/etc/termcap' look like.
        !            33: * Capabilities::Definitions of the individual terminal capabilities:
        !            34:                  how to write them in descriptions, and how to use
        !            35:                  their values to do display updating.
        !            36: * Var Index::   Index of C functions and variables.
        !            37: * Cap Index::   Index of termcap capabilities.
        !            38: * Index::       Concept index.
        !            39: 
        !            40: 
        !            41: File: termcap  Node: Introduction, Prev: Top, Up: Top, Next: Library
        !            42: 
        !            43: Introduction
        !            44: ************
        !            45: 
        !            46: "Termcap" is a library and data base that enables programs to use
        !            47: display terminals in a terminal-independent manner.  It originated in
        !            48: Berkeley Unix.
        !            49: 
        !            50: The termcap data base describes the capabilities of hundreds of different
        !            51: display terminals in great detail.  Some examples of the information
        !            52: recorded for a terminal could include how many columns wide it is, what
        !            53: string to send to move the cursor to an arbitrary position (including how
        !            54: to encode the row and column numbers), how to scroll the screen up one or
        !            55: several lines, and how much padding is needed for such a scrolling
        !            56: operation.
        !            57: 
        !            58: The termcap library is provided for easy access this data base in programs
        !            59: that want to do terminal-independent character-based display output.
        !            60: 
        !            61: This manual describes the GNU version of the termcap library, which has
        !            62: some extensions over the Unix version.  All the extensions are identified
        !            63: as such, so this manual also tells you how to use the Unix termcap.
        !            64: 
        !            65: The GNU version of the termcap library is available free as source code,
        !            66: for use in free programs, and runs on Unix and VMS systems (at least).  You
        !            67: can find it in the GNU Emacs distribution in the files `termcap.c' and
        !            68: `tparam.c'.
        !            69: 
        !            70: This manual was written for the GNU project, whose goal is to develop a
        !            71: complete free operating system upward-compatible with Unix for user
        !            72: programs.  The project is approximately two thirds complete.  For more
        !            73: information on the GNU project, including the GNU Emacs editor and the
        !            74: mostly-portable optimizing C compiler, send one dollar to
        !            75: 
        !            76:      Free Software Foundation
        !            77:      675 Mass Ave
        !            78:      Cambridge, MA 02139
        !            79: 
        !            80: 
        !            81: File: termcap  Node: Library, Prev: Top, Up: Top, Next: Data Base
        !            82: 
        !            83: The Termcap Library
        !            84: *******************
        !            85: 
        !            86: The termcap library is the application programmer's interface to the
        !            87: termcap data base.  It contains functions for the following purposes:
        !            88: 
        !            89:    * Finding the description of the user's terminal type (`tgetent').
        !            90: 
        !            91:    * Interrogating the description for information on various topics
        !            92:      (`tgetnum', `tgetflag', `tgetstr').
        !            93: 
        !            94:    * Computing and performing padding (`tputs').
        !            95: 
        !            96:    * Encoding numeric parameters such as cursor positions into the
        !            97:      terminal-specific form required for display commands (`tparam',
        !            98:      `tgoto').
        !            99: 
        !           100: * Menu:
        !           101: 
        !           102: * Preparation:: Preparing to use the termcap library.
        !           103: * Find::        Finding the description of the terminal being used.
        !           104: * Interrogate:: Interrogating the description for particular capabilities.
        !           105: * Initialize::  Initialization for output using termcap.
        !           106: * Padding::     Outputting padding.
        !           107: * Parameters::  Encoding parameters such as cursor positions.
        !           108: 
        !           109: 
        !           110: File: termcap  Node: Preparation, Prev: Library, Up: Library, Next: Find
        !           111: 
        !           112: Preparing to Use the Termcap Library
        !           113: ====================================
        !           114: 
        !           115: To use the termcap library in a program, you need two kinds of preparation:
        !           116: 
        !           117:    * The compiler needs declarations of the functions and variables in the
        !           118:      library.
        !           119: 
        !           120:      On GNU systems, it suffices to include the header file `termcap.h'
        !           121:      in each source file that uses these functions and variables.
        !           122: 
        !           123:      On Unix systems, there is often no such header file.  Then you must
        !           124:      explictly declare the variables as external.  You can do likewise for
        !           125:      the functions, or let them be implicitly declared and cast their
        !           126:      values from type `int' to the appropriate type.
        !           127: 
        !           128:      We illustrate the declarations of the individual termcap library
        !           129:      functions with ANSI C prototypes because they show how to pass the
        !           130:      arguments.  If you are not using the GNU C compiler, you probably
        !           131:      cannot use function prototypes, so omit the argument types and names
        !           132:      from your declarations.
        !           133: 
        !           134:    * The linker needs to search the library.  Usually either `-ltermcap'
        !           135:      or `-ltermlib' as an argument when linking will do this.
        !           136: 
        !           137: 
        !           138: File: termcap  Node: Find, Prev: Preparation, Up: Library, Next: Interrogate
        !           139: 
        !           140: Finding a Terminal Description: `tgetent'
        !           141: =========================================
        !           142: 
        !           143: An application program that is going to use termcap must first look up the
        !           144: description of the terminal type in use.  This is done by calling
        !           145: `tgetent', whose declaration in ANSI Standard C looks like:
        !           146: 
        !           147:      int tgetent (char *BUFFER, char *TERMTYPE);
        !           148: 
        !           149: This function finds the description and remembers it internally so that
        !           150: you can interrogate it about specific terminal capabilities
        !           151: (*Note Interrogate::).
        !           152: 
        !           153: The argument TERMTYPE is a string which is the name for the type of
        !           154: terminal to look up.  Usually you would obtain this from the environment
        !           155: variable `TERM' using `getenv ("TERM")'.
        !           156: 
        !           157: If you are using the GNU version of termcap, you can alternatively ask
        !           158: `tgetent' to allocate enough space.  Pass a null pointer for BUFFER, and
        !           159: `tgetent' itself allocates the storage using `malloc'.  In this case the
        !           160: returned value on success is the address of the storage, cast to `int'.
        !           161: But normally there is no need for you to look at the address.  Do not
        !           162: free the storage yourself.
        !           163: 
        !           164: With the Unix version of termcap, you must allocate space for the
        !           165: description yourself and pass the address of the space as the argument
        !           166: BUFFER.  There is no way you can tell how much space is needed, so
        !           167: the convention is to allocate a buffer 2048 characters long and assume that
        !           168: is enough.  (Formerly the convention was to allocate 1024 characters and
        !           169: assume that was enough.  But one day, for one kind of terminal, that was
        !           170: not enough.)
        !           171: 
        !           172: No matter how the space to store the description has been obtained,
        !           173: termcap records its address internally for use when you later
        !           174: interrogate the description with `tgetnum', `tgetstr' or `tgetflag'.  If
        !           175: the buffer was allocated by termcap, it will be freed by termcap too if
        !           176: you call `tgetent' again.  If the buffer was provided by you, you must
        !           177: make sure that its contents remain unchanged for as long as you still
        !           178: plan to interrogate the description.
        !           179: 
        !           180: The return value of `tgetent' is -1 if there is some difficulty
        !           181: accessing the data base of terminal types, 0 if the data base is accessible
        !           182: but the specified type is not defined in it, and some other value
        !           183: otherwise.
        !           184: 
        !           185: Here is how you might use the function `tgetent':
        !           186: 
        !           187:      #ifdef unix
        !           188:      static char term_buffer[2048];
        !           189:      #else
        !           190:      #define term_buffer 0
        !           191:      #endif
        !           192: 
        !           193:      init_terminal_data ()
        !           194:      {
        !           195:        char *termtype = getenv ("TERM");
        !           196:        int success;
        !           197: 
        !           198:        if (termtype == 0)
        !           199:          fatal ("Specify a terminal type with `setenv TERM <yourtype>'.\n");
        !           200: 
        !           201:        success = tgetent (term_buffer, termtype);
        !           202:        if (success < 0)
        !           203:          fatal ("Could not access the termcap data base.\n");
        !           204:        if (success == 0)
        !           205:          fatal ("Terminal type `%s' is not defined.\n", termtype);
        !           206:      }
        !           207: 
        !           208: Here we assume the function `fatal' prints an error message and exits.
        !           209: 
        !           210: If the environment variable `TERMCAP' is defined, its value is used to
        !           211: override the terminal type data base.  The function `tgetent' checks the
        !           212: value of `TERMCAP' automatically.  If the value starts with `/' then it
        !           213: is taken as a file name to use as the data base file, instead of
        !           214: `/etc/termcap' which is the standard data base.  If the value does not
        !           215: start with `/' then it is itself used as the terminal description,
        !           216: provided that the terminal type TERMTYPE is among the types it claims to
        !           217: apply to.  *Note Data Base::, for information on the format of a
        !           218: terminal description.
        !           219: 
        !           220: 
        !           221: File: termcap  Node: Interrogate, Prev: Find, Up: Library, Next: Initialize
        !           222: 
        !           223: Interrogating the Terminal Description
        !           224: ======================================
        !           225: 
        !           226: Each piece of information recorded in a terminal description is called a
        !           227: "capability".  Each defined terminal capability has a two-letter code
        !           228: name and a specific meaning.  For example, the number of columns is named
        !           229: `co'.  *Note Capabilities::, for definitions of all the standard
        !           230: capability names.
        !           231: 
        !           232: Once you have found the proper terminal description with `tgetent'
        !           233: (*Note Find::), your application program must "interrogate" it for
        !           234: various terminal capabilities.  You must specify the two-letter code of
        !           235: the capability whose value you seek.
        !           236: 
        !           237: Capability values can be numeric, boolean (capability is either present
        !           238: or absent) or strings.  Any particular capability always has the same
        !           239: value type; for example, `co' always has a numeric value, while `am'
        !           240: (automatic wrap at margin) is always a flag, and `cm' (cursor motion
        !           241: command) always has a string value.  The documentation of each
        !           242: capability says which type of value it has.
        !           243: 
        !           244: There are three functions to use to get the value of a capability,
        !           245: depending on the type of value the capability has.  Here are their
        !           246: declarations in ANSI C:
        !           247: 
        !           248:      int tgetnum (char *NAME);
        !           249:      int tgetflag (char *NAME);
        !           250:      char *tgetstr (char *NAME, char **AREA);
        !           251: 
        !           252: `tgetnum'
        !           253:      Use `tgetnum' to get a capability value that is numeric.  The
        !           254:      argument NAME is the two-letter code name of the capability.  If
        !           255:      the capability is present, `tgetnum' returns the numeric value
        !           256:      (which is nonnegative).  If the capability is not mentioned in the
        !           257:      terminal description, `tgetnum' returns -1.
        !           258: 
        !           259: `tgetflag'
        !           260:      Use `tgetflag' to get a boolean value.  If the capability
        !           261:      NAME is present in the terminal description, `tgetflag'
        !           262:      returns 1; otherwise, it returns 0.
        !           263: 
        !           264: `tgetstr'
        !           265:      Use `tgetstr' to get a string value.  It returns a pointer to a
        !           266:      string which is the capability value, or a null pointer if the
        !           267:      capability is not present in the terminal description.
        !           268: 
        !           269:      There are two ways `tgetstr' can find space to store the string value:
        !           270: 
        !           271:         * You can ask `tgetstr' to allocate the space.  Pass a null
        !           272:           pointer for the argument AREA, and `tgetstr' will use
        !           273:           `malloc' to allocate storage big enough for the value.
        !           274:           Termcap will never free this storage or refer to it again; you
        !           275:           should free it when you are finished with it.
        !           276: 
        !           277:           This method is more robust, since there is no need to guess how
        !           278:           much space is needed.  But it is supported only by the GNU
        !           279:           termcap library.
        !           280: 
        !           281:         * You can provide the space.  Provide for the argument AREA the
        !           282:           address of a pointer variable of type `char *'.  Before calling
        !           283:           `tgetstr', initialize the variable to point at available space.
        !           284:           Then `tgetstr' will store the string value in that space and will
        !           285:           increment the pointer variable to point after the space that has been
        !           286:           used.  You can use the same pointer variable for many calls to
        !           287:           `tgetstr'.
        !           288: 
        !           289:           There is no way to determine how much space is needed for a single
        !           290:           string, and no way for you to prevent or handle overflow of the area
        !           291:           you have provided.  However, you can be sure that the total size of
        !           292:           all the string values you will obtain from the terminal description is
        !           293:           no greater than the size of the description (unless you get the same
        !           294:           capability twice).  You can determine that size with `strlen' on
        !           295:           the buffer you provided to `tgetent'.  See below for an example.
        !           296: 
        !           297:           Providing the space yourself is the only method supported by the Unix
        !           298:           version of termcap.
        !           299: 
        !           300: Note that you do not have to specify a terminal type or terminal
        !           301: description for the interrogation functions.  They automatically use the
        !           302: description found by the most recent call to `tgetent'.
        !           303: 
        !           304: Here is an example of interrogating a terminal description for various
        !           305: capabilities, with conditionals to select between the Unix and GNU methods
        !           306: of providing buffer space.
        !           307: 
        !           308:      char *tgetstr ();
        !           309: 
        !           310:      char *cl_string, *cm_string;
        !           311:      int height;
        !           312:      int width;
        !           313:      int auto_wrap;
        !           314: 
        !           315:      char PC;   /* For tputs.  */
        !           316:      char *BC;  /* For tgoto.  */
        !           317:      char *UP;
        !           318: 
        !           319:      interrogate_terminal ()
        !           320:      {
        !           321:      #ifdef UNIX
        !           322:        /* Here we assume that an explicit term_buffer
        !           323:           was provided to tgetent.  */
        !           324:        char *buffer
        !           325:          = (char *) malloc (strlen (term_buffer));
        !           326:      #define BUFFADDR &buffer
        !           327:      #else
        !           328:      #define BUFFADDR 0
        !           329:      #endif
        !           330: 
        !           331:        char *temp;
        !           332: 
        !           333:        /* Extract information we will use.  */
        !           334:        cl_string = tgetstr ("cl", BUFFADDR);
        !           335:        cm_string = tgetstr ("cm", BUFFADDR);
        !           336:        auto_wrap = tgetflag ("am");
        !           337:        height = tgetnum ("li");
        !           338:        width = tgetnum ("co");
        !           339: 
        !           340:        /* Extract information that termcap functions use.  */
        !           341:        temp = tgetstr ("pc", BUFFADDR);
        !           342:        PC = temp ? *temp : 0;
        !           343:        BC = tgetstr ("le", BUFFADDR);
        !           344:        UP = tgetstr ("up", BUFFADDR);
        !           345:      }
        !           346: 
        !           347: *Note Padding::, for information on the variable `PC'.  *Note Using Parameters::, for information on `UP' and `BC'.
        !           348: 
        !           349: 
        !           350: File: termcap  Node: Initialize, Prev: Interrogate, Up: Library, Next: Padding
        !           351: 
        !           352: Initialization for Use of Termcap
        !           353: =================================
        !           354: 
        !           355: Before starting to output commands to a terminal using termcap,
        !           356: an application program should do two things:
        !           357: 
        !           358:    * Initialize various global variables which termcap library output
        !           359:      functions refer to.  These include `PC' and `ospeed' for padding
        !           360:      (*Note Output Padding::) and `UP' and `BC' for cursor motion (*Note
        !           361:      tgoto::).
        !           362: 
        !           363:    * Tell the kernel to turn off alteration and padding of horizontal-tab
        !           364:      characters sent to the terminal.
        !           365: 
        !           366: To turn off output processing in Berkeley Unix you would use `ioctl'
        !           367: with code `TIOCLSET' to set the bit named `LLITOUT', and clear the bits
        !           368: `ANYDELAY' using `TIOCSETN'.  In POSIX or System V, you must clear the
        !           369: bit named `OPOST'.  Refer to the system documentation for details.
        !           370: 
        !           371: If you do not set the terminal flags properly, some older terminals will
        !           372: not work.  This is because their commands may contain the characters that
        !           373: normally signify newline, carriage return and horizontal tab---characters
        !           374: which the kernel thinks it ought to modify before output.
        !           375: 
        !           376: When you change the kernel's terminal flags, you must arrange to restore
        !           377: them to their normal state when your program exits.  This implies that the
        !           378: program must catch fatal signals such as `SIGQUIT' and `SIGINT'
        !           379: and restore the old terminal flags before actually terminating.
        !           380: 
        !           381: Modern terminals' commands do not use these special characters, so if you
        !           382: do not care about problems with old terminals, you can leave the kernel's
        !           383: terminal flags unaltered.
        !           384: 
        !           385: 
        !           386: File: termcap  Node: Padding, Prev: Initialize, Up: Library, Next: Parameters
        !           387: 
        !           388: Padding
        !           389: =======
        !           390: 
        !           391: "Padding" means outputting null characters following a terminal display
        !           392: command that takes a long time to execute.  The terminal description says
        !           393: which commands require padding and how much; the function `tputs',
        !           394: described below, outputs a terminal command while extracting from it the
        !           395: padding information, and then outputs the padding that is necessary.
        !           396: 
        !           397: * Menu:
        !           398: 
        !           399: * Why Pad::          Explanation of padding.
        !           400: * Describe Padding:: The data base says how much padding a terminal needs.
        !           401: * Output Padding::   Using `tputs' to output the needed padding.
        !           402: 
        !           403: 
        !           404: File: termcap  Node: Why Pad, Prev: Padding, Up: Padding, Next: Describe Padding
        !           405: 
        !           406: Why Pad, and How
        !           407: ----------------
        !           408: 
        !           409: Most types of terminal have commands that take longer to execute than they
        !           410: do to send over a high-speed line.  For example, clearing the screen may
        !           411: take 20msec once the entire command is received.  During that time, on a
        !           412: 9600 bps line, the terminal could receive about 20 additional output
        !           413: characters while still busy clearing the screen.  Every terminal has a
        !           414: certain amount of buffering capacity to remember output characters that
        !           415: cannot be processed yet, but too many slow commands in a row can cause the
        !           416: buffer to fill up.  Then any additional output that cannot be processed
        !           417: immediately will be lost.
        !           418: 
        !           419: To avoid this problem, we normally follow each display command with enough
        !           420: useless charaters (usually null characters) to fill up the time that the
        !           421: display command needs to execute.  This does the job if the terminal throws
        !           422: away null characters without using up space in the buffer (which most
        !           423: terminals do).  If enough padding is used, no output can ever be lost.  The
        !           424: right amount of padding avoids loss of output without slowing down
        !           425: operation, since the time used to transmit padding is time that nothing
        !           426: else could be done.
        !           427: 
        !           428: The number of padding characters needed for an operation depends on the
        !           429: line speed.  In fact, it is proportional to the line speed.  A 9600 baud
        !           430: line transmits about one character per msec, so the clear screen command in
        !           431: the example above would need about 20 characters of padding.  At 1200 baud,
        !           432: however, only about 3 characters of padding are needed to fill up 20msec.
        !           433: 
        !           434: 
        !           435: File: termcap  Node: Describe Padding, Prev: Why Pad, Up: Padding, Next: Output Padding
        !           436: 
        !           437: Specifying Padding in a Terminal Description
        !           438: --------------------------------------------
        !           439: 
        !           440: In the terminal description, the amount of padding required by each display
        !           441: command is recorded as a sequence of digits at the front of the command.
        !           442: These digits specify the padding time in msec.  They can be followed
        !           443: optionally by a decimal point and one more digit, which is a number of
        !           444: tenths of msec.
        !           445: 
        !           446: Sometimes the padding needed by a command depends on the cursor position.
        !           447: For example, the time taken by an "insert line" command is usually
        !           448: proportional to the number of lines that need to be moved down or cleared.
        !           449: An asterisk (`*') following the padding time says that the time
        !           450: should be multiplied by the number of screen lines affected by the command.
        !           451: 
        !           452:      :al=1.3*\E[L:
        !           453: 
        !           454: is used to describe the "insert line" command for a certain terminal.
        !           455: The padding required is 1.3 msec per line affected.  The command itself is
        !           456: `ESC [ L'.
        !           457: 
        !           458: The padding time specified in this way tells `tputs' how many pad
        !           459: characters to output.  *Note Output Padding::.
        !           460: 
        !           461: Two special capability values affect padding for all commands.  These are
        !           462: the `pc' and `pb'.  The variable `pc' specifies the
        !           463: character to pad with, and `pb' the speed below which no padding is
        !           464: needed.  The defaults for these variables, a null character and 0,
        !           465: are correct for most terminals.  *Note Pad Specs::.
        !           466: 
        !           467: 
        !           468: File: termcap  Node: Output Padding, Prev: Describe Padding, Up: Padding
        !           469: 
        !           470: Performing Padding with `tputs'
        !           471: -------------------------------
        !           472: 
        !           473: Use the termcap function `tputs' to output a string containing an
        !           474: optional padding spec of the form described above (*Note Describe Padding::).  The function `tputs' strips off and decodes the padding
        !           475: spec, outputs the rest of the string, and then outputs the appropriate
        !           476: padding.  Here is its declaration in ANSI C:
        !           477: 
        !           478:      char PC;
        !           479:      short ospeed;
        !           480: 
        !           481:      int tputs (char *STRING, int NLINES, int (*OUTFUN) ());
        !           482: 
        !           483: Here STRING is the string (including padding spec) to be output;
        !           484: NLINES is the number of lines affected by the operation, which is
        !           485: used to multiply the amount of padding if the padding spec ends with a
        !           486: `*'.  Finally, OUTFUN is a function (such as `fputchar')
        !           487: that is called to output each character.  When actually called,
        !           488: OUTFUN should expect one argument, a character.
        !           489: 
        !           490: The operation of `tputs' is controlled by two global variables,
        !           491: `ospeed' and `PC'.  The value of `ospeed' is supposed to be
        !           492: the terminal output speed, encoded as in the `ioctl' system call which
        !           493: gets the speed information.  This is needed to compute the number of
        !           494: padding characters.  The value of `PC' is the character used for
        !           495: padding.
        !           496: 
        !           497: You are responsible for storing suitable values into these variables
        !           498: before using `tputs'.  The value stored into the `PC' variable should be
        !           499: taken from the `pc' capability in the terminal description (*Note Pad
        !           500: Specs::).  Store zero in `PC' if there is no `pc' capability.
        !           501: 
        !           502: The argument NLINES requires some thought.  Normally, it should be the
        !           503: number of lines whose contents will be cleared or moved by the command.
        !           504: For cursor motion commands, or commands that do editing within one line,
        !           505: use the value 1.  For most commands that affect multiple lines, such as
        !           506: `al' (insert a line) and `cd' (clear from the cursor to the end of the
        !           507: screen), NLINES should be the screen height minus the current vertical
        !           508: position (origin 0).  For multiple insert and scroll commands such as
        !           509: `AL' (insert multiple lines), that same value for NLINES is correct; the
        !           510: number of lines being inserted is not correct.
        !           511: 
        !           512: If a "scroll window" feature is used to reduce the number of lines
        !           513: affected by a command, the value of NLINES should take this into
        !           514: account.  This is because the delay time required depends on how much work
        !           515: the terminal has to do, and the scroll window feature reduces the work.
        !           516: *Note Scrolling::.
        !           517: 
        !           518: Commands such as `ic' and `dc' (insert or delete characters) are
        !           519: problematical because the padding needed by these commands is proportional
        !           520: to the number of characters affected, which is the number of columns from
        !           521: the cursor to the end of the line.  It would be nice to have a way to
        !           522: specify such a dependence, and there is no need for dependence on vertical
        !           523: position in these commands, so it is an obvious idea to say that for these
        !           524: commands NLINES should really be the number of columns affected.
        !           525: However, the definition of termcap clearly says that NLINES is always
        !           526: the number of lines affected, even in this case, where it is always 1.  It
        !           527: is not easy to change this rule now, because too many programs and terminal
        !           528: descriptions have been written to follow it.
        !           529: 
        !           530: Because NLINES is always 1 for the `ic' and `dc' strings,
        !           531: there is no reason for them to use `*', but some of them do.  These
        !           532: should be corrected by deleting the `*'.  If, some day, such entries
        !           533: have disappeared, it may be possible to change to a more useful convention
        !           534: for the NLINES argument for these operations without breaking any
        !           535: programs.
        !           536: 
        !           537: 
        !           538: File: termcap  Node: Parameters, Prev: Padding, Up: Library
        !           539: 
        !           540: Filling In Parameters
        !           541: =====================
        !           542: 
        !           543: Some terminal control strings require numeric "parameters".  For
        !           544: example, when you move the cursor, you need to say what horizontal and
        !           545: vertical positions to move it to.  The value of the terminal's `cm'
        !           546: capability, which says how to move the cursor, cannot simply be a string of
        !           547: characters; it must say how to express the cursor position numbers and
        !           548: where to put them within the command.
        !           549: 
        !           550: The specifications of termcap include conventions as to which string-valued
        !           551: capabilities require parameters, how many parameters, and what the
        !           552: parameters mean; for example, it defines the `cm' string to take
        !           553: two parameters, the vertical and horizontal positions, with 0,0 being the
        !           554: upper left corner.  These conventions are described where the individual
        !           555: commands are documented.
        !           556: 
        !           557: Termcap also defines a language used within the capability definition for
        !           558: specifying how and where to encode the parameters for output.  This language
        !           559: uses character sequences starting with `%'.  (This is the same idea as
        !           560: `printf', but the details are different.)  The language for parameter
        !           561: encoding is described in this section.
        !           562: 
        !           563: A program that is doing display output calls the functions `tparam' or
        !           564: `tgoto' to encode parameters according to the specifications.  These
        !           565: functions produce a string containing the actual commands to be output (as
        !           566: well a padding spec which must be processed with `tputs';
        !           567: *Note Padding::).
        !           568: 
        !           569: * Menu:
        !           570: 
        !           571: * Encode Parameters:: The language for encoding parameters.
        !           572: * Using Parameters::  Outputting a string command with parameters.
        !           573: 
        !           574: 
        !           575: File: termcap  Node: Encode Parameters, Prev: Parameters, Up: Parameters, Next: Using Parameters
        !           576: 
        !           577: Describing the Encoding
        !           578: -----------------------
        !           579: 
        !           580: A terminal command string that requires parameters contains special
        !           581: character sequences starting with `%' to say how to encode the
        !           582: parameters.  These sequences control the actions of `tparam' and
        !           583: `tgoto'.
        !           584: 
        !           585: The parameters values passed to `tparam' or `tgoto' are
        !           586: considered to form a vector.  A pointer into this vector determines
        !           587: the next parameter to be processed.  Some of the `%'-sequences
        !           588: encode one parameter and advance the pointer to the next parameter.
        !           589: Other `%'-sequences alter the pointer or alter the parameter
        !           590: values without generating output.
        !           591: 
        !           592: For example, the `cm' string for a standard ANSI terminal is written
        !           593: as `\E[%i%d;%dH'.  (`\E' stands for ESC.)  `cm' by
        !           594: convention always requires two parameters, the vertical and horizontal goal
        !           595: positions, so this string specifies the encoding of two parameters.  Here
        !           596: `%i' increments the two values supplied, and each `%d' encodes
        !           597: one of the values in decimal.  If the cursor position values 20,58 are
        !           598: encoded with this string, the result is `\E[21;59H'.
        !           599: 
        !           600: First, here are the `%'-sequences that generate output.  Except for
        !           601: `%%', each of them encodes one parameter and advances the pointer
        !           602: to the following parameter.
        !           603: 
        !           604: `%%'
        !           605:      Output a single `%'.  This is the only way to represent a literal
        !           606:      `%' in a terminal command with parameters.  `%%' does not
        !           607:      use up a parameter.
        !           608: 
        !           609: `%d'
        !           610:      As in `printf', output the next parameter in decimal.
        !           611: 
        !           612: `%2'
        !           613:      Like `%02d' in `printf': output the next parameter in
        !           614:      decimal, and always use at least two digits.
        !           615: 
        !           616: `%3'
        !           617:      Like `%03d' in `printf': output the next parameter in
        !           618:      decimal, and always use at least three digits.  Note that `%4'
        !           619:      and so on are *not* defined.
        !           620: 
        !           621: `%.'
        !           622:      Output the next parameter as a single character whose ASCII code is
        !           623:      the parameter value.  Like `%c' in `printf'.
        !           624: 
        !           625: `%+CHAR'
        !           626:      Add the next parameter to the character CHAR, and output the
        !           627:      resulting character.  For example, `%+ ' represents 0 as a space,
        !           628:      1 as `!', etc.
        !           629: 
        !           630: The following `%'-sequences specify alteration of the parameters (their
        !           631: values, or their order) rather than encoding a parameter for output.
        !           632: They generate no output; they are used only for their side effects on
        !           633: the parameters.  Also, they do not advance the "next parameter" pointer
        !           634: except as explicitly stated.  Only `%i', `%r' and `%>' are defined in
        !           635: standard Unix termcap.  The others are GNU extensions.
        !           636: 
        !           637: `%i'
        !           638:      Increment the next two parameters.  This is used for terminals that
        !           639:      expect cursor positions in origin 1.  For example, `%i%d,%d' would
        !           640:      output two parameters with `1' for 0, `2' for 1, etc.
        !           641: 
        !           642: `%r'
        !           643:      Interchange the next two parameters.  This is used for terminals whose
        !           644:      cursor positioning command expects the horizontal position first.
        !           645: 
        !           646: `%s'
        !           647:      Skip the next parameter.  Do not output anything.
        !           648: 
        !           649: `%b'
        !           650:      Back up one parameter.  The last parameter used will become once again
        !           651:      the next parameter to be output, and the next output command will use
        !           652:      it.  Using `%b' more than once, you can back up any number of
        !           653:      parameters, and you can refer to each parameter any number of times.
        !           654: 
        !           655: `%>C1C2'
        !           656:      Conditionally increment the next parameter.  Here C1 and C2 are
        !           657:      characters which stand for their ASCII codes as numbers.  If the
        !           658:      next parameter is greater than the ASCII code of C1, the ASCII code
        !           659:      of C2 is added to it.
        !           660: 
        !           661: `%a OP TYPE POS'
        !           662:      Perform arithmetic on the next parameter, do not use it up, and do not
        !           663:      output anything.  Here OP specifies the arithmetic operation,
        !           664:      while TYPE and POS together specify the other operand.
        !           665: 
        !           666:      Spaces are used above to separate the operands for clarity; the spaces
        !           667:      don't appear in the data base, where this sequence is exactly five
        !           668:      characters long.
        !           669: 
        !           670:      The character OP says what kind of arithmetic operation to
        !           671:      perform.  It can be any of these characters:
        !           672: 
        !           673:      `='
        !           674:           assign a value to the next parameter, ignoring its old value.
        !           675:           The new value comes from the other operand.
        !           676: 
        !           677:      `+'
        !           678:           add the other operand to the next parameter.
        !           679: 
        !           680:      `-'
        !           681:           subtract the other operand from the next parameter.
        !           682: 
        !           683:      `*'
        !           684:           multiply the next parameter by the other operand.
        !           685: 
        !           686:      `/'
        !           687:           divide the next parameter by the other operand.
        !           688: 
        !           689:      The "other operand" may be another parameter's value or a constant;
        !           690:      the character TYPE says which.  It can be:
        !           691: 
        !           692:      `p'
        !           693:           Use another parameter.  The character POS says which
        !           694:           parameter to use.  Subtract 64 from its ASCII code to get the
        !           695:           position of the desired parameter relative to this one.  Thus,
        !           696:           the character `A' as POS means the parameter after the
        !           697:           next one; the character `?' means the parameter before the
        !           698:           next one.
        !           699: 
        !           700:      `c'
        !           701:           Use a constant value.  The character POS specifies the
        !           702:           value of the constant.  The 0200 bit is cleared out, so that 0200
        !           703:           can be used to represent zero.
        !           704: 
        !           705: The following `%'-sequences are special purpose hacks to compensate
        !           706: for the weird designs of obscure terminals.  They modify the next parameter
        !           707: or the next two parameters but do not generate output and do not use up any
        !           708: parameters.  `%m' is a GNU extension; the others are defined in
        !           709: standard Unix termcap.
        !           710: 
        !           711: `%n'
        !           712:      Exclusive-or the next parameter with 0140, and likewise the parameter
        !           713:      after next.
        !           714: 
        !           715: `%m'
        !           716:      Complement all the bits of the next parameter and the parameter after next.
        !           717: 
        !           718: `%B'
        !           719:      Encode the next parameter in BCD.  It alters the value of the
        !           720:      parameter by adding six times the quotient of the parameter by ten.
        !           721:      Here is a C statement that shows how the new value is computed:
        !           722: 
        !           723:           PARM = (PARM / 10) * 16 + PARM % 10;
        !           724: 
        !           725: `%D'
        !           726:      Transform the next parameter as needed by Delta Data terminals.
        !           727:      This involves subtracting twice the remainder of the parameter by 16.
        !           728: 
        !           729:           PARM -= 2 * (PARM % 16);
        !           730: 
        !           731: 
        !           732: File: termcap  Node: Using Parameters, Prev: Encode Parameters, Up: Parameters
        !           733: 
        !           734: Sending Display Commands with Parameters
        !           735: ----------------------------------------
        !           736: 
        !           737: The termcap library functions `tparam' and `tgoto' serve as the
        !           738: analog of `printf' for terminal string parameters.  The newer function
        !           739: `tparam' is a GNU extension, more general but missing from Unix
        !           740: termcap.  The original parameter-encoding function is `tgoto', which
        !           741: is preferable for cursor motion.
        !           742: 
        !           743: * Menu:
        !           744: 
        !           745: * tparam::   The general case, for GNU termcap only.
        !           746: * tgoto::    The special case of cursor motion.
        !           747: 
        !           748: 
        !           749: File: termcap  Node: tparam, Prev: Using Parameters, Up: Using Parameters, Next: tgoto
        !           750: 
        !           751: `tparam'
        !           752: ........
        !           753: 
        !           754: The function `tparam' can encode display commands with any number of
        !           755: parameters and allows you to specify the buffer space.  It is the preferred
        !           756: function for encoding parameters for all but the `cm' capability.  Its
        !           757: ANSI C declaration is as follows:
        !           758: 
        !           759:      char *tparam (char *CTLSTRING, char *BUFFER, int SIZE, int PARM1,...)
        !           760: 
        !           761: The arguments are a control string CTLSTRING (the value of a terminal
        !           762: capability, presumably), an output buffer BUFFER and SIZE, and
        !           763: any number of integer parameters to be encoded.  The effect of
        !           764: `tparam' is to copy the control string into the buffer, encoding
        !           765: parameters according to the `%' sequences in the control string.
        !           766: 
        !           767: You describe the output buffer by its address, BUFFER, and its size
        !           768: in bytes, SIZE.  If the buffer is not big enough for the data to be
        !           769: stored in it, `tparam' calls `malloc' to get a larger buffer.  In
        !           770: either case, `tparam' returns the address of the buffer it ultimately
        !           771: uses.  If the value equals BUFFER, your original buffer was used.
        !           772: Otherwise, a new buffer was allocated, and you must free it after you are
        !           773: done with printing the results.  If you pass zero for SIZE and
        !           774: BUFFER, `tparam' always allocates the space with `malloc'.
        !           775: 
        !           776: All capabilities that require parameters also have the ability to specify
        !           777: padding, so you should use `tputs' to output the string produced by
        !           778: `tparam'.  *Note Padding::.  Here is an example.
        !           779: 
        !           780:      {
        !           781:        char *buf;
        !           782:        char buffer[40];
        !           783: 
        !           784:        buf = tparam (command, buffer, 40, parm);
        !           785:        tputs (buf, 1, fputchar);
        !           786:        if (buf != buffer)
        !           787:          free (buf);
        !           788:      }
        !           789: 
        !           790: If a parameter whose value is zero is encoded with `%.'-style encoding,
        !           791: the result is a null character, which will confuse `tputs'.  This would
        !           792: be a serious problem, but luckily `%.' encoding is used only by a few
        !           793: old models of terminal, and only for the `cm' capability.  To solve the
        !           794: problem, use `tgoto' rather than `tparam' to encode the `cm' capability.
        !           795: 
        !           796: 
        !           797: File: termcap  Node: tgoto, Prev: tparam, Up: Using Parameters
        !           798: 
        !           799: `tgoto'
        !           800: .......
        !           801: 
        !           802: The special case of cursor motion is handled by `tgoto'.  There
        !           803: are two reasons why you might choose to use `tgoto':
        !           804: 
        !           805:    * For Unix compatibility, because Unix termcap does not have `tparam'.
        !           806: 
        !           807:    * For the `cm' capability, since `tgoto' has a special feature
        !           808:      to avoid problems with null characters, tabs and newlines on certain old
        !           809:      terminal types that use `%.' encoding for that capability.
        !           810: 
        !           811: Here is how `tgoto' might be declared in ANSI C:
        !           812: 
        !           813:      char *tgoto (char *CSTRING, int HPOS, int VPOS)
        !           814: 
        !           815: There are three arguments, the terminal description's `cm' string and
        !           816: the two cursor position numbers; `tgoto' computes the parametrized
        !           817: string in an internal static buffer and returns the address of that buffer.
        !           818: The next time you use `tgoto' the same buffer will be reused.
        !           819: 
        !           820: Parameters encoded with `%.' encoding can generate null characters,
        !           821: tabs or newlines.  These might cause trouble: the null character because
        !           822: `tputs' would think that was the end of the string, the tab because
        !           823: the kernel or other software might expand it into spaces, and the newline
        !           824: becaue the kernel might add a carriage-return, or padding characters
        !           825: normally used for a newline.  To prevent such problems, `tgoto' is
        !           826: careful to avoid these characters.  Here is how this works: if the target
        !           827: cursor position value is such as to cause a problem (that is to say, zero,
        !           828: nine or ten), `tgoto' increments it by one, then compensates by
        !           829: appending a string to move the cursor back or up one position.
        !           830: 
        !           831: The compensation strings to use for moving back or up are found in global
        !           832: variables named `BC' and `UP'.  These are actual external C
        !           833: variables with upper case names; they are declared `char *'.  It is up
        !           834: to you to store suitable values in them, normally obtained from the
        !           835: `le' and `up' terminal capabilities in the terminal description
        !           836: with `tgetstr'.  Alternatively, if these two variables are both zero,
        !           837: the feature of avoiding nulls, tabs and newlines is turned off.
        !           838: 
        !           839: It is safe to use `tgoto' for commands other than `cm' only if
        !           840: you have stored zero in `BC' and `UP'.
        !           841: 
        !           842: Note that `tgoto' reverses the order of its operands: the horizontal
        !           843: position comes before the vertical position in the arguments to `tgoto',
        !           844: even though the vertical position comes before the horizontal in the
        !           845: parameters of the `cm' string.  If you use `tgoto' with a command such
        !           846: as `AL' that takes one parameter, you must pass the parameter to `tgoto'
        !           847: as the "vertical position".
        !           848: 
        !           849: 
        !           850: File: termcap  Node: Data Base, Prev: Library, Up: Top, Next: Capabilities
        !           851: 
        !           852: The Format of the Data Base
        !           853: ***************************
        !           854: 
        !           855: The termcap data base of terminal descriptions is stored in the file
        !           856: `/etc/termcap'.  It contains terminal descriptions, blank lines, and
        !           857: comments.
        !           858: 
        !           859: A terminal description starts with one or more names for the terminal type.
        !           860: The information in the description is a series of "capability names"
        !           861: and values.  The capability names have standard meanings
        !           862: (*Note Capabilities::) and their values describe the terminal.
        !           863: 
        !           864: * Menu:
        !           865: 
        !           866: * Format::            Overall format of a terminal description.
        !           867: * Capability Format:: Format of capabilities within a description.
        !           868: * Naming::            Naming conventions for terminal types.
        !           869: * Inheriting::        Inheriting part of a description from
        !           870:                         a related terminal type.
        !           871: 
        !           872: 
        !           873: File: termcap  Node: Format, Prev: Data Base, Up: Data Base, Next: Capability Format
        !           874: 
        !           875: Terminal Description Format
        !           876: ===========================
        !           877: 
        !           878: Aside from comments (lines starting with `#', which are ignored), each
        !           879: nonblank line in the termcap data base is a terminal description.
        !           880: A terminal description is nominally a single line, but it can be split
        !           881: into multiple lines by inserting the two characters `\ newline'.
        !           882: This sequence is ignored wherever it appears in a description.
        !           883: 
        !           884: The preferred way to split the description is between capabilities: insert
        !           885: the four characters `: \ newline tab' immediately before any colon.
        !           886: This allows each sub-line to start with some indentation.  This works
        !           887: because, after the `\ newline' are ignored, the result is `: tab
        !           888: :'; the first colon ends the preceding capability and the second colon
        !           889: starts the next capability.  If you split with `\ newline' alone, you
        !           890: may not add any indentation after them.
        !           891: 
        !           892: Here is a real example of a terminal description:
        !           893: 
        !           894:      dw|vt52|DEC vt52:\
        !           895:              :cr=^M:do=^J:nl=^J:bl=^G:\
        !           896:              :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:cm=\EY%+ %+ :co#80:li#24:\
        !           897:              :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\
        !           898:              :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H:
        !           899: 
        !           900: Each terminal description begins with several names for the terminal type.
        !           901: The names are separated by `|' characters, and a colon ends the last
        !           902: name.  The first name should be two characters long; it exists only for the
        !           903: sake of very old Unix systems and is never used in modern systems.  The
        !           904: last name should be a fully verbose name such as "DEC vt52" or "Ann
        !           905: Arbor Ambassador with 48 lines".  The other names should include whatever
        !           906: the user ought to be able to specify to get this terminal type, such as
        !           907: `vt52' or `aaa-48'.  *Note Naming::, for information on how to
        !           908: choose terminal type names.
        !           909: 
        !           910: After the terminal type names come the terminal capabilities, separated by
        !           911: colons and with a colon after the last one.  Each capability has a
        !           912: two-letter name, such as `cm' for "cursor motion string" or `li'
        !           913: for "number of display lines".
        !           914: 
        !           915: 
        !           916: File: termcap  Node: Capability Format, Prev: Format, Up: Data Base, Next: Naming
        !           917: 
        !           918: Writing the Capabilities
        !           919: ========================
        !           920: 
        !           921: There are three kinds of capabilities: flags, numbers, and strings.  Each
        !           922: kind has its own way of being written in the description.  Each defined
        !           923: capability has by convention a particular kind of value; for example,
        !           924: `li' always has a numeric value and `cm' always a string value.
        !           925: 
        !           926: A flag capability is thought of as having a boolean value: the value is
        !           927: true if the capability is present, false if not.  When the capability is
        !           928: present, just write its name between two colons.
        !           929: 
        !           930: A numeric capability has a value which is a nonnegative number.  Write
        !           931: the capability name, a `#', and the number, between two colons.  For
        !           932: example, `...:li#48:...' is how you specify the `li' capability for 48
        !           933: lines.
        !           934: 
        !           935: A string-valued capability has a value which is a sequence of
        !           936: characters.  Usually these are the characters used to perform some
        !           937: display operation.  Write the capability name, a `=', and the characters
        !           938: of the value, between two colons.  For example, `...:cm=\E[%i%d;%dH:...'
        !           939: is how the cursor motion command for a standard ANSI terminal would be
        !           940: specified.
        !           941: 
        !           942: Special characters in the string value can be expressed using `\'-escape
        !           943: sequences as in C; in addition, `\E' stands for ESC.  `^' is also a kind
        !           944: of escape character; `^' followed by CHAR stands for the
        !           945: control-equivalent of CHAR.  Thus, `^a' stands for the character
        !           946: control-a, just like `\001'.  `\' and `^' themselves can be represented
        !           947: as `\\' and `\^'.
        !           948: 
        !           949: To include a colon in the string, you must write `\072'.  You might
        !           950: ask, "Why can't `\:' be used to represent a colon?"  The reason is
        !           951: that the interrogation functions do not count slashes while looking for a
        !           952: capability.  Even if `:ce=ab\:cd:' were interpreted as giving the
        !           953: `ce' capability the value `ab:cd', it would also appear to define
        !           954: `cd' as a flag.
        !           955: 
        !           956: The string value will often contain digits at the front to specify padding
        !           957: (*Note Padding::) and/or `%'-sequences within to specify how to encode
        !           958: parameters (*Note Parameters::).  Although these things are not to be
        !           959: output literally to the terminal, they are considered part of the value of
        !           960: the capability.  They are special only when the string value is processed
        !           961: by `tputs', `tparam' or `tgoto'.  By contrast, `\' and
        !           962: `^' are considered part of the syntax for specifying the characters
        !           963: in the string.
        !           964: 
        !           965: Let's look at the VT52 example again:
        !           966: 
        !           967:      dw|vt52|DEC vt52:\
        !           968:              :cr=^M:do=^J:nl=^J:bl=^G:\
        !           969:              :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:cm=\EY%+ %+ :co#80:li#24:\
        !           970:              :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\
        !           971:              :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H:
        !           972: 
        !           973: Here we see the numeric-valued capabilities `co' and `li', the
        !           974: flags `bs' and `pt', and many string-valued capabilities.  Most
        !           975: of the strings start with ESC represented as `\E'.  The rest
        !           976: contain control characters represented using `^'.  The meanings of the
        !           977: individual capabilities are defined elsewhere (*Note Capabilities::).
        !           978: 
        !           979: 
        !           980: File: termcap  Node: Naming, Prev: Capability Format, Up: Data Base, Next: Inheriting
        !           981: 
        !           982: Terminal Type Name Conventions
        !           983: ==============================
        !           984: 
        !           985: There are conventions for choosing names of terminal types.  For one thing,
        !           986: all letters should be in lower case.  The terminal type for a terminal in
        !           987: its most usual or most fundamental mode of operation should not have a
        !           988: hyphen in it.
        !           989: 
        !           990: If the same terminal has other modes of operation which require
        !           991: different terminal descriptions, these variant descriptions are given
        !           992: names made by adding suffixes with hyphens.  Such alternate descriptions
        !           993: are used for two reasons:
        !           994: 
        !           995:    * When the terminal has a switch that changes its behavior.  Since the
        !           996:      computer cannot tell how the switch is set, the user must tell the
        !           997:      computer by choosing the appropriate terminal type name.
        !           998: 
        !           999:      For example, the VT-100 has a setup flag that controls whether the
        !          1000:      cursor wraps at the right margin.  If this flag is set to "wrap",
        !          1001:      you must use the terminal type `vt100-am'.  Otherwise you must use
        !          1002:      `vt100-nam'.  Plain `vt100' is defined as a synonym for either
        !          1003:      `vt100-am' or `vt100-nam' depending on the preferences of the local
        !          1004:      site.
        !          1005: 
        !          1006:      The standard suffix `-am' stands for "automatic margins".
        !          1007: 
        !          1008:    * To give the user a choice in how to use the terminal.  This is done
        !          1009:      when the terminal has a switch that the computer normally controls.
        !          1010: 
        !          1011:      For example, the Ann Arbor Ambassador can be configured with many
        !          1012:      screen sizes ranging from 20 to 60 lines.  Fewer lines make bigger
        !          1013:      characters but more lines let you see more of what you are editing.
        !          1014:      As a result, users have different preferences.  Therefore, termcap
        !          1015:      provides terminal types for many screen sizes.  If you choose type
        !          1016:      `aaa-30', the terminal will be configured to use 30 lines; if you
        !          1017:      choose `aaa-48', 48 lines will be used, and so on.
        !          1018: 
        !          1019: Here is a list of standard suffixes and their conventional meanings:
        !          1020: 
        !          1021: `-w'
        !          1022:      Short for "wide".  This is a mode that gives the terminal more
        !          1023:      columns than usual.  This is normally a user option.
        !          1024: 
        !          1025: `-am'
        !          1026:      "Automatic margins".  This is an alternate description for use when
        !          1027:      the terminal's margin-wrap switch is on; it contains the `am'
        !          1028:      flag.  The implication is that normally the switch is off and the
        !          1029:      usual description for the terminal says that the switch is off.
        !          1030: 
        !          1031: `-nam'
        !          1032:      "No automatic margins".  The opposite of `-am', this names an
        !          1033:      alternative description which lacks the `am' flag.  This implies
        !          1034:      that the terminal is normally operated with the margin-wrap switch
        !          1035:      turned on, and the normal description of the terminal says so.
        !          1036: 
        !          1037: `-na'
        !          1038:      "No arrows".  This terminal description initializes the terminal to
        !          1039:      keep its arrow keys in local mode.  This is a user option.
        !          1040: 
        !          1041: `-rv'
        !          1042:      "Reverse video".  This terminal description causes text output for
        !          1043:      normal video to appear as reverse, and text output for reverse
        !          1044:      video to come out as normal.  Often this description differs from
        !          1045:      the usual one by interchanging the two strings which turn reverse
        !          1046:      video on and off.
        !          1047: 
        !          1048:      This is a user option; you can choose either the "reverse video"
        !          1049:      variant terminal type or the normal terminal type, and termcap will
        !          1050:      obey.
        !          1051: 
        !          1052: `-s'
        !          1053:      "Status".  Says to enable use of a status line which ordinary output
        !          1054:      does not touch (*Note Status Line::).
        !          1055: 
        !          1056:      Some terminals have a special line that is used only as a status line.
        !          1057:      For these terminals, there is no need for an `-s' variant; the
        !          1058:      status line commands should be defined by default.  On other
        !          1059:      terminals, enabling a status line means removing one screen line from
        !          1060:      ordinary use and reducing the effective screen height.  For these
        !          1061:      terminals, the user can choose the `-s' variant type to request
        !          1062:      use of a status line.
        !          1063: 
        !          1064: `-NLINES'
        !          1065:      Says to operate with NLINES lines on the screen, for terminals
        !          1066:      such as the Ambassador which provide this as an option.  Normally this
        !          1067:      is a user option; by choosing the terminal type, you control how many
        !          1068:      lines termcap will use.
        !          1069: 
        !          1070: `-NPAGESp'
        !          1071:      Says that the terminal has NPAGES pages worth of screen memory,
        !          1072:      for terminals where this is a hardware option.
        !          1073: 
        !          1074: `-unk'
        !          1075:      Says that description is not for direct use, but only for reference in
        !          1076:      `tc' capabilities.  Such a description is a kind of subroutine,
        !          1077:      because it describes the common characteristics of several variant
        !          1078:      descriptions that would use other suffixes in place of `-unk'.
        !          1079: 
        !          1080: 
        !          1081: File: termcap  Node: Inheriting, Prev: Naming, Up: Data Base
        !          1082: 
        !          1083: Inheriting from Related Descriptions
        !          1084: ====================================
        !          1085: 
        !          1086: When two terminal descriptions are similar, their identical parts do not
        !          1087: need to be given twice.  Instead, one of the two can be defined in terms of
        !          1088: the other, using the `tc' capability.  We say that one description
        !          1089: "refers to" the other, or "inherits from" the other.
        !          1090: 
        !          1091: The `tc' capability must be the last one in the terminal description,
        !          1092: and its value is a string which is the name of another terminal type which
        !          1093: is referred to.  For example,
        !          1094: 
        !          1095:      N9|aaa|ambassador|aaa-30|ann arbor ambassador/30 lines:\
        !          1096:              :ti=\E[2J\E[30;0;0;30p:\
        !          1097:              :te=\E[60;0;0;30p\E[30;1H\E[J:\
        !          1098:              :li#30:tc=aaa-unk:
        !          1099: 
        !          1100: defines the terminal type `aaa-30' (also known as plain `aaa') in
        !          1101: terms of `aaa-unk', which defines everything about the Ambassador that
        !          1102: is independent of screen height.  The types `aaa-36', `aaa-48'
        !          1103: and so on for other screen heights are likewise defined to inherit from
        !          1104: `aaa-unk'.
        !          1105: 
        !          1106: The capabilities overridden by `aaa-30' include `li', which says
        !          1107: how many lines there are, and `ti' and `te', which configure the
        !          1108: terminal to use that many lines.
        !          1109: 
        !          1110: The effective terminal description for type `aaa' consists of the text
        !          1111: shown above followed by the text of the description of `aaa-unk'.  The
        !          1112: `tc' capability is handled automatically by `tgetent', which
        !          1113: finds the description thus referenced and combines the two descriptions
        !          1114: (*Note Find::).  Therefore, only the implementor of the terminal
        !          1115: descriptions needs to think about using `tc'.  Users and application
        !          1116: programmers do not need to be concerned with it.
        !          1117: 
        !          1118: Since the reference terminal description is used last, capabilities
        !          1119: specified in the referring description override any specifications of the
        !          1120: same capabilities in the reference description.
        !          1121: 
        !          1122: The referring description can cancel out a capability without specifying
        !          1123: any new value for it by means of a special trick.  Write the capability in
        !          1124: the referring description, with the character `@' after the capability
        !          1125: name, as follows:
        !          1126: 
        !          1127:      NZ|aaa-30-nam|ann arbor ambassador/30 lines/no automatic-margins:\
        !          1128:              :am@:tc=aaa-30:
        !          1129: 
        !          1130: 
        !          1131: File: termcap  Node: Capabilities, Prev: Data Base, Up: Top, Next: Summary
        !          1132: 
        !          1133: Definitions of the Terminal Capabilities
        !          1134: ****************************************
        !          1135: 
        !          1136: This section is divided into many subsections, each for one aspect of
        !          1137: use of display terminals.  For writing a display program, you usually need
        !          1138: only check the subsections for the operations you want to use.  For writing
        !          1139: a terminal description, you must read each subsection and fill in the
        !          1140: capabilities described there.
        !          1141: 
        !          1142: String capabilities that are display commands may require numeric
        !          1143: parameters (*Note Parameters::).  Most such capabilities do not use
        !          1144: parameters.  When a capability requires parameters, this is explicitly
        !          1145: stated at the beginning of its definition.  In simple cases, the first or
        !          1146: second sentence of the definition mentions all the parameters, in the order
        !          1147: they should be given, using a name
        !          1148: in upper case
        !          1149: for each one.  For example, the `rp' capability is a command that
        !          1150: requires two parameters; its definition begins as follows:
        !          1151: 
        !          1152:      String of commands to output a graphic character C, repeated N
        !          1153:      times.
        !          1154: 
        !          1155: In complex cases or when there are many parameters, they are described
        !          1156: explicitly.
        !          1157: 
        !          1158: When a capability is described as obsolete, this means that programs should
        !          1159: not be written to look for it, but terminal descriptions should still be
        !          1160: written to provide it.
        !          1161: 
        !          1162: When a capability is described as very obsolete, this means that it should
        !          1163: be omitted from terminal descriptions as well.
        !          1164: 
        !          1165: * Menu:
        !          1166: 
        !          1167: * Basic::             Basic characteristics.
        !          1168: * Screen Size::       Screen size, and what happens when it changes.
        !          1169: * Cursor Motion::     Various ways to move the cursor.
        !          1170: * Scrolling::         Pushing text up and down on the screen.
        !          1171: * Wrapping::          What happens if you write a character in the last column.
        !          1172: * Windows::           Limiting the part of the window that output affects.
        !          1173: * Clearing::          Erasing one or many lines.
        !          1174: * Insdel Line::       Making new blank lines in mid-screen; deleting lines.
        !          1175: * Insdel Char::       Inserting and deleting characters within a line.
        !          1176: * Standout::          Highlighting some of the text.
        !          1177: * Underlining::       Underlining some of the text.
        !          1178: * Cursor Visibility:: Making the cursor more or less easy to spot.
        !          1179: * Bell::              Attracts user's attention; not localized on the screen.
        !          1180: * Keypad::            Recognizing when function keys or arrows are typed.
        !          1181: * Meta Key::          META acts like an extra shift key.
        !          1182: * Initialization::    Commands used to initialize or reset the terminal.
        !          1183: * Pad Specs::         Info for the kernel on how much padding is needed.
        !          1184: * Status Line::       A status line displays "background" information.
        !          1185: * Half-Line::         Moving by half-lines, for superscripts and subscripts.
        !          1186: * Printer::           Controlling auxiliary printers of display terminals.
        !          1187: 
        !          1188: 

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.