lib/libterminfo/terminfo.3

   1 .\"     $NetBSD: terminfo.3,v 1.8 2011/10/04 11:01:14 roy Exp $
   2 .\"
   3 .\" Copyright (c) 2009, 2011 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Roy Marples.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd October 4, 2011
  31 .Dt TERMINFO 3
  32 .Os
  33 .Sh NAME
  34 .Nm setupterm ,
  35 .Nm set_curterm ,
  36 .Nm del_curterm ,
  37 .Nm termname ,
  38 .Nm longname ,
  39 .Nm tigetflag ,
  40 .Nm tigetnum ,
  41 .Nm tigetstr ,
  42 .Nm tparm ,
  43 .Nm tputs ,
  44 .Nm putp
  45 .Nd terminal independent operation routines
  46 .Sh LIBRARY
  47 .Lb libterminfo
  48 .Sh SYNOPSIS
  49 .In term.h
  50 .Vt char PC ;
  51 .Vt short ospeed ;
  52 .Vt TERMINAL *cur_term ;
  53 .Ft int
  54 .Fn setupterm "const char *name" "int fildes" "int *errret"
  55 .Ft TERMINAL *
  56 .Fn set_curterm "TERMINAL *nterm"
  57 .Ft int
  58 .Fn del_curterm "TERMINAL *oterm"
  59 .Ft char *
  60 .Fn termname "void"
  61 .Ft char *
  62 .Fn longname "void"
  63 .Ft int
  64 .Fn tigetnum "const char *id"
  65 .Ft int
  66 .Fn tigetflag "const char *id"
  67 .Ft char *
  68 .Fn tigetstr "const char *id"
  69 .Ft char *
  70 .Fn tparm "const char *cm" "long p1" "long p2" "long p3" "long p4" "long p5" "long p6" "long p7" "long p8" "long p9"
  71 .Ft int
  72 .Fn tputs "const char *cp" "int affcnt" "int (*outc)(int)"
  73 .Ft int
  74 .Fn putp "const char *cp"
  75 .Ft int
  76 .Fn ti_setupterm "TERMINAL **" "const char *name" "int fildes" "int *error"
  77 .Ft int
  78 .Fn ti_getflag "const TERMINAL *" "const char *id"
  79 .Ft int
  80 .Fn ti_getnum "const TERMINAL *" "const char *id"
  81 .Ft const char *
  82 .Fn ti_getstr "const TERMINAL *" "const char *id"
  83 .Ft char *
  84 .Fn tiparm "const char *cm" "..."
  85 .Ft char *
  86 .Fn ti_tiparm "TERMINAL *" "const char *cm" "..."
  87 .Ft int
  88 .Fn ti_puts "const TERMINAL *term" "const char *str" "int affcnt" "int (*outc)(int, void *)"
  89 .Ft int
  90 .Fn ti_putp "const TERMINAL *term" "const char *str"
  91 .Sh DESCRIPTION
  92 These functions extract and use capabilities from a terminal capability
  93 database, usually
  94 .Pa /usr/share/misc/terminfo ,
  95 the format of which is described in
  96 .Xr terminfo 5 .
  97 These are low level routines;
  98 see
  99 .Xr curses 3
 100 for a higher level package.
 101 .Pp
 102 The
 103 .Fn setupterm
 104 function extracts the entry for terminal
 105 .Fa name
 106 and then calls
 107 .Fn set_curterm
 108 to set
 109 .Va cur_term
 110 to it.
 111 If
 112 .Fa name
 113 is
 114 .Dv NULL
 115 then it is replaced by the environment variable
 116 .Ev TERM .
 117 The
 118 .Fn setupterm
 119 function returns 0 on success and \-1 on error.
 120 .Va errret
 121 is set to \-1 if the
 122 .Nm terminfo
 123 database could not be opened,
 124 0 if the terminal could not be found in the database, and
 125 1 if all went well.
 126 .Pp
 127 The
 128 .Fn set_curterm
 129 function sets the variable
 130 .Va cur_term
 131 to
 132 .Va nterm
 133 and makes all of the
 134 .Nm terminfo
 135 boolean, numeric and string variables use the values from
 136 .Va nterm .
 137 The global variables
 138 .Va PC
 139 and
 140 .Va ospeed
 141 are then set.
 142 The old value of
 143 .Va cur_term
 144 is returned.
 145 The
 146 .Fn del_curterm
 147 function frees space pointed to by
 148 .Va oterm .
 149 .Pp
 150 The
 151 .Fn termname
 152 function returns the name of
 153 .Va cur_term .
 154 The
 155 .Fn longname
 156 function returns the description of
 157 .Va cur_term .
 158 .Pp
 159 The
 160 .Fn tigetflag
 161 function gets the boolean value of capability
 162 .Va id ,
 163 returning \-1 if it is not a valid capability.
 164 The
 165 .Fn tigetnum
 166 function gets the numeric value of the capability
 167 .Va id ,
 168 returning \-2 if it is not a valid capability.
 169 The
 170 .Fn tigetstr
 171 function returns the string value of the capability
 172 .Va id ,
 173 returning (char *)-1 if it is not a valid capability.
 174 .Pp
 175 The
 176 .Fn tparm
 177 function returns a string decoded from
 178 .Va cm
 179 with the parameters
 180 .Va p1
 181 \&...
 182 .Va p9
 183 applied.
 184 Some capabilities require string parameters and only platforms that can fit
 185 a
 186 .Vt char *
 187 pointer inside a
 188 .Vt long
 189 can use them.
 190 The string encoding and parameter application is described in
 191 .Xr terminfo 5 .
 192 .Pp
 193 The
 194 .Fn tputs
 195 function applies padding information to the string
 196 .Va cp ;
 197 .Va affcnt
 198 gives the number of lines affected by the operation,
 199 or 1 if this is not applicable;
 200 .Va outc
 201 is a function which is called by each character in turn.
 202 The external variable
 203 .Va ospeed
 204 controls how many padding characters are sent in relation to the terminal
 205 speed.
 206 The
 207 .Fn putp
 208 function calls tputs(str, 1, putchar).
 209 The output from
 210 .Fn putp
 211 always goes to stdout.
 212 .Ss NetBSD Extensions To Terminfo
 213 The
 214 .Fn tiparm
 215 function allows variadic parameters instead of 9 fixed longs.
 216 Numeric parameters must be integers (int) instead of longs.
 217 String parameters can be used even if the platform cannot fit a
 218 .Vt char *
 219 into a
 220 .Vt long .
 221 .Pp
 222 The
 223 .Fn ti_*
 224 functions correspond to the standard
 225 .Fn t*
 226 functions but take an additional
 227 .Ft TERMINAL *
 228 parameter so that the terminal can be specified instead of assuming
 229 .Va cur_term .
 230 These functions use private variables to the
 231 .Ft TERMINAL
 232 instead of the global variables, such as
 233 .Va PC
 234 and
 235 .Va ospeed .
 236 .Sh SEE ALSO
 237 .Xr ex 1 ,
 238 .Xr curses 3 ,
 239 .Xr terminfo 5
 240 .Sh AUTHORS
 241 .An Roy Marples Aq roy@NetBSD.org