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