diff options
author | Rong-En Fan <rafan@FreeBSD.org> | 2008-11-09 09:06:04 +0000 |
---|---|---|
committer | Rong-En Fan <rafan@FreeBSD.org> | 2008-11-09 09:06:04 +0000 |
commit | a388f199193767bacbb38b172ab89cb84369736c (patch) | |
tree | a1816f5667d2280b970ca44e407bac8cc4496c0a /contrib/ncurses/man/curs_terminfo.3x | |
parent | aa59d4d4c5dda7e1c6f9dc0cc6edc58992a525c7 (diff) | |
download | src-a388f199193767bacbb38b172ab89cb84369736c.tar.gz src-a388f199193767bacbb38b172ab89cb84369736c.zip |
- Flatten the vendor area
Notes
Notes:
svn path=/vendor/ncurses/dist/; revision=184786
Diffstat (limited to 'contrib/ncurses/man/curs_terminfo.3x')
-rw-r--r-- | contrib/ncurses/man/curs_terminfo.3x | 336 |
1 files changed, 0 insertions, 336 deletions
diff --git a/contrib/ncurses/man/curs_terminfo.3x b/contrib/ncurses/man/curs_terminfo.3x deleted file mode 100644 index 5af0b8fbe27c..000000000000 --- a/contrib/ncurses/man/curs_terminfo.3x +++ /dev/null @@ -1,336 +0,0 @@ -.\"*************************************************************************** -.\" Copyright (c) 1999-2006,2007 Free Software Foundation, Inc. * -.\" * -.\" Permission is hereby granted, free of charge, to any person obtaining a * -.\" copy of this software and associated documentation files (the * -.\" "Software"), to deal in the Software without restriction, including * -.\" without limitation the rights to use, copy, modify, merge, publish, * -.\" distribute, distribute with modifications, sublicense, and/or sell * -.\" copies of the Software, and to permit persons to whom the Software is * -.\" furnished to do so, subject to the following conditions: * -.\" * -.\" The above copyright notice and this permission notice shall be included * -.\" in all copies or substantial portions of the Software. * -.\" * -.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * -.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * -.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * -.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * -.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * -.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * -.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * -.\" * -.\" Except as contained in this notice, the name(s) of the above copyright * -.\" holders shall not be used in advertising or otherwise to promote the * -.\" sale, use or other dealings in this Software without prior written * -.\" authorization. * -.\"*************************************************************************** -.\" -.\" $Id: curs_terminfo.3x,v 1.28 2007/05/26 20:09:06 tom Exp $ -.TH curs_terminfo 3X "" -.ds n 5 -.na -.hy 0 -.SH NAME -\fBdel_curterm\fR, -\fBmvcur\fR, -\fBputp\fR, -\fBrestartterm\fR, -\fBset_curterm\fR, -\fBsetterm\fR, -\fBsetupterm\fR, -\fBtigetflag\fR, -\fBtigetnum\fR, -\fBtigetstr\fR, -\fBtparm\fR, -\fBtputs\fR, -\fBvid_attr\fR, -\fBvid_puts\fR, -\fBvidattr\fR, -\fBvidputs\fR - \fBcurses\fR interfaces to terminfo database -.ad -.hy -.SH SYNOPSIS -.nf -\fB#include <curses.h>\fR -.br -\fB#include <term.h>\fR -.PP -\fBint setupterm(char *\fR\fIterm\fR\fB, int \fR\fIfildes\fR\fB, int *\fR\fIerrret\fR\fB);\fR -.br -\fBint setterm(char *\fR\fIterm\fR\fB);\fR -.br -\fBTERMINAL *set_curterm(TERMINAL *\fR\fInterm\fR\fB);\fR -.br -\fBint del_curterm(TERMINAL *\fR\fIoterm\fR\fB);\fR -.br -\fBint restartterm(char *\fR\fIterm\fR\fB, int \fR\fIfildes\fR\fB, int *\fR\fIerrret\fR\fB);\fR -.br -\fBchar *tparm(char *\fR\fIstr\fR\fB, ...);\fR -.br -\fBint tputs(const char *\fR\fIstr\fR\fB, int \fR\fIaffcnt\fR\fB, int (*\fR\fIputc\fR\fB)(int));\fR -.br -\fBint putp(const char *\fR\fIstr\fR\fB);\fR -.br -\fBint vidputs(chtype \fR\fIattrs\fR\fB, int (*\fR\fIputc\fR\fB)(int));\fR -.br -\fBint vidattr(chtype \fR\fIattrs\fR\fB);\fR -.br -\fBint vid_puts(attr_t \fR\fIattrs\fR\fB, short \fR\fIpair\fR\fB, void *\fR\fIopts\fR\fB, int (*\fR\fIputc\fR\fB)(char));\fR -.br -\fBint vid_attr(attr_t \fR\fIattrs\fR\fB, short \fR\fIpair\fR\fB, void *\fR\fIopts\fR\fB);\fR -.br -\fBint mvcur(int \fR\fIoldrow\fR\fB, int \fR\fIoldcol\fR\fB, int \fR\fInewrow\fR, int \fR\fInewcol\fR\fB);\fR -.br -\fBint tigetflag(char *\fR\fIcapname\fR\fB);\fR -.br -\fBint tigetnum(char *\fR\fIcapname\fR\fB);\fR -.br -\fBchar *tigetstr(char *\fR\fIcapname\fR\fB);\fR -.br -.fi -.SH DESCRIPTION -These low-level routines must be called by programs that have to deal -directly with the \fBterminfo\fR database to handle certain terminal -capabilities, such as programming function keys. For all other -functionality, \fBcurses\fR routines are more suitable and their use is -recommended. -.PP -Initially, \fBsetupterm\fR should be called. Note that -\fBsetupterm\fR is automatically called by \fBinitscr\fR and -\fBnewterm\fR. This defines the set of terminal-dependent variables -[listed in \fBterminfo\fR(\*n)]. -The \fBterminfo\fR variables -\fBlines\fR and \fBcolumns\fR are initialized by \fBsetupterm\fR as -follows: -.RS -.PP -If \fBuse_env(FALSE)\fR has been called, values for -\fBlines\fR and \fBcolumns\fR specified in \fBterminfo\fR are used. -.PP -Otherwise, if the environment variables \fBLINES\fR and \fBCOLUMNS\fR -exist, their values are used. If these environment variables do not -exist and the program is running in a window, the current window size -is used. Otherwise, if the environment variables do not exist, the -values for \fBlines\fR and \fBcolumns\fR specified in the -\fBterminfo\fR database are used. -.RE -.PP -The header files \fBcurses.h\fR and \fBterm.h\fR should be included (in this -order) to get the definitions for these strings, numbers, and flags. -Parameterized strings should be passed through \fBtparm\fR to instantiate them. -All \fBterminfo\fR strings [including the output of \fBtparm\fR] should be printed -with \fBtputs\fR or \fBputp\fR. Call the \fBreset_shell_mode\fR to restore the -tty modes before exiting [see \fBcurs_kernel\fR(3X)]. Programs which use -cursor addressing should output \fBenter_ca_mode\fR upon startup and should -output \fBexit_ca_mode\fR before exiting. Programs desiring shell escapes -should call -.PP -\fBreset_shell_mode\fR and output \fBexit_ca_mode\fR before the shell -is called and should output \fBenter_ca_mode\fR and call -\fBreset_prog_mode\fR after returning from the shell. -.PP -The \fBsetupterm\fR routine reads in the \fBterminfo\fR database, -initializing the \fBterminfo\fR structures, but does not set up the -output virtualization structures used by \fBcurses\fR. The terminal -type is the character string \fIterm\fR; if \fIterm\fR is null, the -environment variable \fBTERM\fR is used. -All output is to file descriptor \fBfildes\fR which is initialized for output. -If \fIerrret\fR is not null, -then \fBsetupterm\fR returns \fBOK\fR or -\fBERR\fR and stores a status value in the integer pointed to by -\fIerrret\fR. -A return value of \fBOK\fR combined with status of \fB1\fR in \fIerrret\fR -is normal. -If \fBERR\fR is returned, examine \fIerrret\fR: -.RS -.TP 5 -.B 1 -means that the terminal is hardcopy, cannot be used for curses applications. -.TP 5 -.B 0 -means that the terminal could not be found, -or that it is a generic type, -having too little information for curses applications to run. -.TP 5 -.B -1 -means that the \fBterminfo\fR database could not be found. -.RE -.PP -If \fIerrret\fR is -null, \fBsetupterm\fR prints an error message upon finding an error -and exits. Thus, the simplest call is: -.sp - \fBsetupterm((char *)0, 1, (int *)0);\fR, -.sp -which uses all the defaults and sends the output to \fBstdout\fR. -.PP -The \fBsetterm\fR routine is being replaced by \fBsetupterm\fR. The call: -.sp - \fBsetupterm(\fR\fIterm\fR\fB, 1, (int *)0)\fR -.sp -provides the same functionality as \fBsetterm(\fR\fIterm\fR\fB)\fR. -The \fBsetterm\fR routine is included here for BSD compatibility, and -is not recommended for new programs. -.PP -The \fBset_curterm\fR routine sets the variable \fBcur_term\fR to -\fInterm\fR, and makes all of the \fBterminfo\fR boolean, numeric, and -string variables use the values from \fInterm\fR. It returns the old value -of \fBcur_term\fR. -.PP -The \fBdel_curterm\fR routine frees the space pointed to by -\fIoterm\fR and makes it available for further use. If \fIoterm\fR is -the same as \fBcur_term\fR, references to any of the \fBterminfo\fR -boolean, numeric, and string variables thereafter may refer to invalid -memory locations until another \fBsetupterm\fR has been called. -.PP -The \fBrestartterm\fR routine is similar to \fBsetupterm\fR and \fBinitscr\fR, -except that it is called after restoring memory to a previous state (for -example, when reloading a game saved as a core image dump). It assumes that -the windows and the input and output options are the same as when memory was -saved, but the terminal type and baud rate may be different. Accordingly, -it saves various tty state bits, calls \fBsetupterm\fP, -and then restores the bits. -.PP -The \fBtparm\fR routine instantiates the string \fIstr\fR with -parameters \fIpi\fR. A pointer is returned to the result of \fIstr\fR -with the parameters applied. -.PP -The \fBtputs\fR routine applies padding information to the string -\fIstr\fR and outputs it. The \fIstr\fR must be a terminfo string -variable or the return value from \fBtparm\fR, \fBtgetstr\fR, or -\fBtgoto\fR. \fIaffcnt\fR is the number of lines affected, or 1 if -not applicable. \fIputc\fR is a \fBputchar\fR-like routine to which -the characters are passed, one at a time. -.PP -The \fBputp\fR routine calls \fBtputs(\fR\fIstr\fR\fB, 1, putchar)\fR. -Note that the output of \fBputp\fR always goes to \fBstdout\fR, not to -the \fIfildes\fR specified in \fBsetupterm\fR. -.PP -The \fBvidputs\fR routine displays the string on the terminal in the -video attribute mode \fIattrs\fR, which is any combination of the -attributes listed in \fBcurses\fR(3X). The characters are passed to -the \fBputchar\fR-like routine \fIputc\fR. -.PP -The \fBvidattr\fR routine is like the \fBvidputs\fR routine, except -that it outputs through \fBputchar\fR. -.PP -The \fBvid_attr\fR and \fBvid_puts\fR routines correspond to vidattr and vidputs, -respectively. -They use a set of arguments for representing the video attributes plus color, -i.e., -one of type attr_t for the attributes and one of short for -the color_pair number. -The \fBvid_attr\fR and \fBvid_puts\fR routines -are designed to use the attribute constants with the \fIWA_\fR prefix. -The opts argument is reserved for future use. -Currently, applications must provide a null pointer for that argument. -.PP -The \fBmvcur\fR routine provides low-level cursor motion. It takes -effect immediately (rather than at the next refresh). -.PP -The \fBtigetflag\fR, \fBtigetnum\fR and \fBtigetstr\fR routines return -the value of the capability corresponding to the \fBterminfo\fR -\fIcapname\fR passed to them, such as \fBxenl\fR. -.PP -The \fBtigetflag\fR routine returns the value \fB-1\fR if -\fIcapname\fR is not a boolean capability, -or \fB0\fR if it is canceled or absent from the terminal description. -.PP -The \fBtigetnum\fR routine returns the value \fB-2\fR if -\fIcapname\fR is not a numeric capability, -or \fB-1\fR if it is canceled or absent from the terminal description. -.PP -The \fBtigetstr\fR routine returns the value \fB(char *)-1\fR -if \fIcapname\fR is not a string capability, -or \fB0\fR if it is canceled or absent from the terminal description. -.PP -The \fIcapname\fR for each capability is given in the table column entitled -\fIcapname\fR code in the capabilities section of \fBterminfo\fR(\*n). -.sp -.RS -\fBchar *boolnames[]\fR, \fB*boolcodes[]\fR, \fB*boolfnames[]\fR -.sp -\fBchar *numnames[]\fR, \fB*numcodes[]\fR, \fB*numfnames[]\fR -.sp -\fBchar *strnames[]\fR, \fB*strcodes[]\fR, \fB*strfnames[]\fR -.RE -.PP -These null-terminated arrays contain the \fIcapnames\fR, the -\fBtermcap\fR codes, and the full C names, for each of the -\fBterminfo\fR variables. -.SH RETURN VALUE -Routines that return an integer return \fBERR\fR upon failure and \fBOK\fR -(SVr4 only specifies "an integer value other than \fBERR\fR") upon successful -completion, unless otherwise noted in the preceding routine descriptions. -.PP -Routines that return pointers always return \fBNULL\fR on error. -.PP -X/Open defines no error conditions. -In this implementation -.RS -.TP 5 -\fBdel_curterm\fP -returns an error -if its terminal parameter is null. -.TP 5 -\fBrestartterm\fP -returns an error -if the associated call to \fBsetupterm\fP returns an error. -.TP 5 -\fBsetupterm\fP -returns an error -if it cannot allocate enough memory, or -create the initial windows (stdscr, curscr, newscr). -Other error conditions are documented above. -.RE -.SH NOTES -The \fBsetupterm\fR routine should be used in place of \fBsetterm\fR. -It may be useful when you want to test for terminal capabilities without -committing to the allocation of storage involved in \fBinitscr\fR. -.PP -Note that \fBvidattr\fR and \fBvidputs\fR may be macros. -.SH PORTABILITY -The function \fBsetterm\fR is not described in the XSI Curses standard and must -be considered non-portable. All other functions are as described in the XSI -curses standard. -.PP -\fBsetupterm\fP copies the terminal name to the array \fBttytype\fP. -This is not part of X/Open Curses, but is assumed by some applications. -.PP -In System V Release 4, \fBset_curterm\fR has an \fBint\fR return type and -returns \fBOK\fR or \fBERR\fR. We have chosen to implement the XSI Curses -semantics. -.PP -In System V Release 4, the third argument of \fBtputs\fR has the type -\fBint (*putc)(char)\fR. -.PP -The XSI Curses standard prototypes \fBtparm\fR with a fixed number of parameters, -rather than a variable argument list. -This implementation uses a variable argument list. -Portable applications should provide 9 parameters after the format; -zeroes are fine for this purpose. -.PP -XSI notes that after calling \fBmvcur\fR, the curses state may not match the -actual terminal state, and that an application should touch and refresh -the window before resuming normal curses calls. -Both ncurses and System V Release 4 curses implement \fBmvcur\fR using -the SCREEN data allocated in either \fBinitscr\fR or \fBnewterm\fR. -So though it is documented as a terminfo function, -\fBmvcur\fR is really a curses function which is not well specified. -.PP -XSI states that the old location must be given for \fBmvcur\fP. -This implementation allows the caller to use -1's for the old ordinates. -In that case, the old location is unknown. -.PP -Extended terminal capability names, e.g., as defined by \fBtic\ -x\fP, -are not stored in the arrays described in this section. -.SH SEE ALSO -\fBcurses\fR(3X), \fBcurs_initscr\fR(3X), \fBcurs_kernel\fR(3X), \fBcurs_termcap\fR(3X), -\fBputc\fR(3), \fBterminfo\fR(\*n) -.\"# -.\"# The following sets edit modes for GNU EMACS -.\"# Local Variables: -.\"# mode:nroff -.\"# fill-column:79 -.\"# End: |