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