man/man3/termcap.3

   1 .\" Copyright (c) 1980 Regents of the University of California.
   2 .\" All rights reserved.  The Berkeley software License Agreement
   3 .\" specifies the terms and conditions for redistribution.
   4 .\"
   5 .\"     @(#)termcap.3x  6.1 (Berkeley) 5/15/85
   6 .\"
   7 .TH TERMCAP 3 "May 15, 1985"
   8 .UC 4
   9 .SH NAME
  10 termcap, tgetent, tgetnum, tgetflag, tgetstr, tgoto, tputs \- terminal independent operation routines
  11 .SH SYNOPSIS
  12 .nf
  13 .ft B
  14 #include <termcap.h>
  15
  16 int tgetent(char *\fIbp\fP, char *\fIname\fP)
  17 int tgetflag(char *\fIid\fP)
  18 int tgetnum(char *\fIid\fP)
  19 char *tgetstr(char *\fIid\fP, char **\fIarea\fP)
  20 char *tgoto(char *\fIcm\fP, int \fIdestcol\fP, int \fIdestline\fP)
  21 int tputs(char *\fIcp\fP, int \fIaffcnt\fP, void (*\fIoutc\fP)(int))
  22 .ft R
  23 .fi
  24 .SH DESCRIPTION
  25 These functions extract and use capabilities from the terminal capability data
  26 base
  27 .BR termcap (5).
  28 These are low level routines;
  29 see
  30 .BR curses (3)
  31 for a higher level package.
  32 .PP
  33 .B Tgetent
  34 extracts the entry for terminal
  35 .I name
  36 into the buffer at
  37 .IR bp .
  38 .I Bp
  39 should be a character buffer of size
  40 1024 and must be retained through all subsequent calls
  41 to
  42 .BR tgetnum ,
  43 .BR tgetflag ,
  44 and
  45 .BR tgetstr .
  46 .B Tgetent
  47 returns \-1 if it cannot find a termcap
  48 file, 0 if the terminal name given does not have an entry,
  49 and 1 if all goes well.
  50 .PP
  51 .B Tgetent
  52 uses the following recipe to find the termcap file and entry
  53 .IR name :
  54 .PP
  55 .in +5n
  56 if $TERMCAP is itself a termcap entry for
  57 .I name
  58 .br
  59 then
  60 .in +5n
  61 use $TERMCAP
  62 .in -5n
  63 elif $TERMCAP names a file
  64 .br
  65 then
  66 .in +5n
  67 use entry
  68 .I name
  69 found in that file
  70 .in -5n
  71 elif this is Minix-vmd
  72 .br
  73 then
  74 .in +5n
  75 if $TERMPATH is defined
  76 .br
  77 then
  78 .in +5n
  79 search the termcap files named in $TERMPATH for the first occurance of a
  80 .I name
  81 entry and use that entry
  82 .in -5n
  83 else
  84 .in +5n
  85 the path
  86 .B $HOME/.termcap:/etc/termcap:/usr/etc/termcap"
  87 is searched for entry
  88 .I name
  89 .in -5n
  90 fi
  91 .in -5n
  92 fi
  93 .in -5n
  94 .RE
  95 .PP
  96 .B Tgetnum
  97 gets the numeric value of capability
  98 .IR id ,
  99 returning \-1 if is not given for the terminal.
 100 .B Tgetflag
 101 returns 1 if the specified capability is present in
 102 the terminal's entry, 0 if it is not.
 103 .B Tgetstr
 104 returns the string value of the capability
 105 .IR id ,
 106 places it in the buffer at
 107 .IR area ,
 108 and advances the
 109 .I area
 110 pointer.
 111 It decodes the abbreviations for this field described in
 112 .BR termcap (5),
 113 except for cursor addressing and padding information.
 114 .B Tgetstr
 115 returns NULL if the capability was not found.
 116 .PP
 117 .B Tgoto
 118 returns a cursor addressing string decoded from
 119 .I cm
 120 to go to column
 121 .I destcol
 122 in line
 123 .IR destline .
 124 It uses the external variables
 125 .B UP
 126 (from the \fBup\fR capability)
 127 and
 128 .B BC
 129 (if \fBbc\fR is given rather than \fBbs\fR)
 130 if necessary to avoid placing \fB\en\fR, \fB^D\fR or \fB^@\fR in
 131 the returned string.
 132 (Programs which call tgoto should be sure to turn off the XTABS bit(s),
 133 since
 134 .B tgoto
 135 may now output a tab.
 136 Note that programs using termcap should in general turn off XTABS
 137 anyway since some terminals use CTRL-I for other functions,
 138 such as nondestructive space.)
 139 If a \fB%\fR sequence is given which is not understood, then
 140 .B tgoto
 141 returns \*(lqOOPS\*(rq.
 142 .PP
 143 .B Tputs
 144 decodes the leading padding information of the string
 145 .IR cp ;
 146 .I affcnt
 147 gives the number of lines affected by the operation, or 1 if this is
 148 not applicable,
 149 .I outc
 150 is a routine which is called with each character in turn.
 151 The external variable
 152 .B ospeed
 153 should contain the output speed of the terminal as encoded by
 154 .BR stty (3).
 155 The external variable
 156 .B PC
 157 should contain a pad character to be used (from the \fBpc\fR capability)
 158 if a null (\fB^@\fR) is inappropriate.
 159 .SH SEE ALSO
 160 .BR curses (3),
 161 .BR termcap (5).
 162 .SH AUTHOR
 163 William Joy
 164 .SH NOTES
 165 The MINIX 3 implementation does not support any of the external variables,
 166 only the functions calls.  The Minix-vmd termcap does support it all,
 167 although noone in his right mind meddles with those variables.