lib/libterminfo/terminfo.3

   1 .\"     $NetBSD: terminfo.3,v 1.11 2013/07/20 21:39:56 wiz 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 January 25, 2013
  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 For platforms which don't support this,
 191 .Dv NULL
 192 is returned and
 193 .Va errno
 194 is set to
 195 .Er ENOTSUPP .
 196 The string encoding and parameter application is described in
 197 .Xr terminfo 5 .
 198 .Pp
 199 The
 200 .Fn tputs
 201 function applies padding information to the string
 202 .Va cp ;
 203 .Va affcnt
 204 gives the number of lines affected by the operation,
 205 or 1 if this is not applicable;
 206 .Va outc
 207 is a function which is called by each character in turn.
 208 The external variable
 209 .Va ospeed
 210 controls how many padding characters are sent in relation to the terminal
 211 speed.
 212 The
 213 .Fn putp
 214 function calls tputs(str, 1, putchar).
 215 The output from
 216 .Fn putp
 217 always goes to stdout.
 218 .Ss NetBSD Extensions To Terminfo
 219 The
 220 .Fn tiparm
 221 function allows variadic parameters instead of 9 fixed longs.
 222 Numeric parameters must be passed as
 223 .Vt int .
 224 String parameters must be passed as
 225 .Vt char *
 226 and works on all platforms, unlike
 227 .Fn tparm .
 228 .Pp
 229 The
 230 .Fn ti_*
 231 functions correspond to the standard
 232 .Fn t*
 233 functions but take an additional
 234 .Ft TERMINAL *
 235 parameter so that the terminal can be specified instead of assuming
 236 .Va cur_term .
 237 These functions use private variables to the
 238 .Ft TERMINAL
 239 instead of the global variables, such as
 240 .Va PC
 241 and
 242 .Va ospeed .
 243 .Sh SEE ALSO
 244 .Xr ex 1 ,
 245 .Xr curses 3 ,
 246 .Xr terminfo 5
 247 .Sh AUTHORS
 248 .An Roy Marples Aq Mt roy@NetBSD.org