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