lib/libterminfo/terminfo.3

   1 .\"     $NetBSD: terminfo.3,v 1.4 2010/02/04 09:12:56 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2009 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 December 7, 2009
  31 .Dt TERMINFO 3
  32 .Os
  33 .Sh NAME
  34 .Nm setupterm ,
  35 .Nm set_curterm ,
  36 .Nm del_curterm ,
  37 .Nm tigetflag ,
  38 .Nm tigetnum ,
  39 .Nm tigetstr ,
  40 .Nm tparm ,
  41 .Nm tputs ,
  42 .Nm putp
  43 .Nd terminal independent operation routines
  44 .Sh LIBRARY
  45 .Lb libterminfo
  46 .Sh SYNOPSIS
  47 .In term.h
  48 .Vt char PC ;
  49 .Vt short ospeed ;
  50 .Vt TERMINAL *cur_term ;
  51 .Ft int
  52 .Fn setupterm "const char *name" "int fildes" "int *errret"
  53 .Ft TERMINAL *
  54 .Fn set_curterm "TERMINAL *term"
  55 .Ft int
  56 .Fn del_curterm "TERMINAL *term"
  57 .Ft int
  58 .Fn tigetnum "const char *id"
  59 .Ft int
  60 .Fn tigetflag "const char *id"
  61 .Ft char *
  62 .Fn tigetstr "const char *id"
  63 .Ft char *
  64 .Fn tparm "const char *cm" "long p1" "long p2" "long p3" "long p4" "long p5" "long p6" "long p7" "long p8" "long p9"
  65 .Ft int
  66 .Fn tputs "const char *cp" "int affcnt" "int (*outc)(int)"
  67 .Ft int
  68 .Fn putp "const char *cp"
  69 .Ft int
  70 .Fn ti_setupterm "TERMINAL **" "const char *name" "int fildes" "int *error"
  71 .Ft int
  72 .Fn ti_getflag "const TERMINAL *" "const char *id"
  73 .Ft int
  74 .Fn ti_getnum "const TERMINAL *" "const char *id"
  75 .Ft const char *
  76 .Fn ti_getstr "const TERMINAL *" "const char *id"
  77 .Ft char *
  78 .Fn t_parm "const TERMINAL *" "const char *cm" "long p1" "long p2" "long p3" "long p4" "long p5" "long p6" "long p7" "long p8" "long p9"
  79 .Ft char *
  80 .Fn t_parm "const char *cm" "..."
  81 .Ft char *
  82 .Fn t_vparm "TERMINAL *" "const char *cm" "..."
  83 .Ft int
  84 .Fn ti_puts "const TERMINAL *term" "const char *str" "int affcnt" "int (*outc)(int, void *)"
  85 .Ft int
  86 .Fn ti_putp "const TERMINAL *term" "const char *str"
  87 .Sh DESCRIPTION
  88 These functions extract and use capabilities from a terminal capability
  89 database, usually
  90 .Pa /usr/share/misc/terminfo ,
  91 the format of which is described in
  92 .Xr terminfo 5 .
  93 These are low level routines;
  94 see
  95 .Xr curses 3
  96 for a higher level package.
  97 .Pp
  98 The
  99 .Fn setupterm
 100 function extracts the entry for terminal
 101 .Fa name
 102 and then calls
 103 .Fn set_curterm
 104 to set
 105 .Va cur_term
 106 to it.
 107 If
 108 .Fa name
 109 is
 110 .Dv NULL
 111 then it is replaced by the environment variable
 112 .Ev TERM .
 113 The
 114 .Fn setupterm
 115 function returns 0 on success and \-1 on error.
 116 .Va errret
 117 is set to \-1 if the
 118 .Nm terminfo
 119 database could not be opened,
 120 0 if the terminal could not be found in the database, and
 121 1 if all went well.
 122 .Pp
 123 The
 124 .Fn set_curterm
 125 function sets the variable
 126 .Va cur_term
 127 to
 128 .Va nterm
 129 and makes all of the
 130 .Nm terminfo
 131 boolean, numeric and string variables use the values from
 132 .Va nterm .
 133 The global variables
 134 .Va PC
 135 and
 136 .Va ospeed
 137 are then set.
 138 The old value of
 139 .Va cur_term
 140 is returned.
 141 The
 142 .Fn del_curterm
 143 function frees space pointed to by
 144 .Va oterm .
 145 .Pp
 146 The
 147 .Fn tigetflag
 148 function gets the boolean value of capability
 149 .Va id ,
 150 returning \-1 if it is not a valid capability.
 151 The
 152 .Fn tigetnum
 153 function gets the numeric value of the capability
 154 .Va id ,
 155 returning \-2 if it is not a valid capability.
 156 The
 157 .Fn tigetstr
 158 function returns the string value of the capability
 159 .Va id ,
 160 returning (char *)-1 if it is not a valid capability.
 161 .Pp
 162 The
 163 .Fn tparm
 164 function returns a string decoded from
 165 .Va cm
 166 with the parameters
 167 .Va p1
 168 \&...
 169 .Va p9
 170 applied.
 171 Some capabilities require string parameters and only platforms that can fit
 172 a
 173 .Vt char *
 174 pointer inside a
 175 .Vt long
 176 can use them.
 177 The string encoding and parameter application is described in
 178 .Xr terminfo 5 .
 179 .Pp
 180 The
 181 .Fn tputs
 182 function applies padding information to the string
 183 .Va cp ;
 184 .Va affcnt
 185 gives the number of lines affected by the operation,
 186 or 1 if this is not applicable;
 187 .Va outc
 188 is a function which is called by each character in turn.
 189 The external variable
 190 .Va ospeed
 191 controls how many padding characters are sent in relation to the terminal
 192 speed.
 193 The
 194 .Fn putp
 195 function calls tputs(str, 1, putchar).
 196 The output from
 197 .Fn putp
 198 always goes to stdout.
 199 .Ss NetBSD Extensions To Terminfo
 200 The
 201 .Fn vtparm
 202 function allows variadic parameters instead of 9 fixed longs.
 203 Numeric parameters must be longs.
 204 String parameters can be used even if the platform cannot fit a
 205 .Vt char *
 206 into a
 207 .Vt long .
 208 .Pp
 209 The
 210 .Fn ti_*
 211 functions correspond to the standard
 212 .Fn t*
 213 functions but take an additional
 214 .Ft TERMINAL *
 215 parameter so that the terminal can be specified instead of assuming
 216 .Va cur_term .
 217 These functions use private variables to the
 218 .Ft TERMINAL
 219 instead of the global variables, such as
 220 .Va PC
 221 and
 222 .Va ospeed .
 223 .Sh SEE ALSO
 224 .Xr ex 1 ,
 225 .Xr curses 3 ,
 226 .Xr terminfo 5
 227 .Sh AUTHORS
 228 .An Roy Marples Aq roy@NetBSD.org