1.\" $NetBSD: terminfo.3,v 1.12 2014/03/18 18:20:38 riastradh 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 92These functions extract and use capabilities from a terminal capability 93database, usually 94.Pa /usr/share/misc/terminfo , 95the format of which is described in 96.Xr terminfo 5 . 97These are low level routines; 98see 99.Xr curses 3 100for a higher level package. 101.Pp 102The 103.Fn setupterm 104function extracts the entry for terminal 105.Fa name 106and then calls 107.Fn set_curterm 108to set 109.Va cur_term 110to it. 111If 112.Fa name 113is 114.Dv NULL 115then it is replaced by the environment variable 116.Ev TERM . 117The 118.Fn setupterm 119function returns 0 on success and \-1 on error. 120.Va errret 121is set to \-1 if the 122.Nm terminfo 123database could not be opened, 1240 if the terminal could not be found in the database, and 1251 if all went well. 126.Pp 127The 128.Fn set_curterm 129function sets the variable 130.Va cur_term 131to 132.Va nterm 133and makes all of the 134.Nm terminfo 135boolean, numeric and string variables use the values from 136.Va nterm . 137The global variables 138.Va PC 139and 140.Va ospeed 141are then set. 142The old value of 143.Va cur_term 144is returned. 145The 146.Fn del_curterm 147function frees space pointed to by 148.Va oterm . 149.Pp 150The 151.Fn termname 152function returns the name of 153.Va cur_term . 154The 155.Fn longname 156function returns the description of 157.Va cur_term . 158.Pp 159The 160.Fn tigetflag 161function gets the boolean value of capability 162.Va id , 163returning \-1 if it is not a valid capability. 164The 165.Fn tigetnum 166function gets the numeric value of the capability 167.Va id , 168returning \-2 if it is not a valid capability. 169The 170.Fn tigetstr 171function returns the string value of the capability 172.Va id , 173returning (char *)-1 if it is not a valid capability. 174.Pp 175The 176.Fn tparm 177function returns a string decoded from 178.Va cm 179with the parameters 180.Va p1 181\&... 182.Va p9 183applied. 184Some capabilities require string parameters and only platforms that can fit 185a 186.Vt char * 187pointer inside a 188.Vt long 189can use them. 190For platforms which don't support this, 191.Dv NULL 192is returned and 193.Va errno 194is set to 195.Er ENOTSUPP . 196The string encoding and parameter application is described in 197.Xr terminfo 5 . 198.Pp 199The 200.Fn tputs 201function applies padding information to the string 202.Va cp ; 203.Va affcnt 204gives the number of lines affected by the operation, 205or 1 if this is not applicable; 206.Va outc 207is a function which is called by each character in turn. 208The external variable 209.Va ospeed 210controls how many padding characters are sent in relation to the terminal 211speed. 212The 213.Fn putp 214function calls tputs(str, 1, putchar). 215The output from 216.Fn putp 217always goes to stdout. 218.Ss NetBSD Extensions To Terminfo 219The 220.Fn tiparm 221function allows variadic parameters instead of 9 fixed longs. 222Numeric parameters must be passed as 223.Vt int . 224String parameters must be passed as 225.Vt char * 226and works on all platforms, unlike 227.Fn tparm . 228.Pp 229The 230.Fn ti_* 231functions correspond to the standard 232.Fn t* 233functions but take an additional 234.Ft TERMINAL * 235parameter so that the terminal can be specified instead of assuming 236.Va cur_term . 237These functions use private variables to the 238.Ft TERMINAL 239instead of the global variables, such as 240.Va PC 241and 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 249