ncurses 4.1
[ncurses.git] / man / curs_terminfo.3x
1 .\" $Id: curs_terminfo.3x,v 1.6 1996/06/15 22:45:50 tom Exp $
2 .TH curs_terminfo 3X ""
3 .ds n 5
4 .SH NAME
5 \fBsetupterm\fR, \fBsetterm\fR,
6 \fBset_curterm\fR, \fBdel_curterm\fR, \fBrestartterm\fR, \fBtparm\fR,
7 \fBtputs\fR, \fBputp\fR, \fBvidputs\fR, \fBvidattr\fR, \fBmvcur\fR,
8 \fBtigetflag\fR, \fBtigetnum\fR, \fBtigetstr\fR - \fBcurses\fR
9 interfaces to terminfo database
10 .SH SYNOPSIS
11 \fB#include <curses.h>\fR
12 .br
13 \fB#include <term.h>\fR
14
15 \fBint setupterm(const char *term, int fildes, int *errret);\fR
16 .br
17 \fBint setterm(const char *term);\fR
18 .br
19 \fBTERMINAL *set_curterm(TERMINAL *nterm);\fR
20 .br
21 \fBint del_curterm(TERMINAL *oterm);\fR
22 .br
23 \fBint restartterm(const char *term, int fildes, int *errret);\fR
24 .br
25 \fBchar *tparm(const char *str, ...);\fR
26 .br
27 \fBchar *tparam(const char *str, char *buffer, int size, ...);\fR
28 .br
29 \fBint tputs(const char *str, int affcnt, int (*putc)(int));\fR
30 .br
31 \fBint putp(const char *str);\fR
32 .br
33 \fBint vidputs(chtype attrs, int (*putc)(char));\fR
34 .br
35 \fBint vidattr(chtype attrs);\fR
36 .br
37 \fBint mvcur(int oldrow, int oldcol, int newrow, int newcol);\fR
38 .br
39 \fBint tigetflag(const char *capname);\fR
40 .br
41 \fBint tigetnum(const char *capname);\fR
42 .br
43 \fBchar *tigetstr(const char *capname);\fR
44 .br
45 .SH DESCRIPTION
46 These low-level routines must be called by programs that have to deal
47 directly with the \fBterminfo\fR database to handle certain terminal
48 capabilities, such as programming function keys.  For all other
49 functionality, \fBcurses\fR routines are more suitable and their use is
50 recommended.
51
52 Initially, \fBsetupterm\fR should be called.  Note that
53 \fBsetupterm\fR is automatically called by \fBinitscr\fR and
54 \fBnewterm\fR.  This defines the set of terminal-dependent variables
55 [listed in \fBterminfo\fR(\*n)].  The \fBterminfo\fR variables
56 \fBlines\fR and \fBcolumns\fR are initialized by \fBsetupterm\fR as
57 follows: If \fBuse_env(FALSE)\fR has been called, values for
58 \fBlines\fR and \fBcolumns\fR specified in \fBterminfo\fR are used.
59 Otherwise, if the environment variables \fBLINES\fR and \fBCOLUMNS\fR
60 exist, their values are used.  If these environment variables do not
61 exist and the program is running in a window, the current window size
62 is used.  Otherwise, if the environment variables do not exist, the
63 values for \fBlines\fR and \fBcolumns\fR specified in the
64 \fBterminfo\fR database are used.
65
66 The header files \fBcurses.h\fR and \fBterm.h\fR should be included (in this
67 order) to get the definitions for these strings, numbers, and flags.
68 Parameterized strings should be passed through \fBtparm\fR to instantiate them.  
69 All \fBterminfo\fR strings [including the output of \fBtparm\fR] should be printed
70 with \fBtputs\fR or \fBputp\fR.  Call the \fBreset_shell_mode\fR to restore the
71 tty modes before exiting [see \fBcurs_kernel\fR(3X)].  Programs which use
72 cursor addressing should output \fBenter_ca_mode\fR upon startup and should
73 output \fBexit_ca_mode\fR before exiting.  Programs desiring shell escapes
74 should call
75
76 \fBreset_shell_mode\fR and output \fBexit_ca_mode\fR before the shell
77 is called and should output \fBenter_ca_mode\fR and call
78 \fBreset_prog_mode\fR after returning from the shell.
79
80 The \fBsetupterm\fR routine reads in the \fBterminfo\fR database,
81 initializing the \fBterminfo\fR structures, but does not set up the
82 output virtualization structures used by \fBcurses\fR.  The terminal
83 type is the character string \fIterm\fR; if \fIterm\fR is null, the
84 environment variable \fBTERM\fR is used.  All output is to file
85 descriptor \fBfildes\fR which is initialized for output.  If
86 \fIerrret\fR is not null, then \fBsetupterm\fR returns \fBOK\fR or
87 \fBERR\fR and stores a status value in the integer pointed to by
88 \fIerrret\fR.  A status of \fB1\fR in \fIerrret\fR is normal, \fB0\fR
89 means that the terminal could not be found, and \fB-1\fR means that
90 the \fBterminfo\fR database could not be found.  If \fIerrret\fR is
91 null, \fBsetupterm\fR prints an error message upon finding an error
92 and exits.  Thus, the simplest call is:
93
94       \fBsetupterm((char *)0, 1, (int *)0);\fR,
95
96 which uses all the defaults and sends the output to \fBstdout\fR.
97
98 The \fBsetterm\fR routine is being replaced by \fBsetupterm\fR.  The call:
99
100       \fBsetupterm(\fR\fIterm\fR\fB, 1, (int *)0)\fR
101
102 provides the same functionality as \fBsetterm(\fR\fIterm\fR\fB)\fR.
103 The \fBsetterm\fR routine is included here for BSD compatibility, and
104 is not recommended for new programs.
105
106 The \fBset_curterm\fR routine sets the variable \fBcur_term\fR to
107 \fInterm\fR, and makes all of the \fBterminfo\fR boolean, numeric, and
108 string variables use the values from \fInterm\fR.  It returns the old value
109 of \fBcur_term\fR.
110
111 The \fBdel_curterm\fR routine frees the space pointed to by
112 \fIoterm\fR and makes it available for further use.  If \fIoterm\fR is
113 the same as \fBcur_term\fR, references to any of the \fBterminfo\fR
114 boolean, numeric, and string variables thereafter may refer to invalid
115 memory locations until another \fBsetupterm\fR has been called.
116
117 The \fBrestartterm\fR routine is similar to \fBsetupterm\fR and \fBinitscr\fR,
118 except that it is called after restoring memory to a previous state (for
119 example, when reloading a game saved as a core image dump).  It assumes that
120 the windows and the input and output options are the same as when memory was
121 saved, but the terminal type and baud rate may be different.  Accordingly,
122 it saves various tty state bits, does a setupterm, and then restores the bits.
123
124 The \fBtparm\fR routine instantiates the string \fIstr\fR with
125 parameters \fIpi\fR.  A pointer is returned to the result of \fIstr\fR
126 with the parameters applied.
127
128 The \fBtparam\fR routine is included for compatibility with the GNU termcap
129 implementation.  It works like \fBtparm\fR but you specify a buffer and buffer
130 size to be filled with the expanded string.
131
132 The \fBtputs\fR routine applies padding information to the string
133 \fIstr\fR and outputs it.  The \fIstr\fR must be a terminfo string
134 variable or the return value from \fBtparm\fR, \fBtgetstr\fR, or
135 \fBtgoto\fR.  \fIaffcnt\fR is the number of lines affected, or 1 if
136 not applicable.  \fIputc\fR is a \fBputchar\fR-like routine to which
137 the characters are passed, one at a time.
138
139 The \fBputp\fR routine calls \fBtputs(\fR\fIstr\fR\fB, 1, putchar)\fR.
140 Note that the output of \fBputp\fR always goes to \fBstdout\fR, not to
141 the \fIfildes\fR specified in \fBsetupterm\fR.
142
143 The \fBvidputs\fR routine displays the string on the terminal in the
144 video attribute mode \fIattrs\fR, which is any combination of the
145 attributes listed in \fBcurses\fR(3X).  The characters are passed to
146 the \fBputchar\fR-like routine \fIputc\fR.
147
148 The \fBvidattr\fR routine is like the \fBvidputs\fR routine, except
149 that it outputs through \fBputchar\fR.
150
151 The \fBmvcur\fR routine provides low-level cursor motion.  It takes
152 effect immediately (rather than at the next refresh).
153
154 The \fBtigetflag\fR, \fBtigetnum\fR and \fBtigetstr\fR routines return
155 the value of the capability corresponding to the \fBterminfo\fR
156 \fIcapname\fR passed to them, such as \fBxenl\fR.
157
158 The \fBtigetflag\fR routine returns the value \fB-1\fR if
159 \fIcapname\fR is not a boolean capability.
160
161 The \fBtigetnum\fR routine returns the value \fB-2\fR if
162 \fIcapname\fR is not a numeric capability.
163
164 The \fBtigetstr\fR routine returns the value \fB(char *)-1\fR
165 if \fIcapname\fR is not a string capability.
166
167 The \fIcapname\fR for each capability is given in the table column entitled
168 \fIcapname\fR code in the capabilities section of \fBterminfo\fR(\*n).
169
170 \fBchar *boolnames\fR, \fB*boolcodes\fR, \fB*boolfnames\fR
171
172 \fBchar *numnames\fR, \fB*numcodes\fR, \fB*numfnames\fR
173
174 \fBchar *strnames\fR, \fB*strcodes\fR, \fB*strfnames\fR
175
176 These null-terminated arrays contain the \fIcapnames\fR, the
177 \fBtermcap\fR codes, and the full C names, for each of the
178 \fBterminfo\fR variables.
179 .SH RETURN VALUE
180 Routines that return an integer return \fBERR\fR upon failure and \fBOK\fR
181 (SVr4 only specifies "an integer value other than \fBERR\fR") upon successful
182 completion, unless otherwise noted in the preceding routine descriptions.
183
184 Routines that return pointers always return \fBNULL\fR on error.
185 .SH NOTES
186 The \fBsetupterm\fR routine should be used in place of \fBsetterm\fR.
187 It may be useful when you want to test for terminal capabilities without
188 committing to the allocation of storage involved in \fBinitscr\fR.
189
190 Note that \fBvidattr\fR and \fBvidputs\fR may be macros.
191 .SH PORTABILITY
192 The function \fBsetterm\fR is not described in the XSI Curses standard and must
193 be considered non-portable.  All other functions are as described in the XSI
194 curses standard.
195
196 In System V Release 4, \fBset_curterm\fR has an \fBint\fR return type and
197 returns \fBOK\fR or \fBERR\fR.  We have chosen to implement the XSI Curses
198 semantics.
199
200 In System V Release 4, the third argument of \fBtputs\fR has the type
201 \fBint (*putc)(char)\fR.
202
203 The XSI Curses standard prototypes \fBtparm\fR with a fixed number of parameters,
204 rather than a variable argument list.
205 .SH SEE ALSO
206 \fBcurses\fR(3X), \fBcurs_initscr\fR(3X), \fBcurs_kernel\fR(3X), \fBcurs_termcap\fR(3X),
207 \fBputc\fR(3S), \fBterminfo\fR(\*n)
208 .\"#
209 .\"# The following sets edit modes for GNU EMACS
210 .\"# Local Variables:
211 .\"# mode:nroff
212 .\"# fill-column:79
213 .\"# End: