# IBM_PROLOG_BEGIN_TAG # This is an automatically generated prolog. # # bos420 src/bos/usr/lpp/bos/README.SPEC1170 # # Licensed Materials - Property of IBM # # (C) COPYRIGHT International Business Machines Corp. 1996 # All Rights Reserved # # US Government Users Restricted Rights - Use, duplication or # disclosure restricted by GSA ADP Schedule Contract with IBM Corp. # # IBM_PROLOG_END_TAG IBM AIX VERSION 4.2 CURSES PROGRAMMING REFERENCE Contents Chapter 1 Introduction Chapter 2 Use and Implementation of Interfaces Chapter 3 Interface Overview 3.1 Components 3.2 Screens, Windows and Terminals 3.3 Characters 3.3.1 Character Storage Size 3.3.2 Multi-column Characters 3.3.3 Attributes 3.3.4 Rendition 3.3.5 Non-spacing Characters 3.3.6 Window Properties 3.4 Conceptual Operations 3.4.1 Screen Addressing 3.4.2 Basic Character Operations 3.4.3 Special Characters 3.4.4 Rendition of Characters Placed into a Window 3.5 Input Processing 3.5.1 Keypad Processing 3.5.2 Input Mode 3.5.3 Delay Mode 3.5.4 Echo Processing 3.6 The Set of Curses Functions 3.6.1 Function Name Conventions 3.6.2 Function Families Provided 3.7 Interfaces Implemented as Macros 3.8 Initialised Curses Environment 3.9 Synchronous and Networked Asynchronous Terminals Chapter 4 Curses Interfaces addch() addchstr() addnstr() addnwstr() add_wch() add_wchnstr() attroff() attr_get() baudrate() beep() bkgd() bkgrnd() border() border_set() box() box_set() can_change_color() cbreak() chgat() clear() clearok() clrtobot() clrtoeol() color_content() COLOR_PAIRS COLS copywin() curscr curs_set() cur_term def_prog_mode() delay_output() delch() del_curterm() deleteln() delscreen() delwin() derwin() doupdate() dupwin() echo() echochar() echo_wchar() endwin() erase() erasechar() filter() flash() flushinp() getbegyx() getbkgd() getbkgrnd() getcchar() getch() getmaxyx() getnstr() getn_wstr() getparyx() getstr() get_wch() getwin() get_wstr() getyx() halfdelay() has_colors() has_ic() hline() hline_set() idcok() idlok() immedok() inch() inchnstr() init_color() initscr() innstr() innwstr() insch() insdelln() insertln() insnstr() ins_nwstr() insstr() instr() ins_wch() ins_wstr() intrflush() in_wch() in_wchnstr() inwstr() isendwin() is_linetouched() keyname() keypad() killchar() leaveok() LINES longname() meta() move() mv mvcur() mvderwin() mvprintw() mvscanw() mvwin() napms() newpad() newterm() newwin() nl() no nodelay() noqiflush() notimeout() overlay() pair_content() pechochar() pnoutrefresh() printw() putp() putwin() qiflush() raw() redrawwin() refresh() reset_prog_mode() resetty() restartterm() ripoffline() savetty() scanw() scr_dump() scrl() scrollok() setcchar() set_curterm() setscrreg() set_term() setupterm() slk_attroff() standend() start_color() stdscr subpad() subwin() syncok() termattrs() termname() tgetent() tigetflag() timeout() touchline() tparm() tputs() typeahead() unctrl() ungetch() untouchwin() use_env() vidattr() vline() vline_set() vwprintw() vw_printw() vwscanw() vw_scanw() w wunctrl() Chapter 5 Headers Chapter 6 Terminfo Source Format (ENHANCED CURSES) 6.1 Source File Syntax 6.1.1 Minimum Guaranteed Limits 6.1.2 Formal Grammar 6.1.3 Defined Capabilities 6.1.4 Sample Entry 6.1.5 Types of Capabilities in the Sample Entry 6.2 Device Capabilities 6.2.1 Basic Capabilities 6.2.2 Parameterised Strings 6.2.3 Cursor Motions 6.2.4 Area Clears 6.2.5 Insert/Delete Line 6.2.6 Insert/Delete Character 6.2.7 Highlighting, Underlining, and Visible Bells 6.2.8 Keypad 6.2.9 Tabs and Initialisation 6.2.10 Delays 6.2.11 Status Lines 6.2.12 Line Graphics 6.2.13 Colour Manipulation 6.2.14 Miscellaneous 6.2.15 Special Cases 6.2.16 Similar Terminals 6.3 Printer Capabilities 6.3.1 Rounding Values 6.3.2 Printer Resolution 6.3.3 Specifying Printer Resolution 6.3.4 Capabilities that Cause Movement 6.3.5 Alternate Character Sets 6.3.6 Dot-Matrix Graphics 6.3.7 Effect of Changing Printing Resolution 6.3.8 Print Quality 6.3.9 Printing Rate and Buffer Size 6.4 Selecting a Terminal 6.5 Application Usage 6.5.1 Conventions for Device Aliases 6.5.2 Variations of Terminal Definitions Glossary Index This Document o Chapter 1 introduces Curses, gives an overview of enhancements that have been made to this version and lists specific interfaces marked TO BE WITHDRAWN. o Chapter 2 describes the relationship between Curses and the C language, the compilation environment, and the operating system requirements. It also defines the effect of the interface on the name space for identifiers and introduces the major data types that the interfaces use. o Chapter 3 gives an overview of Curses. It discusses the use of some of the key data types and gives general rules for important common concepts such as characters, renditions and window properties. It contains general rules for the common Curses operations and operating modes. This information is implicitly referenced by the interface definitions in Chapter 4. The chapter explains the system of naming the Curses functions and presents a table of function families. Finally, the chapter contains notes regarding use of macros and restrictions on block-mode terminals. o Chapter 4 defines the Curses functional interfaces. o Chapter 5 defines the contents of headers which declare constants, macros and data structures that are needed by programs using the services provided by Chapter 4. o Chapter 6 discusses the terminfo database, which Curses uses to describe terminals. The chapter specifies the source format of a terminfo entry, using a formal grammar, an informal discussion, and an example. Boolean, numeric and string capabilities are presented in tabular form. The remainder of the chapter discusses the use of these capabilities by the writer of a terminfo entry to describe the characteristics of the terminal in use. The chapters are followed by a glossary, which contains normative definitions of terms used in the document. Comprehensive references are available in the index. Chapter 1 New Features Internationalisation This version of the Curses specification has been enhanced to support a wide range of internationalised capabilities. Traditional single-byte character operations are preserved, and multi-byte and wide- character interfaces are included to allow use of the Curses features with a wide range of character code sets. Writing Direction The references to writing direction have been generalised to permit both right-to-left and left-to- right writing. Wide and Non-Spacing Characters New interfaces are introduced for use with wide characters and wide character strings. The traditional single-byte character string interfaces have been made more general for use with multi-byte character strings. The traditional chtype interfaces note that they are usable only in restricted environments and do not support extensible attributes. A new, extensible attribute model has been provided for wide-character interfaces. The display model has been generalised to support both multi-column characters and non-spacing characters. The concept of a complex character is introduced. Some of the interfaces and headers in this issue are marked TO BE WITHDRAWN. Various factors may have contributed to the decision to withdraw an interface. In all cases, the reasons for withdrawal of an interface are documented on the relevant pages. If a migration path exists, advice is given to application developers regarding alternative means of obtaining similar functionality. This information may be found in the APPLICATION USAGE sections on the relevant pages in Chapter 4. Interfaces marked TO BE WITHDRAWN shall still exist on conformant implementations. However, they will be marked WITHDRAWN in a future issue of this document. Interfaces marked WITHDRAWN may still exist on conformant implementations. Application writers should not use functionality marked TO BE WITHDRAWN. The following interfaces are marked TO BE WITHDRAWN in this document: Headers and Interfaces To Be Withdrawn tgetent() tgetnum() tgoto() vwscanw() tgetflag() tgetstr() vwprintw() Chapter 2 Use and Implementation of Interfaces Each of the following statements applies unless explicitly stated otherwise in the detailed descriptions that follow. If an argument to a function has an invalid value (such as a value outside the domain of the function, or a pointer outside the address space of the program, or a null pointer), the behaviour is undefined. Any function declared in a header may also be implemented as a macro defined in the header, so a library function should not be declared explicitly if its header is included. Any macro definition of a function can be suppressed locally by enclosing the name of the function in parentheses, because the name is then not followed by the left parenthesis that indicates expansion of a macro function name. For the same syntactic reason, it is permitted to take the address of a library function even if it is also defined as a macro. The use of the C-language #undef construct to remove any such macro definition will also ensure that an actual function is referred to. Any invocation of a library function that is implemented as a macro will expand to code that evaluates each of its arguments exactly once, fully protected by parentheses where necessary, so it is generally safe to use arbitrary expressions as arguments. Likewise, those function-like macros described in the following sections may be invoked in an expression anywhere a function with a compatible return type could be called. Provided that a library function can be declared without reference to any type defined in a header, it is also permissible to declare the function, either explicitly or implicitly, and use it without including its associated header. If a function that accepts a variable number of arguments is not declared (explicitly or by including its associated header), the behaviour is undefined. C Language Definition Use and Implementation of Interfaces 2.1 C Language Definition The C language that is the basis for the synopses and code examples in this document is ISO C, as specified in the referenced ISO C standard. Common Usage C, which refers to the C language before standardisation, was the basis for previous editions of this specification. 2.2 The Compilation Environment The following interfaces with arguments must be implemented as macros. The relevance to the application programmer is that the `&' character cannot be used before the arguments. Macros Chapter 4 Entry COLOR_PAIR(), PAIR_NUMBER() can_change_color() getbegyx(), getmaxyx(), getparyx(), getyx() getbegyx() The descriptions of headers in Chapter 5 list other macros, like COLOR_BLACK, that do not take arguments. Chapter 3 Interface Overview 3.1 Components A Curses initialisation function, usually initscr(), determines the terminal model in use, by reference to either an argument or an environment variable. If that model is defined in terminfo, then the same terminfo entry tells Curses exactly how to operate the terminal. In this case, a comprehensive API lets the application perform terminal operations. The Curses run-time system receives each terminal request and sends appropriate commands to the terminal to achieve the desired effect. There is no requirement that the paradigms that exist while in Curses mode be carried over outside the Curses environment (see def_prog_mode()). Relationship to Signals Screens, Windows and Terminals Interface Overview 3.2 Screens, Windows and Terminals Screen A screen is the physical output device of the terminal. In Curses, a SCREEN data type is an opaque data type associated with a terminal. Each window (see below) is associated with a SCREEN. Windows The Curses functions permit manipulation of window objects, which can be thought of as two-dimensional arrays of characters and their renditions. A default window called stdscr, which is the size of the terminal screen, is supplied. Others may be created with newwin(). Variables declared as WINDOW * refer to windows (and to subwindows, derived windows, and pads, as described below). These data structures are manipulated with functions described on the reference manual pages in Chapter 6. Among the most basic functions are move() and addch(). More general versions of these functions are included that allow a process to specify a window. After using functions to manipulate a window, refresh() is called, telling Curses to make the CRT screen look like stdscr. Line drawing characters may be specified to be output. On input, Curses is also able to translate arrow and function keys that transmit escape sequences into single values. The line drawing characters and input values use names defined in . Each window has a flag that indicates that the information in the window could differ from the information displayed on the terminal device. Making any change to the contents of the window, moving or modifying the window, or setting the window's cursor position, sets this flag (touches the window). Refreshing the window clears this flag. (For further information, see is_linetouched()) Interface Overview Screens, Windows and Terminals Subwindows A subwindow is a window, created within another window (called the parent window), and positioned relative to the parent window. A subwindow can be created by calling derwin(), newpad() or subwin.() Changes made to a subwindow do not affect its parent window. Subwindows can be created from a parent window by calling subwin(). The position and size of subwindows on the screen must be identical to or totally within the parent window. Changes to either the parent window or the subwindow affect both. Window clipping is not a property of subwindows. Ancestors The term ancestor refers to a window's parent, or its parent, or so on. Derived Windows Derived windows are subwindows whose position is defined by reference to the parent window rather than in absolute screen coordinates. Derived windows are otherwise no different from subwindows. Pads A pad is a specialised case of subwindow that is not necessarily associated with a viewable part of a screen. Functions that deal with pads are all discussed in newpad(). Terminal A terminal is the logical input and output device through which character-based applications interact with the user. TERMINAL is an opaque data type associated with a terminal. A TERMINAL data structure primarily contains information about the capabilities of the terminal, as defined by terminfo. A TERMINAL also contains information about the terminal modes and current state for input and output operations. Each screen (see above) is associated with a TERMINAL. Characters Interface Overview 3.3 Characters 3.3.1 Character Storage Size Historically, a position on the screen has corresponded to a single stored byte. This correspondence is no longer true for several reasons: o Some characters may occupy several columns when displayed on the screen (see Section 3.3.2). o Some characters may be non-spacing characters, defined only in association with a spacing character (see Section 3.3.5). o The number of bytes to hold a character from the extended character sets depends on the LC_CTYPE locale category. The internal storage format of characters and renditions is unspecified. There is no implied correspondence between the internal storage format and the external representation of characters and renditions in objects of type chtype and cchar_t. 3.3.2 Multi-column Characters EC Some character sets define multi-column characters that occupy more than one column position when displayed on the screen. Writing a character whose width is greater than the width of the destination window is an error. ? 3.3.3 Attributes Each character can be displayed with attributes such as underlining, reverse video or colour on terminals that support such display enhancements. Current attributes of a window are applied to all characters that are written into the window with waddch(), wadd_wch(), waddstr(), waddchstr(), waddwstr(), waddwchstr() and wprintw(). Attributes can be combined. Attributes can be specified using constants with the A_ prefix specified in . The A_ constants EC manipulate attributes in objects of type chtype. !Additional attributes can be specified using Interface Overview Characters constants with the WA_ prefix. The WA_ constants manipulate attributes in objects of type attr_t. Two constants that begin with A_ and WA_ and that represent the same terminal capability refer to the same attribute in the terminfo database and in the window data structure. The effect on a window does not differ depending on whether the application specifies A_ or WA_ constants. For example, when an application updates window attributes using the interfaces that support the A_ values, a query of the window attribute using the function that returns WA_ values reflects this update. When it updates window attributes using the interfaces that support the WA_ values, for which corresponding A_ values exist, a query of the window attribute using the function that returns A_ values reflects this update. ? 3.3.4 Rendition The rendition of a character displayed on the screen EC is its attributes !and a colour pair. ? The rendition of a character written to the screen becomes a property of the character and moves with the character through any scrolling and insert/delete line/character operations. To the extent possible on a particular terminal, a character's rendition corresponds to the graphic rendition of the character put on the screen. If a given terminal does not support a rendition that an application program is trying to use, Curses may substitute a different rendition for it. EC Colours are always used in pairs (referred to as colour-pairs). A colour-pair consists of a foreground colour (for characters) and a background colour (for the field on which the characters are displayed). ? Characters Interface Overview 3.3.5 Non-spacing Characters EC The requirements in this section are in effect only for implementations that claim Enhanced Curses compliance. ? Some character sets may contain non-spacing characters. (Non-spacing characters are those for which wcwidth() returns a width of zero.) The application may write non-spacing characters to a window. Every non-spacing character in a window is associated with a spacing character and modifies the spacing character. Non-spacing characters in a window cannot be addressed separately. A non-spacing character is implicitly addressed whenever a Curses operation affects the spacing character with which the non-spacing character is associated. Non-spacing characters do not support attributes. For interfaces that use wide characters and attributes, the attributes are ignored if the wide character is a non-spacing character. Multi-column characters have a single set of attributes for all columns. The association of non-spacing characters with spacing characters can be controlled by the application using the wide character interfaces. The wide character string functions provide codeset-dependent association. Two typical effects of a non-spacing character associated with a spacing character called c, are as follows: o The non-spacing character may modify the appearance of c. (For instance, there may be non-spacing characters that add diacritical marks to characters. However, there may also be spacing characters with built-in diacritical marks.) o The non-spacing character may bridge c to the character following c. (Examples of this usage are the formation of ligatures and the conversion of characters into compound display forms, words, or ideograms.) Implementations may limit the number of non-spacing characters that can be associated with a spacing character, provided any limit is at least 5. Interface Overview Characters Complex Characters A complex character is a set of associated characters, which may include a spacing character and may include any non-spacing characters associated with it. A spacing complex character is a spacing character followed by any non-spacing characters associated with it. That is, a spacing complex character is a complex character that includes one spacing character. An example of a code set that has complex characters is ISO/IEC 10646-1:1993. A complex character can be written to the screen; if it does not include a spacing character, any non- spacing characters are associated with the spacing complex character that exists at the specified screen position. When the application reads information back from the screen, it obtains spacing complex characters. The cchar_t data type represents a complex character and its rendition. When a cchar_t represents a non- spacing complex character (that is, when there is no spacing character within the complex character), then its rendition is not used; when it is written to the screen, it uses the rendition specified by the spacing character already displayed. An object of type cchar_t can be initialised using setcchar() and its contents can be extracted using getcchar(). The behaviour of functions that take a cchar_t input argument is undefined if the application provides a cchar_t value that was not initialised in this way or obtained from a Curses function that has a cchar_t output argument. 3.3.6 Window Properties Associated with each window are the following properties that affect the placing of characters into the window (see Section 3.4.4). Window Rendition Each window has a rendition, which is separate from the rendition component of the window's background property described below. Characters Interface Overview Window Background Each window has a background property. The background property specifies: o A spacing complex character (the background character) that will be used in a variety of situations where visible information is deleted from the screen. o A rendition to use in displaying the background character in those situations, and in other situations specified in Section 3.4.4. Interface Overview Conceptual Operations 3.4 Conceptual Operations 3.4.1 Screen Addressing Many Curses functions use a coordinate pair. In the DESCRIPTION, coordinate locations are represented as (y, x) since the y argument always precedes the x argument in the function call. These coordinates denote a line/column position, not a character position. The coordinate y always refers to the row (of the window), and x always refers to the column. The first row and the first column is number 0, not 1. The position (0, 0) is the window's origin. For example, for terminals that display the ISO 8859-1 character set (with left-to-right writing), (0, 0) represents the upper left-hand corner of the screen. Functions that start with mv take arguments that specify a (y, x) position and move the cursor (as though move() were called) before performing the requested action. As part of the requested action, further cursor movement may occur, specified on the respective reference manual page. 3.4.2 Basic Character Operations Adding (Overwriting) The Curses functions that contain the word add, such as addch(), actually specify one or more characters to EC replace (overwrite) characters already in the window. If these functions specify only non-spacing characters, they are appended to a spacing character already in the window; see also Section 3.3.5 on page 22. When replacing a multi-column character with a character that requires fewer columns, the new character is added starting at the specified or implied column position. All columns that the former multi-column character occupied that the new character does not require are orphaned columns, which are filled using the background character and rendition. Replacing a character with a character that requires more columns also replaces one or more subsequent Conceptual Operations Interface Overview characters on the line. This process may also produce orphaned columns. ? Truncation, Wrapping and Scrolling If the application specifies a character or a string of characters such that writing them to a window would EC extend beyond the end of the line (for example, if the application tries to deposit any multi-column character at the last column in a line), ?the behaviour depends on whether the function supports line wrapping: o If the function does not wrap, it fails. o If the function wraps, then it places one or more characters in the window at the start of the next line, beginning with the first character that would not completely fit on the original line. EC If the final character on the line is a multi- column character that does not completely fit on the line, the entire character wraps to the next line and columns at the end of the original line may be orphaned. ? If the original line was the last line in the window, the wrap may cause a scroll to occur: - If scrolling is enabled, a scroll occurs. The contents of the first line of the window are lost. The contents of each remaining line in the window move to the previous line. The last line of the window is filled with any characters that wrapped. Any remaining space on the last line is filled with the background character and rendition. - If scrolling is disabled, any characters that would extend beyond the last column of the last line are truncated. The scrollok() function enables and disables scrolling. Some add functions move the cursor just beyond the end of the last character added. If this position is beyond the end of a line, it causes wrapping and scrolling under the conditions specified in the second bullet above. Interface Overview Conceptual Operations Insertion Insertion functions (such as insch()) insert characters immediately before the character at the specified or implied cursor position. The insertion shifts all characters that were formerly at or beyond the cursor position on the cursor line toward the end of that line. The disposition of the characters that would thus extend beyond the end of the line depends on whether the function supports wrapping: o If the function does not wrap, those characters are removed from the window. This may produce orphaned columns. o If the function supports wrapping, the effect is as described above in Truncation, Wrapping and Scrolling (except that the overwriting discussed in the final dash is an insertion). EC If multi-column characters are displayed, some cursor positions are within a multi-column character but not at the beginning of a character. Any request to insert data at a position that is not the beginning of a multi-column character will be adjusted so that the actual cursor position is at the beginning of the multi-column character in which the requested position occurs. There are no warning indications relative to cursor relocation. The application should not maintain an image of the cursor position, since this constitutes placing terminal-specific information in the application and defeats the purpose of using Curses. Portable applications cannot assume that a cursor position specified in an insert function is a reusable indication of the actual cursor position. ? Deletion EC Deletion functions (such as delch()) delete the simple !or complex ?character at the specified or implied EC cursor position, !no matter which column of the character this is. ?All column positions are replaced by the background character and rendition and the cursor is not relocated. If a character-deletion operation would cause a previous wrapping operation to be undone, then the results are unspecified. Conceptual Operations Interface Overview Window Operations Overlapping a window (that is, placing one window on top of another) and overwriting a window (that is, copying the contents of one window into another) EC follows the operation of overwriting !multi-column ?glyphs around its edge. Any orphaned columns are handled as in the character operations. Characters that Straddle the Subwindow Border EC A subwindow can be defined such that multi-column characters straddle the subwindow border. The character operations deal with these straddling characters as follows: o Reading the subwindow with a function such as in_wch() reads the entire straddling character. o Adding, inserting or deleting in the subwindow deletes the entire straddling character before the requested operation begins and does not relocate the cursor. o Scrolling lines in the subwindow has the following effects: - A straddling character at the start of the line is completely erased before the scroll operation begins. - A straddling character at the end of the line moves in the direction of the scroll and continues to straddle the subwindow border. Column positions outside the subwindow at the straddling character's former position are orphaned unless another straddling character scrolls into those positions. If the application calls a function such as border(), the above situations do not occur because writing the border on the subwindow deletes any straddling characters. In the above cases involving multi-column characters, operations confined to a subwindow can modify the screen outside the subwindow. Therefore, saving a subwindow, performing operations within the subwindow, and then restoring the subwindow may disturb the appearance of the screen. To overcome these effects (for example, for pop-up windows), the application Interface Overview Conceptual Operations should refresh the entire screen. ? 3.4.3 Special Characters Some functions process special characters as specified below. In functions that do not move the cursor based on the information placed in the window, these special characters would only be used within a string in order to affect the placement of subsequent characters; the cursor movement specified below does not persist in the visible cursor beyond the end of the operation. In functions that do move the cursor, these special characters can be used to affect the placement of subsequent characters and to achieve movement of the visible cursor. Unless the cursor was already in column 0, moves the cursor one column toward the start of the current line and any characters after the are added or inserted starting there. Unless the cursor was already in column 0, moves the cursor to the start of the current line. Any characters after the are added or inserted starting there. In an add operation, Curses adds the background character into successive columns until reaching the end of the line. Scrolling occurs as described in Truncation, Wrapping and Scrolling. Any characters after the character are inserted starting at the start of the new line. In an insert operation, moves the cursor to the start of a new line (causing scrolling as described in Truncation, Wrapping and Scrolling. Any characters after the character are placed at the start of the new line. The filter() function may inhibit this processing. Conceptual Operations Interface Overview Tab characters in text move subsequent characters to the next horizontal tab stop. By default, tab stops are in column 0, 8, 16, and so on. In an insert or add operation, Curses inserts or adds, respectively, the background character into successive columns until reaching the next tab stop. If there are no more tab stops in the current line, wrapping and scrolling occur as described in Truncation, Wrapping and Scrolling. Control Characters The Curses functions that perform special-character processing conceptually convert control characters to the caret ('^') character followed by a second character (which is an upper-case letter if it is alphabetic) and write this string to the window in place of the control character. The functions that retrieve text from the window will not retrieve the original control character. 3.4.4 Rendition of Characters Placed into a Window When the application adds or inserts characters into a window, the effect is as follows: If the character is not the space character, then the window receives: o the character that the application specifies o the colour that the application specifies; or the window colour, if the application does not specify a colour o the attributes specified, OR-ed with the window attributes. If the character is the space character, then the window receives: o the background character o the colour that the application specifies; or the background colour, if the application does not specify a colour Interface Overview Conceptual Operations o the attributes specified, OR-ed with the background attributes. Input Processing Interface Overview 3.5 Input Processing The Curses input model provides a variety of ways to obtain input from the keyboard. 3.5.1 Keypad Processing The application can enable or disable keypad translation by calling keypad(). When translation is enabled, Curses attempts to translate a sequence of terminal input that represents the pressing of a function key into a single key code. When translation is disabled, Curses passes terminal input to the application without such translation, and any interpretation of the input as representing the pressing of a keypad key must be done by the application. The complete set of key codes for keypad keys that Curses can process is specified by the constants defined in whose names begin with ``KEY_''. Each terminal type described in the terminfo database EC may support some or all of these key codes. The terminfo database specifies the sequence of input characters from the terminal type that correspond to each key code (see Section 6.2.8). The Curses implementation cannot translate keypad keys on terminals where pressing the keys does not transmit a unique sequence. When translation is enabled and a character that could be the beginning of a function key (such as escape) is received, Curses notes the time and begins accumulating characters. If Curses receives additional characters that represent the pressing of a keypad key, within an unspecified interval from the time the first character was received, then Curses converts this input to a key code for presentation to the application. If such characters are not received during this interval, translation of this input does not occur and the individual characters are presented to the application separately. (Because Curses waits for this interval to accumulate a key code, many terminals experience a delay between the time a user presses the escape key and the time the escape is returned to the application.) EC In addition, No Timeout Mode provides that in any case where Curses has received part of a function key sequence, it waits indefinitely for the complete key Interface Overview Input Processing sequence. The ``unspecified interval'' in the previous paragraph becomes infinite in No Timeout Mode. No Timeout Mode allows the use of function keys over slow communication lines. No Timeout Mode lets the user type the individual characters of a function key sequence, but also delays application response when the user types a character (not a function key) that begins a function key sequence. For this reason, in No Timeout Mode many terminals will appear to hang between the time a user presses the escape key and the time another key is pressed. No Timeout Mode is switchable by calling notimeout(). ? If any special characters (see Section 3.4.3) are defined or redefined to be characters that are members of a function key sequence, then Curses will be unable to recognise and translate those function keys. Several of the modes discussed below are described in terms of availability of input. If keypad translation is enabled, then input is not available once Curses has begun receiving a keypad sequence until the sequence is completely received or the interval has elapsed. Input Processing Interface Overview 3.5.2 Input Mode The XBD specification (Special Characters) defines flow-control characters, the interrupt character, the erase character, and the kill character. Four mutually-exclusive Curses modes let the application control the effect of these input characters: Input Mode Effect This achieves normal line-at-a-time processing with all special characters handled outside the application. This achieves the same effect as canonical-mode input processing as specified in the XBD specification. The state of the ISIG and IXON flags are not changed upon entering this mode by calling cbreak(), and are set upon entering this mode by calling noraw(). Cooked Mode EC The implementation supports erase and kill characters from any supported locale, no matter what the width of the character is. ? Characters typed by the user are immediately available to the application and Curses does not perform special processing on either the erase character or the kill character. An application can select cbreak mode to do its own line editing but to let the abort character be used to abort the task. This mode achieves the same effect as non-canonical-mode, Case B input processing (with MIN set to 1 and ICRNL cleared) as specified in the XBD specification. The state of the ISIG and IXON flags are not changed upon entering this mode. cbreak Mode The effect is the same as cbreak, except that input functions wait until a character is available or an interval defined by the application elapses, whichever comes first. This mode achieves the same effect as non-canonical-mode, Case C input processing (with TIME set to the value specified by the application) as specified in the XBD specification. The state of the ISIG and IXON flags are not changed upon entering this mode. Half-Delay Mode Raw mode gives the application maximum control over terminal input. The application sees each character as it is typed. This achieves the same effect as non-canonical mode, Case D input processing as specified in the XBD specification. The ISIG and IXON flags are cleared upon entering this mode. Raw Mode The terminal interface settings are recorded when the process calls initscr() or newterm() to initialise Curses and restores these settings when endwin() is called. The initial input mode for Curses operations EC Interface Overview Input Processing is unspecified !unless the implementation supports Enhanced Curses compliance, in which the initial input mode is cbreak mode. ? The behaviour of the BREAK key depends on other bits in the display driver that are not set by Curses. 3.5.3 Delay Mode Two mutually-exclusive delay modes specify how quickly certain Curses functions return to the application when there is no terminal input waiting when the function is called: No Delay The function fails. Delay The application waits until the implementation passes text through to the application. If cbreak or Raw Mode is set, this is after one character. Otherwise, this is after the first character, end-of-line character, or end-of-file character. The effect of No Delay Mode on function key processing is unspecified. 3.5.4 Echo Processing Echo mode determines whether Curses echoes typed characters to the screen. The effect of Echo mode is analogous to the effect of the ECHO flag in the local mode field of the termios structure associated with the terminal device connected to the window. However, Curses always clears the ECHO flag while it is operating, to inhibit the operating system from performing echoing. The method of echoing characters is not identical to the operating system's method of echoing characters, because Curses performs additional processing of terminal input. If in Echo mode, Curses performs its own echoing: Any visible input character is stored in the current or specified window by the input function that the application called, at that window's cursor position, as though addch() were called, with all consequent effects such as cursor movement and wrapping. If not in Echo mode, any echoing of input must be performed by the application. Applications often Input Processing Interface Overview perform their own echoing in a controlled area of the screen, or do not echo at all, so they disable Echo mode. Interface Overview The Set of Curses Functions 3.6 The Set of Curses Functions The Curses functions allow: overall screen, window and pad manipulation; output to windows and pads; reading terminal input; control over terminal and Curses input and output options; environment query functions; colour manipulation; use of soft label keys; access to the terminfo database of terminal capabilities; and access to low-level functions. 3.6.1 Function Name Conventions The reference manual pages in Chapter 4 present families of multiple Curses functions. Most function families have different functions that give the programmer the following options: o A function with the basic name operates on the window stdscr. A function with the same name plus the w prefix operates on a window specified by the win argument. When the reference manual page for a function family refers to the current or specified window, it means stdscr for the basic functions and the window specified by win for any w function. Functions whose names have the p prefix require an argument that is a pad instead of a window. o A function with the basic name operates based on the current cursor position (of the current or specified window, as described above). A function with the same name plus the mv prefix moves the cursor to a position specified by the y and x arguments before performing the specified operation. When the reference manual page for a function family refers to the current or specified position, it means the cursor position for the basic functions and the position (y, x) for any mv function. The mvw prefix exists and combines the mv semantics discussed here with the w semantics discussed above. The window argument is always specified before the coordinates. o A function with the basic name is often provided for historical compatibility and operates only on The Set of Curses Functions Interface Overview single-byte characters. A function with the same name plus the w infix operates on wide (multi- byte) characters. A function with the same name plus the _w infix operates on complex characters and their renditions. o When a function with the basic name operates on a single character, there is sometimes a function with the same name plus the n infix that operates on multiple characters. An n argument specifies the number of characters to process. The respective manual page specifies the outcome if the value of n is inappropriate. Interface Overview The Set of Curses Functions 3.6.2 Function Families Provided Function Names Description s w c Refer to Add (Overwrite) [mv][w]addch() add a character Y Y Y addch() [mv][w]addch[n]str() add a character string N N N addchstr() [mv][w]add[n]str() add a string Y Y Y addnstr() [mv][w]add[n]wstr() add a wide character string Y Y Y addnwstr() [mv][w]add_wch() add a wide character and rendition Y Y Y add_wch() [mv][w]add_wch[n]str() add an array of wide characters and renditions ? N N add_wchnstr() Change Renditions [mv][w]chgat() change renditions of characters in a window - N N chgat() Delete [mv][w]delch() delete a character - - N delch() Get (Input from Keyboard to Window) [mv][w]getch() get a character Y Y Y getch() [mv][w]get[n]str() get a character string Y Y Y getnstr() [mv][w]get_wch() get a wide character Y Y Y get_wch() [mv][w]get[n]_wstr() get an array of wide characters and key codes Y Y Y get_wstr() Explicit Cursor Movement [w]move() move the cursor - - - move() Input (Read Back from Window) [mv][w]inch() input a character - - - inch() [mv][w]inch[n]str() input an array of characters and attributes - - - inchnstr() [mv][w]in[n]str() input a string - - - innstr() [mv][w]in[n]wstr() input a string of wide characters - - - innwstr() [mv][w]in_wch() input a wide character and rendition - - - in_wch() [mv][w]in_wch[n]str() input an array of wide characters and renditions - - - inwchnstr() Insert [mv][w]insch() insert a character Y N N insch() [mv][w]ins[n]str() insert a character string Y N N insnstr() [mv][w]ins_[n]wstr() insert a wide-character string Y N N ins_nwstr() [mv][w]ins_wch() insert a wide character Y N N ins_wch() Print and Scan [mv][w]printw() print formatted output - - - mvprintw() [mv][w]scanw() convert formatted output - - - mvscanw() The Set of Curses Functions Interface Overview Legend The following notation indicates the effect when characters are moved to the screen. (For the Get functions, this applies only when echoing is enabled.) s Y means these functions perform special-character processing (see Section 3.4.3). N means they do not. ? means the results are unspecified when these functions are applied to special characters. w Y means these functions perform wrapping (see Truncation, Wrapping and Scrolling). N means they do not. c Y means these functions advance the cursor (see Truncation, Wrapping and Scrolling). N means they do not. - The attribute specified by this column does not apply to these functions. Interface Overview Interfaces Implemented as Macros 3.7 Interfaces Implemented as Macros The following interfaces with arguments must be implemented as macros. The relevance to the application programmer is that the `&' character cannot be used before the arguments. Macros Chapter 4 Entry COLOR_PAIR() can_change_color() getbegyx(), getmaxyx(), getparyx(), getyx() getbegyx() The header file reference manual pages list other macros, like COLOR_BLACK, that do not take arguments. 3.8 Initialised Curses Environment Before executing an application that uses Curses, the terminal must be prepared as follows: o If the terminal has hardware tab stops, they should be set. o Any initialisation strings defined for the terminal must be output to the terminal. EC The resulting state of the terminal must be compatible with the model of the terminal that Curses has, as reflected in the terminal's entry in the terminfo database (see Chapter 6). ? To initialise Curses, the application must call initscr() or newterm() before calling any of the other functions that deal with windows and screens, and it must call endwin() before exiting. To get character- at-a-time input without echoing (most interactive, screen-oriented programs want this), the following sequence should be used: initscr() cbreak() noecho() Most programs would additionally use the sequence: Initialised Curses Environment Interface Overview nonl() intrflush(stdscr, FALSE) keypad(stdscr, TRUE) Interface OvSynchronous and Networked Asynchronous Terminals 3.9 Synchronous and Networked Asynchronous Terminals This section indicates to the application writer some considerations to be borne in mind when driving synchronous, networked asynchronous (NWA) or non- standard directly-connected asynchronous terminals. Such terminals are often used in a mainframe environment and communicate to the host in block mode. That is, the user types characters at the terminal then presses a special key to initiate transmission of the characters to the host. Frequently, although it may be possible to send arbitrary sized blocks to the host, it is not possible or desirable to cause a character to be transmitted with only a single keystroke. This can cause severe problems to an application wishing to make use of single-character input; see Section 3.5. Output The Curses interface can be used in the normal way for all operations pertaining to output to the terminal, with the possible exception that on some terminals the refresh() routine may have to redraw the entire screen contents in order to perform any update. If it is additionally necessary to clear the screen before each such operation, the result could be undesirable. Input Because of the nature of operation of synchronous (block-mode) and NWA terminals, it might not be possible to support all or any of the Curses input functions. In particular, the following points should be noted: o Single-character input might not be possible. It may be necessary to press a special key to cause all characters typed at the terminal to be transmitted to the host. o It is sometimes not possible to disable echo. Character echo may be performed directly by the terminal. On terminals that behave in this way, any Curses application that performs input should be aware that any characters typed will appear on Synchronous and Networked Asynchronous TerInterface Overview the screen at wherever the cursor is positioned. This does not necessarily correspond to the position of the cursor in the window. Chapter 4 Curses Interfaces This chapter describes the Curses functions, macros and external variables to support application portability at the C-language source level. The display model defined in Section 3.4 contains important information, not repeated for individual interface definitions, regarding cursor movement, relocation of the cursor in the case of multi-column characters, wrapping of characters to subsequent lines of the screen, truncation of characters, and other important concepts. The reference manual pages must be read in conjunction with this overview information. The interface definitions are collated as though any underscore characters were not present. addch() CURSES Curses Interfaces NAME addch, mvaddch, mvwaddch, waddch - add a single-byte character and rendition to a window and advance the cursor SYNOPSIS #include int addch(const chtype ch); int mvaddch(int y, int x, const chtype ch); int mvwaddch(WINDOW *win, int y, int x, const chtype ch); int waddch(WINDOW *win, const chtype ch); DESCRIPTION The addch(), mvaddch(), mvwaddch() and waddch() functions place ch into the current or specified window at the current or specified position, and then advance the window's cursor position. These functions perform wrapping. These functions perform special-character processing. RETURN VALUE Upon successful completion, these functions return OK. Otherwise they return ERR. ERRORS No errors are defined. APPLICATION USAGE These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. SEE ALSO Section 3.4.4, add_wch(), attroff(), doupdate(), . CHANGE HISTORY First released in Issue 2. Issue 4 The entry is rewritten for clarity. Also the type of argument ch is changed from chtype to const chtype. Curses Interfaces CURSES addchstr() NAME addchstr, addchnstr, mvaddchstr, mvaddchnstr, mvwaddchstr, mvwaddchnstr waddchstr, waddchnstr - add string of single-byte characters and renditions to a window SYNOPSIS #include int addchstr(chtype *const chstr); EC int addchnstr(chtype *const chstr, int n); int mvaddchstr(int y, int x, chtype *const chstr); EC int mvaddchnstr(int y, int x, chtype *const chstr, int n); int mvwaddchstr(WINDOW *win, int y, int x, chtype *const chstr); EC int mvwaddchnstr(WINDOW *win, int y, int x, chtype *const chstr, int n); int waddchstr(WINDOW *win, chtype *const chstr); EC int waddchnstr(WINDOW *win, chtype *const chstr, int n); ? DESCRIPTION These functions overlay the contents of the current or specified window, starting at the current or specified position, with the contents of the array pointed to by chstr until a null chtype is encountered in the array pointed to by chstr. These functions do not change the cursor position. These functions do not perform special-character processing. These functions do not perform wrapping. EC The addchnstr(), mvaddchnstr(), mvwaddchnstr() and waddchnstr() functions copy at most n items, but no more than will fit on the line. If n is -1 then the whole string is copied, to the maximum number that fit on the line. ? RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. addchstr() CURSES Curses Interfaces APPLICATION USAGE These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. SEE ALSO addch(), add_wch(), add_wchstr(), . CHANGE HISTORY First released in Issue 4. Curses Interfaces ENHANCED CURSES addnstr() NAME addnstr, addstr, mvaddnstr, mvaddstr, mvwaddnstr, mvwaddstr waddnstr, waddstr - add a string of multi-byte characters without rendition to a window and advance cursor SYNOPSIS EC #include int addnstr(char *const str, int n); int addstr(char *const str); int mvaddnstr(int y, int x, char *const str, int n); int mvaddstr(int y, int x, char *const str); int mvwaddnstr(WINDOW *win, int y, int x, char *const str, int n); int mvwaddstr(WINDOW *win, int y, int x, char *const str); int waddnstr(WINDOW *win, char *const str, int n); int waddstr(WINDOW *win, char *const str); ? DESCRIPTION These functions write the characters of the string str on the current or specified window starting at the current or specified position using the background rendition. These functions advance the cursor position. These functions perform special character processing. These functions perform wrapping. The addstr(), mvaddstr(), mvwaddstr() and waddstr() functions are similar to calling mbstowcs() on str, and then calling addwstr(), mvaddwstr(), mvwaddwstr() and waddwstr(), respectively. The addnstr(), mvaddnstr(), mvwaddnstr() and waddnstr() functions use at most n bytes from str. These functions add the entire string when n is -1. These functions are similar to calling mbstowcs() on the first n bytes of str, and then calling addwstr(), mvaddwstr(), mvwaddwstr() and waddwstr(), respectively. RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. addnstr() ENHANCED CURSES Curses Interfaces ERRORS No errors are defined. SEE ALSO addnwstr(), mbstowcs() (in the XSH specification), . CHANGE HISTORY First released in Issue 4. In Issue 3, the addstr(), mvaddstr(), mvwaddstr() and waddstr() functions were described in the addstr() entry. In Issue 4, the type of the str argument defined for these functions is changed from char * to char *const, and the DESCRIPTION is changed to indicate that the functions will handle multi-byte sequences correctly. Curses Interfaces ENHANCED CURSES addnwstr() NAME addnwstr, addwstr, mvaddnwstr, mvaddwstr, mvwaddnwstr, mvwaddwstr, waddnwstr, waddwstr - add a wide-character string to a window and advance the cursor SYNOPSIS EC #include int addnwstr(wchar_t *const wstr, int n); int addwstr(wchar_t *const wstr); int mvaddnwstr(int y, int x, wchar_t *const wstr, int n); int mvaddwstr(int y, int x, wchar_t *const wstr); int mvwaddnwstr(WINDOW *win, int y, int x, wchar_t *const wstr, int n); int mvwaddwstr(WINDOW *win, int y, int x, wchar_t *const wstr); int waddnwstr(WINDOW *win, wchar_t *const wstr, int n); int waddwstr(WINDOW *win, wchar_t *const wstr); ? DESCRIPTION These functions write the characters of the wide character string wstr on the current or specified window at that window's current or specified cursor position. These functions advance the cursor position. These functions perform special character processing. These functions perform wrapping. The effect is similar to building a cchar_t from the wchar_t and the background rendition and calling wadd_wch(), once for each wchar_t character in the string. The cursor movement specified by the mv functions occurs only once at the start of the operation. The addnwstr(), mvaddnwstr(), mvwaddnwstr() and waddnwstr() functions write at most n wide characters. If n is -1, then the entire string will be added. RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. addnwstr() ENHANCED CURSES Curses Interfaces ERRORS No errors are defined. SEE ALSO add_wch(), . CHANGE HISTORY First released in Issue 4. Curses Interfaces ENHANCED CURSES add_wch() NAME add_wch, mvadd_wch, mvwadd_wch, wadd_wch - add a complex character and rendition to a window SYNOPSIS EC #include int add_wch(cchar_t *const wch); int wadd_wch(WINDOW *win, cchar_t *const wch); int mvadd_wch(int y, int x, cchar_t *const wch); int mvwadd_wch(WINDOW *win, int y, int x, cchar_t *const wch); ? DESCRIPTION These functions add information to the current or specified window at the current or specified position, and then advance the cursor. These functions perform wrapping. These functions perform special-character processing. o If wch refers to a spacing character, then any previous character at that location is removed, a new character specified by wch is placed at that location with rendition specified by wch; then the cursor advances to the next spacing character on the screen. o If wch refers to a non-spacing character, all previous characters at that location are preserved, the non-spacing characters of wch are added to the spacing complex character, and the rendition specified by wch is ignored. RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. SEE ALSO Section 3.4.4, addch(), . CHANGE HISTORY First released in Issue 4. add_wchnstr() ENHANCED CURSES Curses Interfaces NAME add_wchnstr, add_wchstr, mvadd_wchnstr, mvadd_wchstr, mvwadd_wchnstr, mvwadd_wchstr, wadd_wchnstr, wadd_wchstr - add an array of complex characters and renditions to a window SYNOPSIS EC #include int add_wchnstr(cchar_t *const wchstr, int n); int add_wchstr(cchar_t *const wchstr); int wadd_wchnstr(WINDOW *win, cchar_t *const wchstr, int n); int wadd_wchstr(WINDOW *win, cchar_t *const wchstr); int mvadd_wchnstr(int y, int x, cchar_t *const wchstr, int n); int mvadd_wchstr(int y, int x, cchar_t *const wchstr); int mvwadd_wchnstr(WINDOW *win, int y, int x, cchar_t *const wchstr, int n); int mvwadd_wchstr(WINDOW *win, int y, int x, cchar_t *const wchstr); ? DESCRIPTION These functions write the array of cchar_t specified by wchstr into the current or specified window starting at the current or specified cursor position. These functions do not advance the cursor. The results are unspecified if wchstr contains any special characters. The functions end successfully on encountering a null cchar_t. The functions also end successfully when they fill the current line. If a character cannot completely fit at the end of the current line, those columns are filled with the background character and rendition. The add_wchnstr(), mvadd_wchnstr(), mvwadd_wchnstr() and wadd_wchnstr() functions end successfully after writing n cchar_ts (or the entire array of cchar_ts, if n is -1). RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. Curses Interfaces ENHANCED CURSES add_wchnstr() ERRORS No errors are defined. SEE ALSO . CHANGE HISTORY First released in Issue 4. attroff() CURSES Curses Interfaces NAME attroff, attron, attrset, wattroff, wattron, wattrset - restricted window attribute control functions SYNOPSIS #include int attroff(int attrs); int attron(int attrs); int attrset(int attrs); int wattroff(WINDOW *win, int attrs); int wattron(WINDOW *win, int attrs); int wattrset(WINDOW *win, int attrs); DESCRIPTION These functions manipulate the window attributes of the current or specified window. The attroff() and wattroff() functions turn off attrs in the current or specified window without affecting any others. The attron() and wattron() functions turn on attrs in the current or specified window without affecting any others. The attrset() and wattrset() functions set the background attributes of the current or specified window to attrs. It is unspecified whether these functions can be used to manipulate attributes other than A_BLINK, A_BOLD, A_DIM, A_REVERSE, A_STANDOUT and A_UNDERLINE. RETURN VALUE These functions always return either OK or 1. ERRORS No errors are defined. SEE ALSO attr_get(), standend(), . CHANGE HISTORY First released in Issue 2. Curses Interfaces CURSES attroff() Issue 4 This entry is rewritten for clarity. The DESCRIPTION is updated to specify that it is undefined whether these functions can be used to manipulate attributes beyond those defined in Issue 3. The standend(), standout(), wstandend() and wstandout() functions are moved to the standend() entry. attr_get() ENHANCED CURSES Curses Interfaces NAME attr_get, attr_off, attr_on, attr_set, wattr_get, wattr_off, wattr_on, wattr_set - window attribute control functions SYNOPSIS EC #include attr_t attr_get(void); int attr_off(attr_t attrs); int attr_on(attr_t attrs); int attr_set(attr_t attrs); attr_t wattr_get(WINDOW *win); int wattr_off(WINDOW *win, attr_t attrs); int wattr_on(WINDOW *win, attr_t attrs); int wattr_set(WINDOW *win, attr_t attrs); ? DESCRIPTION These functions manipulate the window attributes of the current or specified window. The attr_get() and wattr_get() functions obtain the current attributes of a window. The attr_off() and wattr_off() functions turn off attrs in the current or specified window without affecting any others. The attr_on() and wattr_on() functions turn on attrs in the current or specified window without affecting any others. The attr_set() and wattr_set() functions set the background attributes of the current or specified window to attrs. RETURN VALUE The attr_get() and wattr_get() functions return the current window attributes for the current or specified window. The other functions always return OK. Curses Interfaces ENHANCED CURSES attr_get() ERRORS No errors are defined. SEE ALSO attroff(), . CHANGE HISTORY First released in Issue 4. baudrate() CURSES Curses Interfaces NAME baudrate - get terminal baud rate SYNOPSIS #include int baudrate(void); DESCRIPTION The baudrate() function extracts the output speed of the terminal in bits per second. RETURN VALUE The baudrate() function returns the output speed of the terminal. ERRORS No errors are defined. SEE ALSO tcgetattr() (in the XSH specification), . CHANGE HISTORY First released in Issue 2. Issue 4 The argument list is explicitly declared as void. Curses Interfaces CURSES beep() NAME beep - audible signal SYNOPSIS #include int beep(void); DESCRIPTION The beep() function alerts the user. It sounds the audible alarm on the terminal, or if that is not possible, it flashes the screen (visible bell). If neither signal is possible, nothing happens. RETURN VALUE The beep() function always returns OK. ERRORS No errors are defined. APPLICATION USAGE Nearly all terminals have an audible alarm, but only some can flash the screen. SEE ALSO flash(), . CHANGE HISTORY First released in Issue 2. Issue 4 The argument list is explicitly declared as void. The RETURN VALUE section is changed to indicate that the function always returns OK. The flash() function is moved to its own entry. bkgd() ENHANCED CURSES Curses Interfaces NAME bkgd, bkgdset, getbkgd, wbkgd, wbkgdset - set or get background character and rendition using a single- byte character SYNOPSIS EC #include int bkgd(chtype ch); void bkgdset(chtype ch); chtype getbkgd(WINDOW *win); int wbkgd(WINDOW *win, chtype ch); void wbkgdset(WINDOW *win, chtype ch); ? DESCRIPTION The bkgdset() and wbkgdset() functions set the background property of the current or specified window based on the information in ch. If ch refers to a multi-column character, the results are undefined. The bkgd() and wbkgd() functions set the background property of the current or specified window and then apply this setting to every character position in that window: o The rendition of every character on the screen is changed to the new background rendition. o Wherever the former background character appears, it is changed to the new background character. The getbkgd() function extracts the specified window's background character and rendition. RETURN VALUE Upon successful completion, bkgd() and wbkgd() return OK. Otherwise, they return ERR. The bkgdset() and wbkgdset() functions do not return a value. Upon successful completion, getbkgd() returns the specified window's background character and rendition. Otherwise, it returns (chtype)ERR. Curses Interfaces ENHANCED CURSES bkgd() ERRORS No errors are defined. APPLICATION USAGE These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. SEE ALSO Section 3.3.4, . CHANGE HISTORY First released in Issue 4. bkgrnd() ENHANCED CURSES Curses Interfaces NAME bkgrnd, bkgrndset, getbkgrnd, wbkgrnd, wbkgrndset, wgetbkgrnd - set or get background character and rendition using a complex character SYNOPSIS EC #include int bkgrnd(cchar_t *const wch); void bkgrndset(cchar_t *const wch); int getbkgrnd(cchar_t *wch); int wbkgrnd(WINDOW *win, cchar_t *const wch); void wbkgrndset(WINDOW *win, cchar_t *const wch); int wgetbkgrnd(WINDOW *win, cchar_t *wch); ? DESCRIPTION The bkgrndset() and wbkgrndset() functions set the background property of the current or specified window based on the information in wch. The bkgrnd() and wbkgrnd() functions set the background property of the current or specified window and then apply this setting to every character position in that window: o The rendition of every character on the screen is changed to the new background rendition. o Wherever the former background character appears, it is changed to the new background character. If wch refers to a non-spacing complex character for bkgrnd(), bkgrndset(), wbkgrnd() and wbkgrndset(), then wch is added to the existing spacing complex character that is the background character. If wch refers to a multi-column character, the results are unspecified. The getbkgrnd() and wgetbkgrnd() functions store, into the area pointed to by wch, the value of the window's background character and rendition. RETURN VALUE The bkgrndset() and wbkgrndset() functions do not return a value. Curses Interfaces ENHANCED CURSES bkgrnd() Upon successful completion, the other functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. SEE ALSO Section 3.3.4, . CHANGE HISTORY First released in Issue 4. border() ENHANCED CURSES Curses Interfaces NAME border, wborder - draw borders from single-byte characters and renditions SYNOPSIS EC #include int border(chtype ls, chtype rs, chtype ts, chtype bs, chtype tl, chtype tr, chtype bl, chtype br); int wborder(WINDOW *win, chtype ls, chtype rs, chtype ts, chtype bs, chtype tl, chtype tr, chtype bl, chtype br); ? DESCRIPTION The border() and wborder() functions draw a border around the edges of the current or specified window. These functions do not advance the cursor position. These functions do not perform special character processing. These functions do not perform wrapping. The arguments in the left-hand column of the following table contain single-byte characters with renditions, which have the following uses in drawing the border: Argument Default Name Usage Value ls Starting-column side ACS_VLINE rs Ending-column side ACS_VLINE ts First-line side ACS_HLINE bs Last-line side ACS_HLINE tl Corner of the first line and the starting column ACS_ULCORNER tr Corner of the first line and the ending column ACS_URCORNER bl Corner of the last line and the starting column ACS_BLCORNER br Corner of the last line and the ending column ACS_BRCORNER If the value of any argument in the left-hand column is 0, then the default value in the right-hand column is used. If the value of any argument in the left-hand column is a multi-column character, the results are undefined. RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. Curses Interfaces ENHANCED CURSES border() ERRORS No errors are defined. APPLICATION USAGE These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. SEE ALSO border_set(), box(), hline(), . CHANGE HISTORY First released in Issue 4. border_set() ENHANCED CURSES Curses Interfaces NAME border_set, wborder_set, - draw borders from complex characters and renditions SYNOPSIS EC #include int border_set(cchar_t *const ls, cchar_t *const rs, cchar_t *const ts, cchar_t *const bs, cchar_t *const tl, cchar_t *const tr, cchar_t *const bl, cchar_t *const br); int wborder_set(WINDOW *win, cchar_t *const ls, cchar_t *const rs, cchar_t *const ts, cchar_t *const bs, cchar_t *const tl, cchar_t *const tr, cchar_t *const bl, cchar_t *const br); ? DESCRIPTION The border_set() and wborder_set() functions draw a border around the edges of the current or specified window. These functions do not advance the cursor position. These functions do not perform special character processing. These functions do not perform wrapping. The arguments in the left-hand column of the following table contain spacing complex characters with renditions, which have the following uses in drawing the border: Argument Default Name Usage Value ls Starting-column side WACS_VLINE rs Ending-column side WACS_VLINE ts First-line side WACS_HLINE bs Last-line side WACS_HLINE tl Corner of the first line and the starting column WACS_ULCORNER tr Corner of the first line and the ending column WACS_URCORNER bl Corner of the last line and the starting column WACS_BLCORNER br Corner of the last line and the ending column WACS_BRCORNER If the value of any argument in the left-hand column is a null pointer, then the default value in the right-hand column is used. If the value of any argument in the left-hand column is a multi-column character, the results are undefined. RETURN VALUE Upon successful completion, these functions return Curses Interfaces ENHANCED CURSES border_set() OK. Otherwise, they return ERR. ERRORS No errors are defined. SEE ALSO box_set(), hline_set(), . CHANGE HISTORY First released in Issue 4. box() CURSES Curses Interfaces NAME box - draw borders from single-byte characters and renditions SYNOPSIS #include int box(WINDOW *win, chtype verch, chtype horch); DESCRIPTION The box() function draws a border around the edges of the specified window. This function does not advance the cursor position. This function does not perform special character processing. This function does not perform wrapping. The function box(win, verch, horch) has an effect equivalent to: wborder(win, verch, verch, horch, horch, 0, 0, 0, 0); RETURN VALUE Upon successful completion, box() returns OK. Otherwise, it returns ERR. ERRORS No errors are defined. APPLICATION USAGE These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. SEE ALSO border(), box_set(), hline(), . CHANGE HISTORY First released in Issue 2. Issue 4 The DESCRIPTION is changed to describe this function in terms of a call to the wborder() function. Curses Interfaces ENHANCED CURSES box_set() NAME box_set - draw borders from complex characters and renditions SYNOPSIS EC #include int box_set(WINDOW *win, cchar_t *const verch, cchar_t *const horch); ? DESCRIPTION The box_set() function draws a border around the edges of the specified window. This function does not advance the cursor position. This function does not perform special character processing. This function does not perform wrapping. The function box_set(win, verch, horch) has an effect equivalent to: wborder_set(win, verch, verch, horch, horch, NULL, NULL, NULL, NULL); RETURN VALUE Upon successful completion, this function returns OK. Otherwise, it returns ERR. ERRORS No errors are defined. SEE ALSO border_set(), hline_set(), . CHANGE HISTORY First released in Issue 4. can_change_color() ENHANCED CURSES Curses Interfaces NAME can_change_color, color_content, has_colors, init_color, init_pair, start_color, pair_content - color manipulation functions SYNOPSIS EC #include bool can_change_color(void); int color_content(short color, short *red, short *green, short *blue); int COLOR_PAIR(int n); bool has_colors(void); int init_color(short color, short red, short green, short blue); int init_pair(short pair, short f, short b); int pair_content(short pair, short *f, short *b); int PAIR_NUMBER(int value); int start_color(void); extern int COLOR_PAIRS; extern int COLORS; ? DESCRIPTION These functions manipulate colour on terminals that support colour. Querying Capabilities The has_colors() function indicates whether the terminal is a colour terminal. The can_change_color() function indicates whether the terminal is a colour terminal on which colours can be redefined. Initialisation The start_color() function must be called in order to enable use of colours and before any colour manipulation function is called. The function initialises eight basic colours (black, blue, green, cyan, red, magenta, yellow, and white) that can be specified by the colour macros (such as COLOR_BLACK) defined in . (See Colour-related Macros) Curses Interfaces ENHANCED CURSES can_change_color() The initial appearance of these eight colours is not specified. The function also initialises two global external variables: o COLORS defines the number of colours that the terminal supports. (See Colour Identification below.) If COLORS is 0, the terminal does not support redefinition of colours (and can_change_colour() will return FALSE). o COLOR_PAIRS defines the maximum number of colour-pairs that the terminal supports. (See User-Defined Colour Pairs below.) The start_color() function also restores the colours on the terminal to terminal-specific initial values. The initial background colour is assumed to be black for all terminals. Colour Identification The init_color() function redefines colour number color, on terminals that support the redefinition of colours, to have the red, green, and blue intensity components specified by red, green, and blue, respectively. Calling init_color() also changes all occurrences of the specified colour on the screen to the new definition. The color_content() function identifies the intensity components of colour number color. It stores the red, green, and blue intensity components of this colour in the addresses pointed to by red, green, and blue, respectively. For both functions, the color argument must be in the range from 0 to and including COLORS-1. Valid intensity values range from 0 (no intensity component) up to and including 1000 (maximum intensity in that component). User-Defined Colour Pairs Calling init_pair() defines or redefines colour-pair number pair to have foreground colour f and background colour b. Calling init_pair() changes any characters that were displayed in the colour pair's old definition to the new definition and refreshes the screen. can_change_color() ENHANCED CURSES Curses Interfaces After defining the colour pair, the macro COLOR_PAIR(n) returns the value of colour pair n. This value is the colour attribute as it would be extracted from a chtype. Conversely, the macro PAIR_NUMBER(value) returns the colour pair number associated with the colour attribute value. The pair_content() function retrieves the component colours of a colour-pair number pair. It stores the foreground and background colour numbers in the variables pointed to by f and b, respectively. With init_pair() and pair_content(), the value of pair must be in a range from 0 to and including COLOR_PAIRS-1. (There may be an implementation- specific lower limit on the valid value of pair, but any such limit is at least 63.) Valid values for f and b are the range from 0 to and including COLORS-1. RETURN VALUE The has_colors() function returns TRUE if the terminal can manipulate colors; otherwise, it returns FALSE. The can_change_color() function returns TRUE if the terminal supports colors and can change their definitions; otherwise, it returns FALSE. Upon successful completion, the other functions return OK; otherwise, they return ERR. ERRORS No errors are defined. APPLICATION USAGE To use these functions, start_color() must be called, usually right after initscr(). The can_change_color() and has_colors() functions facilitate writing terminal-independent programs. For example, a programmer can use them to decide whether to use colour or some other video attribute. On color terminals, a typical value of COLORS is 8 and the macros such as COLOR_BLACK return a value within the range from 0 to and including 7. However, applications cannot rely on this to be true. SEE ALSO attroff(), delscreen(), . Curses Interfaces ENHANCED CURSES can_change_color() CHANGE HISTORY First released in Issue 4. cbreak() CURSES Curses Interfaces NAME cbreak, nocbreak, noraw, raw - input mode control functions SYNOPSIS #include int cbreak(void); int nocbreak(void); int noraw(void); int raw(void); DESCRIPTION The cbreak() function sets the input mode for the current terminal to cbreak mode and overrides a call to raw(). The nocbreak() function sets the input mode for the current terminal to Cooked Mode without changing the state of ISIG and IXON. The noraw() function sets the input mode for the current terminal to Cooked Mode and sets the ISIG and IXON flags. The raw() function sets the input mode for the current terminal to Raw Mode. RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. APPLICATION USAGE If the application is not certain what the input mode of the process was at the time it called initscr(), it should use these functions to specify the desired input mode. SEE ALSO Section 3.5.2, , XBD specification, Chapter 9, General Terminal Interface. CHANGE HISTORY First released in Issue 2. Curses Interfaces CURSES cbreak() Issue 4 The raw() and noraw() functions are merged with this entry. In previous issues, they appeared in entries of their own. The entry is rewritten for clarity. The argument list for all these functions is explicitly declared as void. chgat() ENHANCED CURSES Curses Interfaces NAME chgat, mvchgat, mvwchgat, wchgat - change renditions of characters in a window SYNOPSIS EC #include int chgat(int n, attr_t attr, short color, void *const opts); int mvchgat(int y, int x, int n, attr_t attr, short color, void *const opts); int mvwchgat(WINDOW *win, int y, int x, int n, attr_t attr, short color, void *const opts); int wchgat(WINDOW *win, int n, attr_t attr, short color, void *const opts); ? DESCRIPTION These functions change the renditions of the next n characters in the current or specified window (or of the remaining characters on the line, if n is -1), starting at the current or specified cursor position. The attributes and colors are specified by attr and color as for setcchar(). These functions do not update the cursor. These functions do not perform wrapping. A value of n that is greater than the remaining characters on a line is not an error. The opts argument is reserved for definition in a future edition of this document. Currently, the application must provide a null pointer as opts. RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. SEE ALSO setcchar(), . CHANGE HISTORY First released in Issue 4. Curses Interfaces CURSES clear() NAME clear, erase, wclear, werase - clear a window SYNOPSIS #include int clear(void); int erase(void); int wclear(WINDOW *win); int werase(WINDOW *win); DESCRIPTION The clear(), erase(), wclear() and werase() functions clear every position in the current or specified window. The clear() and wclear() functions also achieve the same effect as calling clearok(), so that the window is cleared completely on the next call to wrefresh() for the window and is redrawn in its entirety. RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. SEE ALSO clearok(), doupdate(), . CHANGE HISTORY First released in Issue 2. Issue 4 The erase() and werase() functions are merged with this entry. In previous issues, they appeared in entries of their own. The entry is rewritten for clarity. The argument list for the clear() and erase() functions is explicitly declared as void. clearok() CURSES Curses Interfaces NAME clearok, idlok, leaveok, scrollok, setscrreg, wsetscrreg - terminal output control functions SYNOPSIS #include int clearok(WINDOW *win, bool bf); int idlok(WINDOW *win, bool bf); int leaveok(WINDOW *win, bool bf); int scrollok(WINDOW *win, bool bf); int setscrreg(int top, int bot); int wsetscrreg(WINDOW *win, int top, int bot); DESCRIPTION These functions set options that deal with output within Curses. The clearok() function assigns the value of bf to an internal flag in the specified window that governs clearing of the screen during a refresh. If, during a refresh operation on the specified window, the flag in curscr is TRUE or the flag in the specified window is TRUE, then the implementation clears the screen, redraws it in its entirety, and sets the flag to FALSE in curscr and in the specified window. The initial state is unspecified. The idlok() function specifies whether the implementation may use the hardware insert-line, delete-line, and scroll features of terminals so equipped. If bf is TRUE, use of these features is enabled. If bf is FALSE, use of these features is disabled and lines are instead redrawn as required. The initial state is FALSE. The leaveok() function controls the cursor position after a refresh operation. If bf is TRUE, refresh operations on the specified window may leave the terminal's cursor at an arbitrary position. If bf is FALSE, then at the end of any refresh operation, the terminal's cursor is positioned at the cursor position contained in the specified window. The initial state is FALSE. The scrollok() function controls the use of scrolling. If bf is TRUE, then scrolling is enabled Curses Interfaces CURSES clearok() for the specified window, with the consequences discussed in Truncation, Wrapping and Scrolling If bf is FALSE, scrolling is disabled for the specified window. The initial state is FALSE. The setscrreg() and wsetscrreg() functions define a software scrolling region in the current or specified window. The top and bot arguments are the line numbers of the first and last line defining the scrolling region. (Line 0 is the top line of the window.) If this option and scrollok() are enabled, an attempt to move off the last line of the margin causes all lines in the scrolling region to scroll one line in the direction of the first line. Only characters in the window are scrolled. If a software scrolling region is set and scrollok() is not enabled, an attempt to move off the last line of the margin does not reposition any lines in the scrolling region. RETURN VALUE Upon successful completion, setscrreg() and wsetscrreg() return OK. Otherwise, they return ERR. The other functions always return OK. ERRORS No errors are defined. APPLICATION USAGE The only reason to enable the idlok() feature is to use scrolling to achieve the visual effect of motion of a partial window, such as for a screen editor. In other cases, the feature can be visually annoying. The leaveok() option provides greater efficiency for applications that do not use the cursor. SEE ALSO clear(), delscreen(), doupdate(), scrl(), . CHANGE HISTORY First released in Issue 2. Issue 4 The idlok(), leaveok(), scrollok(), setscrreq() and wsetscrreq() functions are merged with this entry. In previous issues, they appeared in entries of their own. clearok() CURSES Curses Interfaces The entry is rewritten for clarity. The DESCRIPTION of clearok() is updated to indicate that clearing of a screen applies if the flag is TRUE in either curscr or the specified window. The RETURN VALUE is changed to indicate that the clearok(), leaveok() and scrollok() functions always return OK. Curses Interfaces CURSES clrtobot() NAME clrtobot, wclrtobot - clear from cursor to end of window SYNOPSIS #include int clrtobot(void); int wclrtobot(WINDOW *win); DESCRIPTION The clrtobot() and wclrtobot() functions erase all lines following the cursor in the current or specified window, and erase the current line from the cursor to the end of the line, inclusive. RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. SEE ALSO doupdate(), . CHANGE HISTORY First released in Issue 2. Issue 4 The entry is rewritten for clarity. The argument list for the clrtobot() function is explicitly declared as void. clrtoeol() CURSES Curses Interfaces NAME clrtoeol, wclrtoeol - clear from cursor to end of line SYNOPSIS #include int clrtoeol(void); int wclrtoeol(WINDOW *win); DESCRIPTION The clrtoeol() and wclrtoeol() functions erase the current line from the cursor to the end of the line, inclusive, in the current or specified window. RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. SEE ALSO doupdate(), . CHANGE HISTORY First released in Issue 2. Issue 4 The entry is rewritten for clarity. The argument list for the clrtoeol() function is explicitly declared as void. Curses Interfaces ENHANCED CURSES color_content() NAME color_content - identify red/green/blue intensity of a colour SYNOPSIS EC #include int color_content(short color, short *red, short *green, short *blue); ? DESCRIPTION Refer to can_change_color(). CHANGE HISTORY First released in Issue 4. COLOR_PAIRS ENHANCED CURSES Curses Interfaces NAME COLOR_PAIRS, COLORS - external variables for colour support SYNOPSIS EC #include extern int COLOR_PAIRS; extern int COLORS; ? DESCRIPTION Refer to can_change_color(). CHANGE HISTORY First released in Issue 4. Curses Interfaces ENHANCED CURSES COLS NAME COLS - number of columns on terminal screen SYNOPSIS EC #include extern int COLS; ? DESCRIPTION The external variable COLS indicates the number of columns on the terminal screen. SEE ALSO initscr(), . CHANGE HISTORY First released in Issue 4. copywin() CURSES Curses Interfaces NAME copywin - copy a region of a window SYNOPSIS EC #include int copywin(WINDOW * const srcwin, WINDOW *dstwin, int sminrow, int smincol, int dminrow, int dmincol, int dmaxrow, int dmaxcol, int overlay); ? DESCRIPTION The copywin() function provides a finer granularity of control over the overlay() and overwrite() functions. As in the prefresh() function, a rectangle is specified in the destination window, (dminrow, dmincol) and (dmaxrow, dmaxcol), and the upper-left-corner coordinates of the source window, (sminrow, smincol). If overlay is TRUE, then copying is non-destructive, as in overlay(). If overlay is FALSE, then copying is destructive, as in overwrite(). RETURN VALUE Upon successful completion, copywin() returns OK. Otherwise, it returns ERR. ERRORS No errors are defined. SEE ALSO newpad(), overlay(), . CHANGE HISTORY First released in Issue 4. Curses Interfaces ENHANCED CURSES curscr NAME curscr - current window SYNOPSIS EC #include extern WINDOW *curscr; ? DESCRIPTION The external variable curscr points to an internal data structure. It can be specified as an argument to certain functions, such as clearok(), where permitted in this specification. SEE ALSO clearok(), . CHANGE HISTORY First released in Issue 4. curs_set() ENHANCED CURSES Curses Interfaces NAME curs_set - set the cursor mode SYNOPSIS EC #include int curs_set(int visibility); ? DESCRIPTION The curs_set() function sets the appearance of the cursor based on the value of visibility: Value of visibility Appearance of Cursor 0 Invisible 1 Terminal-specific normal mode 2 Terminal-specific high visibility mode The terminal does not necessarily support all the above values. RETURN VALUE If the terminal supports the cursor mode specified by visibility, then curs_set() returns the previous cursor state. Otherwise, the function returns ERR. ERRORS No errors are defined. SEE ALSO . CHANGE HISTORY First released in Issue 4. Curses Interfaces ENHANCED CURSES cur_term NAME cur_term - current terminal information SYNOPSIS EC #include extern TERMINAL *cur_term; ? DESCRIPTION The external variable cur_term identifies the record in the terminfo database associated with the terminal currently in use. SEE ALSO set_curterm(), tigetflag(), . CHANGE HISTORY First released in Issue 4. def_prog_mode() CURSES Curses Interfaces NAME def_prog_mode, def_shell_mode, reset_prog_mode, reset_shell_mode - save/restore program or shell terminal modes SYNOPSIS #include int def_prog_mode(void); int def_shell_mode(void); int reset_prog_mode(void); int reset_shell_mode(void); DESCRIPTION The def_prog_mode() function saves the current terminal modes as the ``program'' (in Curses) state for use by reset_prog_mode(). The def_shell_mode() function saves the current terminal modes as the ``shell'' (not in Curses) state for use by reset_shell_mode(). The reset_prog_mode() function restores the terminal to the ``program'' (in Curses) state. The reset_shell_mode() function restores the terminal to the ``shell'' (not in Curses) state. These functions affect the mode of the terminal associated with the current screen. RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. APPLICATION USAGE The initscr() function achieves the effect of calling def_shell_mode() to save the prior terminal settings so they can be restored during the call to endwin(), and of calling def_prog_mode() to specify an initial definition of the program terminal mode. Applications normally do not need to refer to the shell terminal mode. Applications may find it useful to save and restore the program terminal mode. Curses Interfaces CURSES def_prog_mode() SEE ALSO doupdate(), endwin(), initscr(), . CHANGE HISTORY First released in Issue 2. Issue 4 The reset_prog_mode() and reset_shell_mode() functions are merged with this entry. In previous issues, they appeared in entries of their own. The entry is rewritten for clarity. The argument list for all these functions is explicitly declared as void. delay_output() CURSES Curses Interfaces NAME delay_output - delay output SYNOPSIS #include int delay_output(int ms); DESCRIPTION On terminals that support pad characters, delay_output() pauses the output for at least ms milliseconds. Otherwise, the length of the delay is unspecified. RETURN VALUE Upon successful completion, delay_output() returns OK. Otherwise, it returns ERR. ERRORS No errors are defined. APPLICATION USAGE Whether or not the terminal supports pad characters, the delay_output() function is not a precise method of timekeeping. SEE ALSO Section 6.1.3, napms(), . CHANGE HISTORY First released in Issue 2. Issue 4 The entry is rewritten for clarity. Curses Interfaces CURSES delch() NAME delch, mvdelch, mvwdelch, wdelch - delete a character from a window. SYNOPSIS #include int delch(void); int mvdelch(int y, int x); int mvwdelch(WINDOW *win, int y, int x); int wdelch(WINDOW *win); DESCRIPTION These functions delete the character at the current or specified position in the current or specified window. This function does not change the cursor position. RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. SEE ALSO . CHANGE HISTORY First released in Issue 2. Issue 4 The entry is rewritten for clarity. The argument list for the delch() function is explicitly declared as void. del_curterm() ENHANCED CURSES Curses Interfaces NAME del_curterm, restartterm, set_curterm, setupterm - interfaces to the terminfo database SYNOPSIS EC #include int del_curterm(TERMINAL *oterm); int restartterm(char *term, int fildes, int *errret); TERMINAL *set_curterm(TERMINAL *nterm); int setupterm(char *term, int fildes, int *errret); extern TERMINAL *cur_term; ? DESCRIPTION These functions retrieve information from the terminfo database. To gain access to the terminfo database, setupterm() must be called first. It is automatically called by initscr() and newterm(). The setupterm() function initialises the other functions to use the terminfo record for a specified terminal (which depends on whether use_env() was called). It sets the cur_term external variable to a TERMINAL structure that contains the record from the terminfo database for the specified terminal. The terminal type is the character string term; if term is a null pointer, the environment variable TERM is used. If TERM is not set or if its value is an empty string, then "unknown" is used as the terminal type. The application must set fildes to a file descriptor, open for output, to the terminal device, before calling setupterm(). If errret is not null, the integer it points to is set to one of the following values to report the function outcome: -1 The terminfo database was not found (function fails). 0 The entry for the terminal was not found in terminfo (function fails). 1 Success. If setupterm() detects an error and errret is a null pointer, setupterm() writes a diagnostic message and exits. Curses Interfaces ENHANCED CURSES del_curterm() A simple call to setupterm() that uses all the defaults and sends the output to stdout is: setupterm((char *)0, fileno(stdout), (int *)0); The set_curterm() function sets the variable cur_term to nterm, and makes all of the terminfo boolean, numeric, and string variables use the values from nterm. The del_curterm() function frees the space pointed to by oterm and makes it available for further use. If oterm is the same as cur_term, references to any of the terminfo boolean, numeric, and string variables thereafter may refer to invalid memory locations until setupterm() is called again. The restartterm() function assumes a previous call to setupterm() (perhaps from initscr() or newterm()). It lets the application specify a different terminal type in term and updates the information returned by baudrate() based on fildes, but does not destroy other information created by initscr(), newterm() or setupterm(). RETURN VALUE Upon successful completion, set_curterm() returns the previous value of cur_term. Otherwise, it returns a null pointer. Upon successful completion, the other functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. APPLICATION USAGE An application would call setupterm() if it required access to the terminfo database but did not otherwise need to use Curses. SEE ALSO Section 6.4, baudrate(), erasechar(), has_ic(), longname(), putc(), termattrs(), termname(), tgetent(), tigetflag(), use_env(), . CHANGE HISTORY First released in Issue 4. deleteln() CURSES Curses Interfaces NAME deleteln, wdeleteln - delete lines in a window SYNOPSIS #include int deleteln(void); int wdeleteln(WINDOW *win); DESCRIPTION The deleteln() and wdeleteln() functions delete the line containing the cursor in the current or specified window and move all lines following the current line one line toward the cursor. The last line of the window is cleared. The cursor position does not change. RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. SEE ALSO insdelln(), . CHANGE HISTORY First released in Issue 2. Issue 4 The entry is rewritten for clarity. The argument list for the deleteln() function is explicitly declared as void. Curses Interfaces CURSES delscreen() NAME delscreen - free storage associated with a screen SYNOPSIS EC #include void delscreen(SCREEN *sp); ? DESCRIPTION The delscreen() function frees storage associated with the SCREEN pointed to by sp. RETURN VALUE The delscreen() function does not return a value. ERRORS No errors are defined. SEE ALSO endwin(), initscr(), . CHANGE HISTORY First released in Issue 4. delwin() CURSES Curses Interfaces NAME delwin - delete a window SYNOPSIS #include int delwin(WINDOW *win); DESCRIPTION The delwin() function deletes win, freeing all memory associated with it. The application must delete subwindows before deleting the main window. RETURN VALUE Upon successful completion, delwin() returns OK. Otherwise, it returns ERR. ERRORS No errors are defined. SEE ALSO derwin(), dupwin(), . CHANGE HISTORY First released in Issue 2. Issue 4 The entry is rewritten for clarity. Curses Interfaces CURSES derwin() NAME derwin, newwin, subwin - window creation functions SYNOPSIS #include EC WINDOW *derwin(WINDOW *orig, int nlines, int ncols, int begin_y, int begin_x); WINDOW *newwin(int nlines, int ncols, int begin_y, int begin_x); WINDOW *subwin(WINDOW *orig, int nlines, int ncols, int begin_y, int begin_x); DESCRIPTION EC The derwin() function is the same as subwin(), except that begin_y and begin_x are relative to the origin of the window orig rather than absolute screen positions. ? The newwin() function creates a new window with nlines lines and ncols columns, positioned so that the origin is (begin_y, begin_x). If nlines is zero, it defaults to LINES - begin_y; if ncols is zero, it defaults to COLS - begin_x. The subwin() function creates a new window with nlines lines and ncols columns, positioned so that the origin is at (begin_y, begin_x). (This position is an absolute screen position, not a position relative to the window orig.) If any part of the new window is outside orig, the function fails and the window is not created. RETURN VALUE Upon successful completion, these functions return a pointer to the new window. Otherwise, they return a null pointer. ERRORS No errors are defined. APPLICATION USAGE Before performing the first refresh of a subwindow, portable applications should call touchwin() or touchline() on the parent window. Each window maintains internal descriptions of the screen image and status. The screen image is shared among all windows in the window hierarchy. Refresh operations rely on information on what has changed within a window, which is private to each window. derwin() CURSES Curses Interfaces Refreshing a window, when updates were made to a different window, may fail to perform needed updates because the windows do not share this information. A new full-screen window is created by calling: newwin(0, 0, 0, 0); SEE ALSO delwin(), is_linetouched(), doupdate(), . CHANGE HISTORY First released in Issue 4. Curses Interfaces CURSES doupdate() NAME doupdate, refresh, wnoutrefresh, wrefresh - refresh windows and lines SYNOPSIS #include int doupdate(void); int refresh(void); int wnoutrefresh(WINDOW *win); int wrefresh(WINDOW *win); DESCRIPTION The refresh() and wrefresh() functions refresh the current or specified window. The functions position the terminal's cursor at the cursor position of the window, except that if the leaveok() mode has been enabled, they may leave the cursor at an arbitrary position. The wnoutrefresh() function determines which parts of the terminal may need updating. The doupdate() function sends to the terminal the commands to perform any required changes. RETURN VALUE Upon successful completion, these functions return OK. Otherwise they return ERR. ERRORS No errors are defined. APPLICATION USAGE Refreshing an entire window is typically more efficient than refreshing several subwindows separately. An efficient sequence is to call wnoutrefresh() on each subwindow that has changed, followed by a call to doupdate(), which updates the terminal. The refresh() or wrefresh() function (or wnoutrefresh() followed by doupdate()) must be called to send output to the terminal, as other Curses functions merely manipulate data structures. SEE ALSO clearok(), redrawwin(), . doupdate() CURSES Curses Interfaces CHANGE HISTORY First released in Issue 4. This entry is a merger of the Issue 3 entries refresh() and wnoutrefresh(). The DESCRIPTION is rewritten for clarity and the argument list for the doupdate() and refresh() functions is explicitly declared as void. Otherwise the functionality is identical to that defined in Issue 3. Curses Interfaces ENHANCED CURSES dupwin() NAME dupwin - duplicate a window SYNOPSIS EC #include WINDOW *dupwin(WINDOW *win); ? DESCRIPTION The dupwin() function creates a duplicate of the window win. RETURN VALUE Upon successful completion, dupwin() returns a pointer to the new window. Otherwise, it returns a null pointer. ERRORS No errors are defined. SEE ALSO derwin(), doupdate(), . CHANGE HISTORY First released in Issue 4. echo() CURSES Curses Interfaces NAME echo, noecho - enable/disable terminal echo SYNOPSIS #include int echo(void); int noecho(void); DESCRIPTION The echo() function enables Echo mode for the current screen. The noecho() function disables Echo mode for the current screen. Initially, Echo mode is disabled and the underlying implementation is set to not echo characters. RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. SEE ALSO Section 3.5, getch(), , XBD specification, Section 9.2, Parameters That Can Be Set. CHANGE HISTORY First released in Issue . Issue 4 The entry is rewritten for clarity. The argument list for the echo() and noecho() functions is explicitly declared as void. Curses Interfaces ENHANCED CURSES echochar() NAME echochar, wechochar - echo single-byte character and rendition to a window and refresh SYNOPSIS EC #include int echochar(const chtype ch); int wechochar(WINDOW *win, const chtype ch); ? DESCRIPTION The echochar() function is equivalent to a call to addch() followed by a call to refresh(). The wechochar() function is equivalent to a call to waddch() followed by a call to wrefresh(). RETURN VALUE Upon successful completion, these functions return OK. Otherwise they return ERR. ERRORS No errors are defined. APPLICATION USAGE These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. SEE ALSO addch(), doupdate(), echo_wchar(), . CHANGE HISTORY First released in Issue 4. echo_wchar() ENHANCED CURSES Curses Interfaces NAME echo_wchar, wecho_wchar - write a complex character and immediately refresh the window SYNOPSIS EC #include int echo_wchar(cchar_t *const wch); int wecho_wchar(WINDOW *win, cchar_t *const wch); ? DESCRIPTION The echo_wchar() function is equivalent to calling add_wch() and then calling refresh(). The wecho_wchar() function is equivalent to calling wadd_wch() and then calling wrefresh(). RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. SEE ALSO addch(), add_wch(), doupdate(), . CHANGE HISTORY First released in Issue 4. Curses Interfaces CURSES endwin() NAME endwin - suspend Curses session SYNOPSIS #include int endwin(void); DESCRIPTION The endwin() function restores the terminal after Curses activity by at least restoring the saved shell terminal mode, flushing any output to the terminal and moving the cursor to the first column of the last line of the screen. Refreshing a window resumes program mode. The application must call endwin() for each terminal being used before exiting. If newterm() is called more than once for the same terminal, the first screen created must be the last one for which endwin() is called. RETURN VALUE Upon successful completion, endwin() returns OK. Otherwise, it returns ERR. ERRORS No errors are defined. APPLICATION USAGE The endwin() function does not free storage associated with a screen, so delscreen() should be called after endwin() if a particular screen is no longer needed. To leave Curses mode temporarily, portable applications should call endwin(). Subsequently, to return to Curses mode, they should call doupdate(), refresh() or wrefresh(). SEE ALSO delscreen(), doupdate(), initscr(), isendwin(), . CHANGE HISTORY First released in Issue 2. Issue 4 The entry is rewritten for clarity. The argument list is explicitly declared as void. erase() CURSES Curses Interfaces NAME erase, werase - clear a window SYNOPSIS #include int erase(void); int werase(WINDOW *win); DESCRIPTION Refer to clear(). CHANGE HISTORY First released in Issue 2. Issue 4 The functionality previously described by this entry is moved to the entry for clear(). Curses Interfaces CURSES erasechar() NAME erasechar, erasewchar, killchar, killwchar - terminal environment query functions SYNOPSIS #include char erasechar(void); EC int erasewchar(wchar_t *ch); char killchar(void); EC int killwchar(wchar_t *ch); ? DESCRIPTION The erasechar() function returns the current erase EC character. !The erasewchar() function stores the current erase character in the object pointed to by ch. If no erase character has been defined, the function will fail and the object pointed to by ch will not be changed. ? The killchar() function returns the current line EC kill character. !The killwchar() function stores the current line kill character in the object pointed to by ch. If no line kill character has been defined, the function will fail and the object pointed to by ch will not be changed. ? RETURN VALUE The erasechar() function returns the erase character and killchar() returns the line kill character. The return value is unspecified when these characters are multi-byte characters. EC Upon successful completion, erasewchar() and killwchar() return OK. Otherwise, they return ERR. ? ERRORS No errors are defined. APPLICATION USAGE The erasechar() and killchar() functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. Moreover, they do not reliably indicate cases in which when the erase or line kill character, respectively, has not been defined. The erasechar() CURSES Curses Interfaces erasewchar() and killwchar() functions overcome these limitations. SEE ALSO Section 3.3.3, clearok(), delscreen(), tcgetattr() (in the XSH specification) , . CHANGE HISTORY First released in Issue 2. Issue 4 The killchar() function is merged with this entry. In previous issues, it appeared in an entry of its own. The entry is rewritten for clarity. The argument list for the erasechar() and killchar() functions is explicitly declared as void. The functions erasewchar() and killwchar() are added and marked as an X/Open UNIX Extension. Curses Interfaces ENHANCED CURSES filter() NAME filter - disable use of certain terminal capabilities SYNOPSIS EC #include void filter(void); ? DESCRIPTION The filter() function changes the algorithm for initialising terminal capabilities that assume that the terminal has more than one line. A subsequent call to initscr() or newterm() performs the following additional actions: o Disable use of clear, cud, cud1, cup, cuu1 and vpa o Set the value of the home string to the value of the cr string o Set lines equal to 1. Any call to filter() must precede the call to initscr() or newterm(). RETURN VALUE The filter() function does not return a value. ERRORS No errors are defined. SEE ALSO Section 6.1.3, initscr(), . CHANGE HISTORY First released in Issue 4. flash() CURSES Curses Interfaces NAME flash - flash the screen SYNOPSIS #include int flash(void); DESCRIPTION The flash() function alerts the user. It flashes the screen, or if that is not possible, it sounds the audible alarm on the terminal. If neither signal is possible, nothing happens. RETURN VALUE The flash() function always returns OK. ERRORS No errors are defined. APPLICATION USAGE Nearly all terminals have an audible alarm, but only some can flash the screen. SEE ALSO beep(), . CHANGE HISTORY First released in Issue 4. In previous issues, this function was included in the entry for beep(). It is moved to its own entry in Issue 4, the argument list is explicitly declared as void, and the RETURN VALUE section is changed to indicate that the function always returns OK. Curses Interfaces CURSES flushinp() NAME flushinp - discard input SYNOPSIS #include int flushinp(void); DESCRIPTION The flushinp() function discards (flushes) any characters in the input buffer associated with the current screen. RETURN VALUE The flushinp() function always returns OK. ERRORS No errors are defined. SEE ALSO . CHANGE HISTORY First released in Issue 2. Issue 4 The entry is rewritten for clarity. The argument list for the flushinp() function is explicitly declared as void. getbegyx() CURSES Curses Interfaces NAME getbegyx, getmaxyx, getparyx, getyx - get cursor and window coordinates SYNOPSIS #include EC void getbegyx(WINDOW *win, int y, int x); void getmaxyx(WINDOW *win, int y, int x); void getparyx(WINDOW *win, int y, int x); ? void getyx(WINDOW *win, int y, int x); DESCRIPTION The getyx() macro stores the cursor position of the specified window in y and x. EC The getparyx() macro, if the specified window is a subwindow, stores in y and x the coordinates of the window's origin relative to its parent window. Otherwise, -1 is stored in y and x. The getbegyx() macro stores the absolute screen coordinates of the specified window's origin in y and x. The getmaxyx() macro stores the number of rows of the specified window in y and stores the window's number of columns in x. ? RETURN VALUE No return values are defined. ERRORS No errors are defined. APPLICATION USAGE These interfaces are macros and `&' cannot be used before the y and x arguments. SEE ALSO . CHANGE HISTORY First released in Issue 4. Curses Interfaces ENHANCED CURSES getbkgd() NAME getbkgd - get background character and rendition using a single-byte character SYNOPSIS EC #include chtype getbkgd(WINDOW *win); ? DESCRIPTION Refer to bkgd(). CHANGE HISTORY First released in Issue 4. getbkgrnd() ENHANCED CURSES Curses Interfaces NAME getbkgrnd - get background character and rendition SYNOPSIS EC #include int getbkgrnd(cchar_t *ch); ? DESCRIPTION Refer to bkgrnd(). CHANGE HISTORY First released in Issue 4. Curses Interfaces ENHANCED CURSES getcchar() NAME getcchar - get a wide character string and rendition from a cchar_t SYNOPSIS EC #include int getcchar(cchar_t *const wcval, wchar_t *wch, attr_t *attrs, short *color_pair, void *opts); ? DESCRIPTION When wch is not a null pointer, the getcchar() function extracts information from a cchar_t defined by wcval, stores the character attributes in the object pointed to by attrs, stores the colour pair in the object pointed to by color_pair, and stores the wide character string referenced by wcval into the array pointed to by wch. When wch is a null pointer, getcchar() obtains the number of wide characters in the object pointed to by wcval and does not change the objects pointed to by attrs or color_pair. The opts argument is reserved for definition in a future edition of this document. Currently, the application must provide a null pointer as opts. RETURN VALUE When wch is a null pointer, getcchar() returns the number of wide characters referenced by wcval, including the null terminator. When wch is not a null pointer, getcchar() returns OK upon successful completion, and ERR otherwise. ERRORS No errors are defined. APPLICATION USAGE The wcval argument may be a value generated by a call to setcchar() or by a function that has a cchar_t output argument. If wcval is constructed by any other means, the effect is unspecified. SEE ALSO attroff(), can_change_color(), setcchar(), . CHANGE HISTORY First released in Issue 4. getcchar() ENHANCED CURSES Curses Interfaces Curses Interfaces CURSES getch() NAME getch, wgetch, mvgetch, mvwgetch - get a single-byte character from the terminal SYNOPSIS #include int getch(void); int mvgetch(int y, int x); int mvwgetch(WINDOW *win, int y, int x); int wgetch(WINDOW *win); DESCRIPTION These functions read a single-byte character from the terminal associated with the current or specified window. The results are unspecified if the input is not a single-byte character. If keypad() is enabled, these functions respond to the pressing of a function key by returning the corresponding KEY_ value defined in . Processing of terminal input is subject to the general rules described in Section 3.5. If echoing is enabled, then the character is echoed as though it were provided as an input argument to insch(), except for the following characters: , and the current erase character: The input is interpreted as specified in Section 3.4.3 and then the character at the resulting cursor position is deleted as though delch() were called, except that if the cursor was originally in the first column of the line, then the user is alerted as though beep() were called. The user is alerted as though beep() were called. Information concerning the function keys is not returned to the caller. Function keys If the current or specified window is not a pad, and it has been moved or modified since the last refresh operation, then it will be refreshed before another character is read. RETURN VALUE Upon successful completion, these functions return getch() CURSES Curses Interfaces OK. Otherwise, they return ERR. ERRORS No errors are defined. APPLICATION USAGE Applications should not define the escape key by itself as a single-character function. When using these functions, nocbreak mode (nocbreak()) and echo mode (echo()) should not be used at the same time. Depending on the state of the terminal when each character is typed, the program may produce undesirable results. SEE ALSO Section 3.5, cbreak(), doupdate(), insch(), . CHANGE HISTORY First released in Issue 2. Issue 4 The entry is rewritten for clarity. The argument list for the getch() function is explicitly declared as void. Curses Interfaces ENHANCED CURSES getmaxyx() NAME getmaxyx - get size of a window SYNOPSIS EC #include void getmaxyx(WINDOW *win, int y, int x); ? DESCRIPTION Refer to getbegyx(). CHANGE HISTORY First released in Issue 4. getnstr() CURSES Curses Interfaces NAME getnstr, getstr, mvgetnstr, mvgetstr, mvwgetnstr, mvwgetstr, wgetstr, wgetnstr - get a multi-byte character string from the terminal SYNOPSIS #include EC int getnstr(char *str, int n); int getstr(char *str); EC int mvgetnstr(int y, int x, char *str, int n); int mvgetstr(int y, int x, char *str); EC int mvwgetnstr(WINDOW *win, int y, int x, char *str, int n); int mvwgetstr(WINDOW *win, int y, int x, char *str); EC int wgetnstr(WINDOW *win, char *str, int n); int wgetstr(WINDOW *win, char *str); DESCRIPTION The effect of getstr() is as though a series of calls to getch() were made, until a newline or carriage return is received. The resulting value is EC placed in the area pointed to by str. !The getnstr(), mvgetnstr(), mvwgetnstr() and wgetnstr() functions read at most n bytes, thus preventing a possible overflow of the input buffer. ?The user's erase and kill characters are interpreted, as well as any special keys (such as function keys, home key, clear key, and so on). The mvgetstr() function is identical to getstr() except that it is as though it is a call to move() and then a series of calls to getch(). The mvwgetstr() function is identical to getstr() except it is as though a call to wmove() is made and then a EC series of calls to wgetch(). !The mvgetnstr() function is identical to getnstr() except that it is as though it is a call to move() and then a series of calls to getch(). The mvwgetnstr() function is identical to getnstr() except it is as though a call to wmove() is made and then a series of calls to wgetch(). The getnstr(), wgetnstr(), mvgetnstr() and mvwgetnstr() functions will only return the entire multi-byte sequence associated with a character. If Curses Interfaces CURSES getnstr() the array is large enough to contain at least one character, the functions fill the array with complete characters. If the array is not large enough to contain any complete characters, the function fails. ? RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. APPLICATION USAGE Reading a line that overflows the array pointed to by str with getstr(), mvgetstr(), mvwgetstr() or wgetstr() causes undefined results. The use of getnstr(), mvgetnstr(), mvwgetnstr() or wgetnstr(), respectively, is recommended. SEE ALSO Section 3.5, beep(), getch(), . CHANGE HISTORY First released in Issue 4. In Issue 3, the getstr(), mvgetstr(), mvwgetstr() and wgetstr() functions were described in the addstr() entry. In Issue 4, the DESCRIPTION of these functions is rewritten for clarity and is updated to indicate that they will handle multi-byte sequences correctly. getn_wstr() ENHANCED CURSES Curses Interfaces NAME getn_wstr, get_wstr, mvgetn_wstr, mvget_wstr, mvwgetn_wstr, mvwget_wstr, wgetn_wstr, wget_wstr - get an array of wide characters and function key codes from a terminal SYNOPSIS EC #include int getn_wstr(wint_t *wstr, int n); int get_wstr(wint_t *wstr); int mvgetn_wstr(int y, int x, wint_t *wstr, int n); int mvget_wstr(int y, int x, wint_t *wstr); int mvwgetn_wstr(WINDOW *win, int y, int x, wint_t *wstr, int n); int mvwget_wstr(WINDOW *win, int y, int x, wint_t *wstr); int wgetn_wstr(WINDOW *win, wint_t *wstr, int n); int wget_wstr(WINDOW *win, wint_t *wstr); ? DESCRIPTION The effect of get_wstr() is as though a series of calls to get_wch() were made, until a newline character, end-of-line character, or end-of-file character is processed. An end-of-file character is represented by WEOF, as defined in . A newline or end-of-line is represented as its wchar_t value. In all instances, the end of the string is terminated by a null wchar_t. The resulting values are placed in the area pointed to by wstr. The user's erase and kill characters are interpreted and affect the sequence of characters returned. The effect of wget_wstr() is as though a series of calls to wget_wch() were made. The effect of mvget_wstr() is as though a call to move() and then a series of calls to get_wch() were made. The effect of mvwget_wstr() is as though a call to wmove() and then a series of calls to wget_wch() were made. The effect of mvget_nwstr() is as though a call to move() and then a series of calls to get_wch() were made. The effect of mvwget_nwstr() is as though a call to wmove() and then a series of calls to wget_wch() were made. Curses Interfaces ENHANCED CURSES getn_wstr() The getn_wstr(), mvgetn_wstr(), mvwgetn_wstr() and wgetn_wstr() functions read at most n characters, letting the application prevent overflow of the input buffer. RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. APPLICATION USAGE Reading a line that overflows the array pointed to by wstr with get_wstr(), mvget_wstr(), mvwget_wstr() or wget_wstr() causes undefined results. The use of getn_wstr(), mvgetn_wstr(), mvwgetn_wstr() or wgetn_wstr(), respectively, is recommended. These functions cannot return KEY_ values as there is no way to distinguish a KEY_ value from a valid wchar_t value. SEE ALSO get_wch(), getstr(), , (in the XSH specification), XBD specification, Chapter 9, General Terminal Interface. CHANGE HISTORY First released in Issue 4. getparyx() ENHANCED CURSES Curses Interfaces NAME getparyx - get subwindow origin coordinates SYNOPSIS EC #include void getparyx(WINDOW *win, int y, int x); ? DESCRIPTION Refer to getbegyx(). CHANGE HISTORY First released in Issue 4. Curses Interfaces CURSES getstr() NAME getstr - get a multi-byte character string from the terminal SYNOPSIS #include int getstr(char *str); DESCRIPTION Refer to getnstr(). CHANGE HISTORY First released in Issue 2. Issue 4 The functionality previously described by this entry is moved to the entry for getnstr(). get_wch() ENHANCED CURSES Curses Interfaces NAME get_wch, mvget_wch, mvwget_wch, wget_wch - get a wide character from a terminal SYNOPSIS EC #include int get_wch(wint_t *ch); int mvget_wch(int y, int x, wint_t *ch); int mvwget_wch(WINDOW *win, int y, int x, wint_t *ch); int wget_wch(WINDOW *win, wint_t *ch); ? DESCRIPTION These functions read a character from the terminal associated with the current or specified window. If keypad() is enabled, these functions respond to the pressing of a function key by setting the object pointed to by ch to the corresponding KEY_ value defined in and returning KEY_CODE_YES. Processing of terminal input is subject to the general rules described in Section 3.5. If echoing is enabled, then the character is echoed as though it were provided as an input argument to ins_wch(), except for the following characters: , and the current erase character: The input is interpreted as specified in Section 3.4.3 and then the character at the resulting cursor position is deleted as though delch() were called, except that if the cursor was originally in the first column of the line, then the user is alerted as though beep() were called. The user is alerted as though beep() were called. Information concerning the function keys is not returned to the caller. Function keys If the current or specified window is not a pad, and it has been moved or modified since the last refresh operation, then it will be refreshed before another character is read. RETURN VALUE When these functions successfully report the Curses Interfaces ENHANCED CURSES get_wch() pressing of a function key, they return KEY_CODE_YES. When they successfully report a wide character, they return OK. Otherwise, they return ERR. ERRORS No errors are defined. APPLICATION USAGE Applications should not define the escape key by itself as a single-character function. When using these functions, nocbreak() mode and echo() mode should not be used at the same time. Depending on the state of the terminal when each character is typed, the application may produce undesirable results. SEE ALSO Section 3.5, beep(), cbreak(), ins_wch(), keypad(), move(), , (in the XSH specification). CHANGE HISTORY First released in Issue 4. getwin() ENHANCED CURSES Curses Interfaces NAME getwin, putwin - dump window to, and reload window from, a file SYNOPSIS EC #include WINDOW *getwin(FILE *filep); int putwin(WINDOW *win, FILE *filep); ? DESCRIPTION The getwin() function reads window-related data stored in the file by putwin(). The function then creates and initialises a new window using that data. The putwin() function writes all data associated with win into the stdio stream to which filep points, using an unspecified format. This information can be retrieved later using getwin(). RETURN VALUE Upon successful completion, getwin() returns a pointer to the window it created. Otherwise, it returns a null pointer. Upon successful completion, putwin() returns OK. Otherwise, it returns ERR. ERRORS No errors are defined. SEE ALSO scr_dump(), . CHANGE HISTORY First released in Issue 4. Curses Interfaces ENHANCED CURSES get_wstr() NAME get_wstr - get an array of wide characters and function key codes from a terminal SYNOPSIS EC #include int get_wstr(wchar_t *wstr); ? DESCRIPTION Refer to getn_wstr(). CHANGE HISTORY First released in Issue 4. getyx() CURSES Curses Interfaces NAME getyx - get cursor coordinates SYNOPSIS #include void getyx(WINDOW *win, int y, int x); DESCRIPTION Refer to getbegyx(). CHANGE HISTORY First released in Issue 2. Issue 4 The functionality previously described by this entry is moved to the entry for getbegyx(). Curses Interfaces ENHANCED CURSES halfdelay() NAME halfdelay - control input character delay mode SYNOPSIS EC #include int halfdelay(int tenths); ? DESCRIPTION The halfdelay() function sets the input mode for the current window to Half-Delay Mode and specifies tenths tenths of seconds as the half-delay interval. The tenths argument must be in a range from 1 up to and including 255. RETURN VALUE Upon successful completion, halfdelay() returns OK. Otherwise, it returns ERR. ERRORS No errors are defined. APPLICATION USAGE The application can call nocbreak() to leave Half- Delay mode. SEE ALSO Section 3.5.2, cbreak(), XBD specification, Chapter 9, General Terminal Interface. CHANGE HISTORY First released in Issue 4. has_colors() ENHANCED CURSES Curses Interfaces NAME has_colors - indicate whether terminal supports colours SYNOPSIS EC #include bool has_colors(void); ? DESCRIPTION Refer to can_change_color(). CHANGE HISTORY First released in Issue 4. Curses Interfaces CURSES has_ic() NAME has_ic, has_il - query functions for terminal insert and delete capability SYNOPSIS #include bool has_ic(void); bool has_il(void); DESCRIPTION The has_ic() function indicates whether the terminal has insert- and delete-character capabilities. The has_il() function indicates whether the terminal has insert- and delete-line capabilities, or can simulate them using scrolling regions. RETURN VALUE The has_ic() function returns TRUE if the terminal has insert- and delete-character capabilities. Otherwise, it returns FALSE. The has_il() function returns TRUE if the terminal has insert- and delete-line capabilities. Otherwise, it returns FALSE. ERRORS No errors are defined. APPLICATION USAGE The has_il() function may be used to determine if it would be appropriate to turn on physical scrolling using scrollok(). SEE ALSO . CHANGE HISTORY First released in Issue 2. Issue 4 The has_il() function is merged with this entry. In previous issues, it appeared in an entry of its own. The entry is rewritten for clarity. The argument list for the has_ic() and has_il() functions is explicitly declared as void. hline() ENHANCED CURSES Curses Interfaces NAME hline, mvhline, mvvline, mvwhline, mvwvline, vline, whline, wvline - draw lines from single-byte characters and renditions SYNOPSIS EC #include int hline(chtype ch, int n); int mvhline(int y, int x, chtype ch, int n); int mvvline(int y, int x, chtype ch, int n); int mvwhline(WINDOW *win, int y, int x, chtype ch, int n); int mvwvline(WINDOW *win, int y, int x, chtype ch, int n); int vline(chtype ch, int n); int whline(WINDOW *win, chtype ch, int n); int wvline(WINDOW *win, chtype ch, int n); ? DESCRIPTION These functions draw a line in the current or specified window starting at the current or specified position, using ch. The line is at most n positions long, or as many as fit into the window. These functions do not advance the cursor position. These functions do not perform special character processing. These functions do not perform wrapping. The hline(), mvhline(), mvwhline() and whline() functions draw a line proceeding toward the last column of the same line. The vline(), mvvline(), mvwvline() and wvline() functions draw a line proceeding toward the last line of the window. RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. Curses Interfaces ENHANCED CURSES hline() APPLICATION USAGE These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. SEE ALSO border(), box(), hline_set(), . CHANGE HISTORY First released in Issue 4. hline_set() ENHANCED CURSES Curses Interfaces NAME hline_set, mvhline_set, mvvline_set, mvwhline_set, mvwvline_set, vline_set, whline_set, wvline_set - draw lines from complex characters and renditions SYNOPSIS EC #include int hline_set(cchar_t *const wch, int n); int mvhline_set(int y, int x, cchar_t *const wch, int n); int mvvline_set(int y, int x, cchar_t *const wch, int n); int mvwhline_set(WINDOW *win, int y, int x, cchar_t *const wch, int n); int mvwvline_set(WINDOW *win, int y, int x, cchar_t *const wch, int n); int vline_set(cchar_t *const wch, int n); int whline_set(WINDOW *win, cchar_t *const wch, int n); int wvline_set(WINDOW *win, cchar_t *const wch, int n); ? DESCRIPTION These functions draw a line in the current or specified window starting at the current or specified position, using ch. The line is at most n positions long, or as many as fit into the window. These functions do not advance the cursor position. These functions do not perform special character processing. These functions do not perform wrapping. The hline_set(), mvhline_set(), mvwhline_set() and whline_set() functions draw a line proceeding toward the last column of the same line. The vline_set(), mvvline_set(), mvwvline_set() and wvline_set() functions draw a line proceeding toward the last line of the window. RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. Curses Interfaces ENHANCED CURSES hline_set() SEE ALSO border_set(), . CHANGE HISTORY First released in Issue 4. idcok() ENHANCED CURSES Curses Interfaces NAME idcok - enable or disable use of hardware insert- and delete-character features SYNOPSIS EC #include void idcok(WINDOW *win, bool bf); ? DESCRIPTION The idcok() function specifies whether the implementation may use hardware insert- and delete- character features in win if the terminal is so equipped. If bf is TRUE, use of these features in win is enabled. If bf is FALSE, use of these features in win is disabled. The initial state is TRUE. RETURN VALUE The idcok() function does not return a value. ERRORS No errors are defined. SEE ALSO clearok(), doupdate(), . CHANGE HISTORY First released in Issue 4. Curses Interfaces CURSES idlok() NAME idlok - enable or disable use of terminal insert- and delete-line features SYNOPSIS #include int idlok(WINDOW *win, bool bf); DESCRIPTION Refer to clearok(). CHANGE HISTORY First released in Issue 2. Issue 4 The functionality previously described by this entry is moved to the entry for clearok(). immedok() ENHANCED CURSES Curses Interfaces NAME immedok - enable or disable immediate terminal refresh SYNOPSIS EC #include void immedok(WINDOW *win, bool bf); ? DESCRIPTION The immedok() function specifies whether the screen is refreshed whenever the window pointed to by win is changed. If bf is TRUE, the window is implicitly refreshed on each such change. If bf is FALSE, the window is not implicitly refreshed. The initial state is FALSE. RETURN VALUE The immedok() function does not return a value. ERRORS No errors are defined. APPLICATION USAGE The immedok() function is useful for windows that are used as terminal emulators. SEE ALSO clearok(), doupdate(), . CHANGE HISTORY First released in Issue 4. Curses Interfaces CURSES inch() NAME inch, mvinch, mvwinch, winch - input a single-byte character and rendition from a window SYNOPSIS #include chtype inch(void); chtype mvinch(int y, int x); chtype mvwinch(WINDOW *win, int y, int x); chtype winch(WINDOW *win); DESCRIPTION These functions return the character and rendition, of type chtype, at the current or specified position in the current or specified window. RETURN VALUE Upon successful completion, the functions return the specified character and rendition. Otherwise, they return (chtype)ERR. ERRORS No errors are defined. APPLICATION USAGE These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. SEE ALSO . CHANGE HISTORY First released in Issue 2. Issue 4 The entry is rewritten for clarity. The argument list for the inch() function is explicitly declared as void. inchnstr() ENHANCED CURSES Curses Interfaces NAME inchnstr, inchstr, mvinchnstr, mvinchstr, mvwinchnstr, mvwinchstr, winchnstr, winchstr - input an array of single-byte characters and renditions from a window SYNOPSIS EC #include int inchnstr(chtype *chstr, int n); int inchstr(chtype *chstr); int mvinchnstr(int y, int x, chtype *chstr, int n); int mvinchstr(int y, int x, chtype *chstr); int mvwinchnstr(WINDOW *win, int y, int x, chtype *chstr, int n); int mvwinchstr(WINDOW *win, int y, int x, chtype *chstr); int winchnstr(WINDOW *win, chtype *chstr, int n); int winchstr(WINDOW *win, chtype *chstr); ? DESCRIPTION These functions place characters and renditions from the current or specified window into the array pointed to by chstr, starting at the current or specified position and ending at the end of the line. The inchnstr(), mvinchnstr(), mvwinchnstr() and winchnstr() functions store at most n elements from the current or specified window into the array pointed to by chstr. RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. APPLICATION USAGE Reading a line that overflows the array pointed to by chstr with inchstr(), mvinchstr(), mvwinchstr() or winchstr() causes undefined results. The use of inchnstr(), mvinchnstr(), mvwinchnstr() or winchnstr(), respectively, is recommended. Curses Interfaces ENHANCED CURSES inchnstr() SEE ALSO inch(), . CHANGE HISTORY First released in Issue 4. init_color() ENHANCED CURSES Curses Interfaces NAME init_color, init_pair - redefine specified colour or colour pair SYNOPSIS EC #include int init_color(short color, short red, short green, short blue); int init_pair(short pair, short f, short b); ? DESCRIPTION Refer to can_change_color(). CHANGE HISTORY First released in Issue 4. Curses Interfaces CURSES initscr() NAME initscr, newterm - screen initialisation functions SYNOPSIS #include WINDOW *initscr(void); SCREEN *newterm(char *type, FILE *outfile, FILE *infile); DESCRIPTION The initscr() function determines the terminal type and initialises all implementation data structures. The TERM environment variable specifies the terminal type. The initscr() function also causes the first refresh operation to clear the screen. If errors occur, initscr() writes an appropriate error message to standard error and exits. The only functions that can be called before initscr() or newterm() are filter(), ripoffline(), slk_init(), use_env() and the functions whose prototypes are defined in . Portable applications must not call initscr() twice. The newterm() function can be called as many times as desired to attach a terminal device. The type argument points to a string specifying the terminal type, except that if type is a null pointer, the TERM environment variable is used. The outfile and infile arguments are file pointers for output to the terminal and input from the terminal, respectively. It is unspecified whether Curses modifies the buffering mode of these file pointers. The newterm() function should be called once for each terminal. The initscr() function is equivalent to: newterm(getenv("TERM"), stdout, stdin); return stdscr; If the current disposition for the signals SIGINT, SIGQUIT or SIGTSTP is SIGDFL, then initscr() may also install a handler for the signal, which may remain in effect for the life of the process or until the process changes the disposition of the signal. The initscr() and newterm() functions initialise the cur_term external variable. initscr() CURSES Curses Interfaces RETURN VALUE Upon successful completion, initscr() returns a pointer to stdscr. Otherwise, it does not return. Upon successful completion, newterm() returns a pointer to the specified terminal. Otherwise, it returns a null pointer. ERRORS No errors are defined. APPLICATION USAGE A program that outputs to more than one terminal should use newterm() for each terminal instead of initscr(). A program that needs an indication of error conditions, so it can continue to run in a line-oriented mode if the terminal cannot support a screen-oriented program, would also use this function. Applications should perform any required handling of the SIGINT, SIGQUIT or SIGTSTP signals before calling initscr(). SEE ALSO Section 6.4, delscreen(), doupdate(), del_curterm(), filter(), slk_attroff(), use_env(), . CHANGE HISTORY First released in Issue 2. Issue 4 The newterm() function is merged with this entry. In previous issues, it appeared in an entry of its own. The entry is rewritten for clarity. The argument list for the initscr() function is explicitly declared as void. Curses Interfaces ENHANCED CURSES innstr() NAME innstr, instr, mvinnstr, mvinstr, mvwinnstr, mvwinstr, winnstr, winstr - input a multi-byte character string from a window SYNOPSIS EC #include int innstr(char *str, int n); int instr(char *str); int mvinnstr(int y, int x, char *str, int n); int mvinstr(int y, int x, char *str); int mvwinnstr(WINDOW *win, int y, int x, char *str, int n); int mvwinstr(WINDOW *win, int y, int x, char *str); int winnstr(WINDOW *win, char *str, int n); int winstr(WINDOW *win, char *str); ? DESCRIPTION These functions place a string of characters from the current or specified window into the array pointed to by str, starting at the current or specified position and ending at the end of the line. The innstr(), mvinnstr(), mvwinnstr() and winnstr() functions store at most n bytes in the string pointed to by str. The innstr(), mvinnstr(), mvwinnstr() and winnstr() functions will only store the entire multi-byte sequence associated with a character. If the array is large enough to contain at least one character the array is filled with complete characters. If the array is not large enough to contain any complete characters, the function fails. RETURN VALUE Upon successful completion, instr(), mvinstr(), mvwinstr() and winstr() return OK. Upon successful completion, innstr(), mvinnstr(), mvwinnstr() and winnstr() return the number of characters actually read into the string. innstr() ENHANCED CURSES Curses Interfaces Otherwise, all these functions return ERR. ERRORS No errors are defined. APPLICATION USAGE Since multi-byte characters may be processed, there might not be a one-to-one correspondence between the number of column positions on the screen and the number of bytes returned. These functions do not return rendition information. Reading a line that overflows the array pointed to by str with instr(), mvinstr(), mvwinstr() or winstr() causes undefined results. The use of innstr(), mvinnstr(), mvwinnstr() or winnstr(), respectively, is recommended. SEE ALSO . CHANGE HISTORY First released in Issue 4. Curses Interfaces ENHANCED CURSES innwstr() NAME innwstr, inwstr, mvinnwstr, mvinwstr, mvwinnwstr, mvwinwstr, winnwstr, winwstr - input a string of wide characters from a window SYNOPSIS EC #include int innwstr(wchar_t *wstr, int n); int inwstr(wchar_t *wstr); int mvinnwstr(int y, int x, wchar_t *wstr, int n); int mvinwstr(int y, int x, wchar_t *wstr); int mvwinnwstr(WINDOW *win, int y, int x, wchar_t *wstr, int n); int mvwinwstr(WINDOW *win, int y, int x, wchar_t *wstr); int winnwstr(WINDOW *win, wchar_t *wstr, int n); int winwstr(WINDOW *win, wchar_t *wstr); ? DESCRIPTION These functions place a string of wchar_t characters from the current or specified window into the array pointed to by wstr starting at the current or specified cursor position and ending at the end of the line. These functions will only store the entire wide character sequence associated with a spacing complex character. If the array is large enough to contain at least one complete spacing complex character, the array is filled with complete characters. If the array is not large enough to contain any complete characters this is an error. The innwstr(), mvinnwstr(), mvwinnwstr() and winnwstr() functions store at most n characters in the array pointed to by wstr. RETURN VALUE Upon successful completion, inwstr(), mvinwstr(), mvwinwstr() and winwstr() return OK. Upon successful completion, innwstr(), mvinnwstr(), mvwinnwstr() and winnwstr() return the number of characters actually read into the string. innwstr() ENHANCED CURSES Curses Interfaces Otherwise, all these functions return ERR. ERRORS No errors are defined. APPLICATION USAGE Reading a line that overflows the array pointed to by wstr with inwstr(), mvinwstr(), mvwinwstr() or winwstr() causes undefined results. The use of innwstr(), mvinnwstr(), mvwinnwstr() or winnwstr(), respectively, is recommended. These functions do not return rendition information. SEE ALSO . CHANGE HISTORY First released in Issue 4. Curses Interfaces CURSES insch() NAME insch, mvinsch, mvwinsch, winsch - insert a single- byte character and rendition into a window SYNOPSIS #include int insch(chtype ch); int mvinsch(int y, int x, chtype ch); int mvwinsch(WINDOW *win, int y, int x, chtype ch); int winsch(WINDOW *win, chtype ch); DESCRIPTION These functions insert the character and rendition from ch into the current or specified window at the current or specified position. These functions do not perform wrapping. These functions do not advance the cursor position. These functions perform special-character processing. RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. APPLICATION USAGE These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. SEE ALSO ins_wch(), . CHANGE HISTORY First released in Issue 2. Issue 4 The entry is rewritten for clarity. insdelln() ENHANCED CURSES Curses Interfaces NAME insdelln, winsdelln - delete or insert lines into a window SYNOPSIS EC #include int insdelln(int n); int winsdelln(WINDOW *win, int n); ? DESCRIPTION The insdelln() and winsdelln() functions perform the following actions: o If n is positive, these functions insert n lines into the current or specified window before the current line. The n last lines are no longer displayed. o If n is negative, these functions delete n lines from the current or specified window starting with the current line, and move the remaining lines toward the cursor. The last n lines are cleared. The current cursor position remains the same. RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. SEE ALSO deleteln(), insertln(), . CHANGE HISTORY First released in Issue 4. Curses Interfaces CURSES insertln() NAME insertln, winsertln - insert lines into a window SYNOPSIS #include int insertln(void); int winsertln(WINDOW *win); DESCRIPTION The insertln() and winsertln() functions insert a blank line before the current line in the current or specified window. The bottom line is no longer displayed. The cursor position does not change. RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. SEE ALSO insdelln(), . CHANGE HISTORY First released in Issue 2. Issue 4 The entry is rewritten for clarity. The argument list for the insertln() function is explicitly declared as void. insnstr() ENHANCED CURSES Curses Interfaces NAME insnstr, insstr, mvinsnstr, mvinsstr, mvwinsnstr, mvwinsstr, winsnstr, winsstr - insert a multi-byte character string into a window SYNOPSIS EC #include int insnstr(char *const str, int n); int insstr(char *const str); int mvinsnstr(int y, int x, char *const str, int n); int mvinsstr(int y, int x, char *const str); int mvwinsnstr(WINDOW *win, int y, int x, char *const str, int n); int mvwinsstr(WINDOW *win, int y, int x, char *const str); int winsnstr(WINDOW *win, char *const str, int n); int winsstr(WINDOW *win, char *const str); ? DESCRIPTION These functions insert a character string (as many characters as will fit on the line) before the current or specified position in the current or specified window. These functions do not advance the cursor position. These functions perform special-character processing. The innstr() and innwstr() functions perform wrapping. The instr() and () inswstr functions do not perform wrapping. The insnstr(), mvinsnstr(), mvwinsnstr() and winsnstr() functions insert at most n bytes. If n is less than 1, the entire string is inserted. RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. APPLICATION USAGE Since the string may contain multi-byte characters, there might not be a one-to-one correspondence between the number of column positions occupied by Curses Interfaces ENHANCED CURSES insnstr() the characters and the number of bytes in the string. SEE ALSO . CHANGE HISTORY First released in Issue 4. ins_nwstr() ENHANCED CURSES Curses Interfaces NAME ins_nwstr, ins_wstr, mvins_nwstr, mvins_wstr, mvwins_nwstr, mvwins_wstr, wins_nwstr, wins_wstr - insert a wide-character string into a window SYNOPSIS EC #include int ins_nwstr(wchar_t *const wstr, int n); int ins_wstr(wchar_t *const wstr); int mvins_nwstr(int y, int x, wchar_t *const wstr, int n); int mvins_wstr(int y, int x, wchar_t *const wstr); int mvwins_nwstr(WINDOW *win, int y, int x, wchar_t *const wstr, int n); int mvwins_wstr(WINDOW *win, int y, int x, wchar_t *const wstr); int wins_nwstr(WINDOW *win, wchar_t *const wstr, int n); int wins_wstr(WINDOW *win, wchar_t *const wstr); ? DESCRIPTION These functions insert a wchar_t character string (as many wchar_t characters as will fit on the line) in the current or specified window immediately before the current or specified position. Any non-spacing characters in the string are associated with the first spacing character in the string that precedes the non-spacing characters. If the first character in the string is a non-spacing character, these functions will fail. These functions do not perform wrapping. These functions do not advance the cursor position. These functions perform special-character processing. The ins_nwstr(), mvins_nwstr(), mvwins_nwstr() and wins_nwstr() functions insert at most n wchar_t characters. If n is less than 1, then the entire string is inserted. RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. Curses Interfaces ENHANCED CURSES ins_nwstr() SEE ALSO . CHANGE HISTORY First released in Issue 4. insstr() ENHANCED CURSES Curses Interfaces NAME insstr - insert a multi-byte character string into the current window SYNOPSIS EC #include int insstr(char *const str); ? DESCRIPTION Refer to insnstr(). CHANGE HISTORY First released in Issue 4. Curses Interfaces ENHANCED CURSES instr() NAME instr - input a multi-byte character string from the current window SYNOPSIS EC #include int instr(char *str); ? DESCRIPTION Refer to innstr(). CHANGE HISTORY First released in Issue 4. ins_wch() ENHANCED CURSES Curses Interfaces NAME ins_wch, mvins_wch, mvwins_wch, wins_wch - insert a complex character and rendition into a window SYNOPSIS EC #include int ins_wch(cchar_t *const wch); int wins_wch(WINDOW *win, cchar_t *const wch); int mvins_wch(int y, int x, cchar_t *const wch); int mvwins_wch(WINDOW *win, int y, int x, cchar_t *const wch); ? DESCRIPTION These functions insert the complex character wch with its rendition in the current or specified window at the current or specified cursor position. These functions do not perform wrapping. These functions do not advance the cursor position. These functions perform special-character processing. RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. APPLICATION USAGE For non-spacing characters, add_wch() can be used to add the non-spacing characters to a spacing complex character already in the window. SEE ALSO add_wch(), . CHANGE HISTORY First released in Issue 4. Curses Interfaces ENHANCED CURSES ins_wstr() NAME ins_wstr - insert a wide-character string into the current window SYNOPSIS EC #include int ins_wstr(wchar_t *const wstr); ? DESCRIPTION Refer to ins_nwstr(). CHANGE HISTORY First released in Issue 4. intrflush() CURSES Curses Interfaces NAME intrflush - enable or disable flush on interrupt SYNOPSIS #include int intrflush(WINDOW *win, bool bf); DESCRIPTION The intrflush() function specifies whether pressing an interrupt key (interrupt, suspend or quit) will flush the input buffer associated with the current screen. If bf is TRUE, pressing an interrupt key will flush this input buffer. If bf is FALSE, pressing an interrupt key will not flush this input buffer. The default for the option is inherited from the display driver settings. The win argument must refer to a window associated with the current screen. RETURN VALUE Upon successful completion, intrflush() returns OK. Otherwise, it returns ERR. ERRORS No errors are defined. APPLICATION USAGE The same effect is achieved outside Curses using the NOFLSH local mode flag specified in the XBD specification (General Terminal Interface). SEE ALSO Section 3.5, , XBD specification, Section 9.2, Parameters That Can Be Set. CHANGE HISTORY First released in Issue 2. Issue 4 The entry is rewritten for clarity. Curses Interfaces ENHANCED CURSES in_wch() NAME in_wch, mvin_wch, mvwin_wch, win_wch - input a complex character and rendition from a window SYNOPSIS EC #include int in_wch(cchar_t *wcval); int mvin_wch(int y, int x, cchar_t *wcval); int mvwin_wch(WINDOW *win, int y, int x, cchar_t *wcval); int win_wch(WINDOW *win, cchar_t *wcval); ? DESCRIPTION These functions extract the complex character and rendition from the current or specified position in the current or specified window into the object pointed to by wcval. RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. SEE ALSO . CHANGE HISTORY First released in Issue 4. in_wchnstr() ENHANCED CURSES Curses Interfaces NAME in_wchnstr, in_wchstr, mvin_wchnstr, mvin_wchstr, mvwin_wchnstr, mvwin_wchstr, win_wchnstr, win_wchstr - input an array of complex characters and renditions from a window SYNOPSIS EC #include int in_wchnstr(cchar_t *wchstr, int n); int in_wchstr(cchar_t *wchstr); int mvin_wchnstr(int y, int x, cchar_t *wchstr, int n); int mvin_wchstr(int y, int x, cchar_t *wchstr); int mvwin_wchnstr(WINDOW *win, int y, int x, cchar_t *wchstr, int n); int mvwin_wchstr(WINDOW *win, int y, int x, cchar_t *wchstr); int win_wchnstr(WINDOW *win, cchar_t *wchstr, int n); int win_wchstr(WINDOW *win, cchar_t *wchstr); ? DESCRIPTION These functions extract characters from the current or specified window, starting at the current or specified position and ending at the end of the line, and place them in the array pointed to by wchstr. The in_wchnstr(), mvin_wchnstr(), mvwin_wchnstr() and win_wchnstr() fill the array with at most n cchar_t elements. RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. APPLICATION USAGE Reading a line that overflows the array pointed to by wchstr with in_wchstr(), mvin_wchstr(), mvwin_wchstr() or win_wchstr() causes undefined results. The use of in_wchnstr(), mvin_wchnstr(), mvwin_wchnstr() or win_wchnstr(), respectively, is recommended. Curses Interfaces ENHANCED CURSES in_wchnstr() SEE ALSO in_wch(), . CHANGE HISTORY First released in Issue 4. inwstr() ENHANCED CURSES Curses Interfaces NAME inwstr - input a string of wide characters from the current window SYNOPSIS EC #include int inwstr(wchar_t *wstr); ? DESCRIPTION Refer to innwstr(). CHANGE HISTORY First released in Issue 4. Curses Interfaces ENHANCED CURSES isendwin() NAME isendwin - determine whether a screen has been refreshed SYNOPSIS EC #include bool isendwin(void); ? DESCRIPTION The isendwin() function indicates whether the screen has been refreshed since the last call to endwin(). RETURN VALUE The isendwin() function returns TRUE if endwin() has been called without any subsequent refresh. Otherwise, it returns FALSE. ERRORS No errors are defined. SEE ALSO endwin(), . CHANGE HISTORY First released in Issue 4. is_linetouched() CURSES Curses Interfaces NAME is_linetouched, is_wintouched, touchline, touchwin, untouchwin, wtouchln - window refresh control functions SYNOPSIS #include EC bool is_linetouched(WINDOW *win, int line); bool is_wintouched(WINDOW *win); int touchline(WINDOW *win, int start, int count); int touchwin(WINDOW *win); EC int untouchwin(WINDOW *win); int wtouchln(WINDOW *win, int y, int n, int changed); ? DESCRIPTION The touchwin() function touches the specified window (that is, marks it as having changed more recently EC than the last refresh operation). !The touchline() function only touches count lines, beginning with line start. The untouchwin() function marks all lines in the window as unchanged since the last refresh operation. Calling wtouchln(), if changed is 1, touches n lines in the specified window, starting at line y. If changed is 0, wtouchln() marks such lines as unchanged since the last refresh operation. The is_wintouched() function determines whether the specified window is touched. The is_linetouched() function determines whether line line of the specified window is touched. ? RETURN VALUE EC The is_linetouched() and is_wintouched() functions return TRUE if any of the specified lines, or the specified window, respectively, has been touched since the last refresh operation. Otherwise, they return FALSE. ? Upon successful completion, the other functions return OK. Otherwise, they return ERR. Exceptions to this are noted in the preceding function Curses Interfaces CURSES is_linetouched() descriptions. ERRORS No errors are defined. APPLICATION USAGE Calling touchwin() or touchline() is sometimes necessary when using overlapping windows, since a change to one window affects the other window, but the records of which lines have been changed in the other window do not reflect the change. SEE ALSO Section 3.2, doupdate(), . CHANGE HISTORY First released in Issue 4. keyname() ENHANCED CURSES Curses Interfaces NAME keyname, key_name - get name of key SYNOPSIS EC #include char *keyname(int c); char *key_name(wchar_t c); ? DESCRIPTION The keyname() and key_name() functions generate a character string whose value describes the key c. The c argument of keyname() can be an 8-bit character or a key code. The c argument of key_name() must be a wide character. The string has a format according to the first applicable row in the following table: Input Format of Returned String Visible character The same character Control character ^X Meta-character (keyname() only) M-X Key value defined in (keyname() only) KEY_name None of the above UNKNOWN KEY The meta-character notation shown above is used only if meta-characters are enabled. RETURN VALUE Upon successful completion, keyname() returns a pointer to a string as described above. Otherwise, it returns a null pointer. ERRORS No errors are defined. APPLICATION USAGE The return value of keyname() and key_name() may point to a static area which is overwritten by a subsequent call to either of these functions. Applications normally process meta-characters without storing them into a window. If an application stores meta-characters in a window and tries to retrieve them as wide characters, keyname() cannot detect meta-characters, since wide characters Curses Interfaces ENHANCED CURSES keyname() do not support meta-characters. SEE ALSO meta(), . CHANGE HISTORY First released in Issue 4. keypad() CURSES Curses Interfaces NAME keypad - enable/disable abbreviation of function keys SYNOPSIS #include int keypad(WINDOW *win, bool bf); DESCRIPTION The keypad() function controls keypad translation. If bf is TRUE, keypad translation is turned on. If bf is FALSE, keypad translation is turned off. The initial state is FALSE. This function affects the behaviour of any function that provides keyboard input. If the terminal in use requires a command to enable it to transmit distinctive codes when a function key is pressed, then after keypad translation is first enabled, the implementation transmits this command to the terminal before an affected input function tries to read any characters from that terminal. RETURN VALUE Upon successful completion, keypad() returns OK. Otherwise, it returns ERR. ERRORS No errors are defined. SEE ALSO Section 3.5.1, . CHANGE HISTORY First released in Issue 2. Issue 4 The entry is rewritten for clarity. Curses Interfaces CURSES killchar() NAME killchar, killwchar - terminal environment query functions SYNOPSIS #include char killchar(void); EC int killwchar(wchar_t *ch); ? DESCRIPTION Refer to erasechar(). CHANGE HISTORY First released in Issue 2. Issue 4 The functionality previously described by this entry is moved to the entry for erasechar(). leaveok() CURSES Curses Interfaces NAME leaveok - control cursor position resulting from refresh operations SYNOPSIS #include int leaveok(WINDOW *win, bool bf); DESCRIPTION Refer to clearok(). CHANGE HISTORY First released in Issue 2. Issue 4 The functionality previously described by this entry is moved to the entry for clearok(). Curses Interfaces ENHANCED CURSES LINES NAME LINES - number of lines on terminal screen SYNOPSIS EC #include extern int LINES; ? DESCRIPTION The external variable LINES indicates the number of lines on the terminal screen. SEE ALSO initscr(), . CHANGE HISTORY First released in Issue 4. longname() CURSES Curses Interfaces NAME longname - get verbose description of current terminal SYNOPSIS #include char *longname(void); DESCRIPTION The longname() function generates a verbose description of the current terminal. The maximum length of a verbose description is 128 bytes. It is defined only after the call to initscr() or newterm(). RETURN VALUE Upon successful completion, longname() returns a pointer to the description specified above. Otherwise, it returns a null pointer on error. ERRORS No errors are defined. APPLICATION USAGE The return value of longname() may point to a static area which is overwritten by a subsequent call to newterm(). SEE ALSO initscr(), . CHANGE HISTORY First released in Issue 2. Issue 4 The entry is rewritten for clarity. The argument list for the longname() function is explicitly declared as void. Curses Interfaces ENHANCED CURSES meta() NAME meta - enable/disable meta-keys SYNOPSIS EC #include int meta(WINDOW *win, bool bf); ? DESCRIPTION Initially, whether the terminal returns 7 or 8 significant bits on input depends on the control mode of the display driver (see the XBD specification, General Terminal Interface). To force 8 bits to be returned, invoke meta(win, TRUE). To force 7 bits to be returned, invoke meta(win, FALSE). The win argument is always ignored. If the terminfo capabilities smm (meta_on) and rmm (meta_off) are defined for the terminal, smm is sent to the terminal when meta(win, TRUE) is called and rmm is sent when meta(win, FALSE) is called. RETURN VALUE Upon successful completion, meta() returns OK. Otherwise, it returns ERR. ERRORS No errors are defined. APPLICATION USAGE The same effect is achieved outside Curses using the CS7 or CS8 control mode flag specified in the XBD specification (General Terminal Interface). The meta() function was designed for use with terminals with 7-bit character sets and a ``meta'' key that could be used to set the eighth bit. SEE ALSO Section 3.5, getch(), , XBD specification, Section 9.2, Parameters That Can Be Set (ISTRIP flag). CHANGE HISTORY First released in Issue 4. move() CURSES Curses Interfaces NAME move, wmove - window cursor location functions SYNOPSIS #include int move(int y, int x); int wmove(WINDOW *win, int y, int x); DESCRIPTION The move() and wmove() functions move the cursor associated with the current or specified window to (y, x) relative to the window's origin. This function does not move the terminal's cursor until the next refresh operation. RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. SEE ALSO doupdate(), . CHANGE HISTORY First released in Issue 2. Issue 4 The entry is rewritten for clarity. Curses Interfaces CURSES mv NAME mv - pointer page for functions with mv prefix DESCRIPTION Most cases in which a Curses function has the mv prefix1 indicate that the function takes y and x arguments and moves the cursor to that address as though move() were first called. (The corresponding functions without the mv prefix operate at the cursor position.) The mv prefix is combined with a w prefix to produce Curses functions beginning with mvw. The mv and mvw functions are discussed together with the corresponding functions that do not have these prefixes. They are found on the following entries: Function Refer to mvaddch() mvwaddch() addch() mvaddchnstr() mvwaddchnstr() addchstr() mvaddchstr() mvwaddchstr() addchstr() mvaddnstr() mvwaddnstr() addnstr() mvaddstr() mvwaddstr() addnstr() mvaddnwstr() mvwaddnwstr() addnwstr() mvaddwstr() mvwaddwstr() addnwstr() mvadd_wch() mvwadd_wch() add_wch() mvadd_wchnstr() mvwadd_wchnstr() add_wchnstr() mvadd_wchstr() mvwadd_wchstr() add_wchnstr() mvchgat() mvwchgat() chgat() mvdelch() mvwdelch() delch() __________ 1. The mvcur(), mvderwin() and mvwin() functions are exceptions to this rule, in that mv is not a prefix with the usual meaning and there are no corresponding functions without the mv prefix. These functions have entries under their own names. In the mvprintw() and mvscanw() functions, mv is a prefix with the usual meaning, but the functions have entries under their own names because the mv function is the first function in the family of functions in alphabetical order. mv CURSES Curses Interfaces Function Refer to mvgetch() mvwgetch() getch() mvgetnstr() mvwgetnstr() getnstr() mvgetstr() mvwgetstr() getnstr() mvgetn_wstr() mvwgetn_wstr() getn_wstr() mvget_wch() mvwget_wch() get_wch() mvget_wstr() mvwget_wstr() getn_wstr() mvhline() mvwhline() hline() mvhline_set() mvwhline_set() hline_set() mvinch() mvwinch() inch() mvinchnstr() mvwinchnstr() inchnstr() mvinchstr() mvwinchstr() inchnstr() mvinnstr() mvwinnstr() innstr() mvinnwstr() mvwinnwstr() innwstr() mvinsch() mvwinsch() insch() mvinsnstr() mvwinsnstr() insnstr() mvinsstr() mvwinsstr() insnstr() mvinstr() mvwinstr() innstr() mvins_nwstr() mvwins_nwstr() ins_nwstr() mvins_wch() mvwins_wch() ins_wch() mvins_wstr() mvwins_wstr() ins_nwstr() mvinwstr() mvwinwstr() innwstr() mvin_wch() mvwin_wch() in_wch() mvin_wchnstr() mvwin_wchnstr() in_wchnstr() mvin_wchstr() mvwin_wchstr() in_wchnstr() mvprintw() mvwprintw() amvprintw() mvscanw() mvwscanw() mvscanw() mvvline() mvwvline() hline() mvvline_set() mvwvline_set() hline_set() SEE ALSO w. CHANGE HISTORY First released in Issue 4. Curses Interfaces ENHANCED CURSES mvcur() NAME mvcur - output cursor movement commands to the terminal SYNOPSIS EC #include int mvcur(int oldrow, int oldcol, int newrow, int newcol); ? DESCRIPTION The mvcur() function outputs one or more commands to the terminal that move the terminal's cursor to (newrow, newcol), an absolute position on the terminal screen. The (oldrow, oldcol) arguments specify the former cursor position. Specifying the former position is necessary on terminals that do not provide coordinate-based movement commands. On terminals that provide these commands, Curses may select a more efficient way to move the cursor based on the former position. If (newrow, newcol) is not a valid address for the terminal in use, mvcur() fails. If (oldrow, oldcol) is the same as (newrow, newcol), then mvcur() succeeds without taking any action. If mvcur() outputs a cursor movement command, it updates its information concerning the location of the cursor on the terminal. RETURN VALUE Upon successful completion, mvcur() returns OK. Otherwise, it returns ERR. ERRORS No errors are defined. APPLICATION USAGE After use of mvcur(), the model Curses maintains of the state of the terminal might not match the actual state of the terminal. The application should touch and refresh the window before resuming conventional use of Curses. SEE ALSO doupdate(), is_linetouched(), . CHANGE HISTORY First released in Issue 4. mvderwin() ENHANCED CURSES Curses Interfaces NAME mvderwin - define window coordinate transformation SYNOPSIS EC #include int mvderwin(WINDOW *win, int par_y, int par_x); ? DESCRIPTION The mvderwin() function specifies a mapping of characters. The function identifies a mapped area of the parent of the specified window, whose size is the same as the size of the specified window and whose origin is at (par_y, par_x) of the parent window. o During any refresh of the specified window, the characters displayed in that window's display area of the terminal are taken from the mapped area. o Any references to characters in the specified window obtain or modify characters in the mapped area. That is, mvderwin() defines a coordinate transformation from each position in the mapped area to a corresponding position (same y, x offset from the origin) in the specified window. RETURN VALUE Upon successful completion, mvderwin() returns OK. Otherwise, it returns ERR. ERRORS No errors are defined. SEE ALSO derwin(), doupdate(), dupwin(), . CHANGE HISTORY First released in Issue 4. Curses Interfaces CURSES mvprintw() NAME mvprintw, mvwprintw, printw, wprintw - print formatted output in window SYNOPSIS #include int mvprintw(int y, int x, char *fmt, ...); int mvwprintw(WINDOW *win, int y, int x, char *fmt, ...); int printw(char *fmt, ...); int wprintw(WINDOW *win, char *fmt, ...); DESCRIPTION The mvprintw(), mvwprintw(), printw() and wprintw() functions are analogous to printf(). The effect of these functions is as though sprintf() were used to format the string, and then waddstr() were used to add that multi-byte string to the current or specified window at the current or specified cursor position. RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. SEE ALSO addnstr(), fprintf() (in the XSH specification), . CHANGE HISTORY First released in Issue 2. Issue 4 The entry is rewritten for clarity and its name is changed from printw() to mvprintw(). mvscanw() CURSES Curses Interfaces NAME mvscanw, mvwscanw, scanw, wscanw - convert formatted input from a window SYNOPSIS #include int mvscanw(int y, int x, char *fmt, ...); int mvwscanw(WINDOW *win, int y, int x, char *fmt, ...); int scanw(char *fmt, ...); int wscanw(WINDOW *win, char *fmt, ...); DESCRIPTION These functions are similar to scanf(). Their effect is as though mvwgetstr() were called to get a multi-byte character string from the current or specified window at the current or specified cursor position, and then sscanf() were used to interpret and convert that string. RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. SEE ALSO getnstr(), printw(), fscanf() (in the XSH specification), wcstombs() (in the XSH specification), . CHANGE HISTORY First released in Issue 2. Issue 4 The entry is rewritten for clarity and its name is changed from scanw() to mvscanw(). Curses Interfaces CURSES mvwin() NAME mvwin - move window SYNOPSIS #include int mvwin(WINDOW *win, int y, int x); DESCRIPTION The mvwin() function moves the specified window so that its origin is at position (y, x). If the move would cause any portion of the window to extend past any edge of the screen, the function fails and the window is not moved. RETURN VALUE Upon successful completion, mvwin() returns OK. Otherwise, it returns ERR. ERRORS No errors are defined. APPLICATION USAGE The application should not move subwindows by calling mvwin(). SEE ALSO derwin(), doupdate(), is_linetouched(), . CHANGE HISTORY First released in Issue 2. Issue 4 The entry is rewritten for clarity. napms() ENHANCED CURSES Curses Interfaces NAME napms - suspend the calling process SYNOPSIS EC #include int napms(int ms); ? DESCRIPTION The napms() function takes at least ms milliseconds to return. RETURN VALUE The napms() function returns OK. ERRORS No errors are defined. APPLICATION USAGE A more reliable method of achieving a timed delay is the usleep() function. SEE ALSO delay_output(), usleep() (in the XSH specification), . CHANGE HISTORY First released in Issue 4. Curses Interfaces CURSES newpad() NAME newpad, pnoutrefresh, prefresh, subpad - pad management functions SYNOPSIS #include WINDOW *newpad(int nlines, int ncols); int pnoutrefresh(WINDOW *pad, int pminrow, int pmincol, int sminrow, int smincol, int smaxrow, int smaxcol); int prefresh(WINDOW *pad, int pminrow, int pmincol, int sminrow, int smincol, int smaxrow, int smaxcol); EC WINDOW *subpad(WINDOW *orig, int nlines, int ncols, int begin_y, int begin_x); ? DESCRIPTION The newpad() function creates a specialised WINDOW data structure representing a pad with nlines lines and ncols columns. A pad is like a window, except that it is not necessarily associated with a viewable part of the screen. Automatic refreshes of pads do not occur. EC The subpad() function creates a subwindow within a pad with nlines lines and ncols columns. Unlike subwin(), which uses screen coordinates, the window is at position (begin_y, begin_x) on the pad. The window is made in the middle of the window orig, so that changes made to one window affect both windows. ? The prefresh() and pnoutrefresh() functions are analogous to wrefresh() and wnoutrefresh() except that they relate to pads instead of windows. The additional arguments indicate what part of the pad and screen are involved. The pminrow and pmincol arguments specify the origin of the rectangle to be displayed in the pad. The sminrow, smincol, smaxrow and smaxcol arguments specify the edges of the rectangle to be displayed on the screen. The lower right-hand corner of the rectangle to be displayed in the pad is calculated from the screen coordinates, since the rectangles must be the same size. Both rectangles must be entirely contained within their respective structures. Negative values of pminrow, pmincol, sminrow or smincol are treated as if they were zero. newpad() CURSES Curses Interfaces RETURN VALUE EC Upon successful completion, the newpad() !and subpad() ?functions return a pointer to the pad data structure. Otherwise, they return a null pointer. Upon successful completion, pnoutrefresh() and prefresh() return OK. Otherwise, they return ERR. ERRORS No errors are defined. APPLICATION USAGE To refresh a pad, call prefresh() or pnoutrefresh(), not wrefresh(). When porting code to use pads from WINDOWS, remember that these functions require additional arguments to specify the part of the pad to be displayed and the location on the screen to be used for the display. Although a subwindow and its parent pad may share memory representing characters in the pad, they need not share status information about what has changed in the pad. Therefore, after modifying a subwindow within a pad, it may be necessary to call touchwin() or touchline() on the pad before calling prefresh(). SEE ALSO derwin(), doupdate(), is_linetouched(), . CHANGE HISTORY First released in Issue 2. Issue 4 The pnoutrefresh() and prefresh() functions are merged with this entry. In previous issues, they appeared in the entry for prefresh(). The subpad() function is new in Issue 4. Curses Interfaces CURSES newterm() NAME newterm - screen initialisation function SYNOPSIS #include SCREEN *newterm(char *type, FILE *outfile, FILE *infile); DESCRIPTION Refer to initscr(). CHANGE HISTORY First released in Issue 2. Issue 4 The functionality previously described by this entry is moved to the entry for initscr(). newwin() CURSES Curses Interfaces NAME newwin - create a new window SYNOPSIS #include WINDOW *newwin(int nlines, int ncols, int begin_y, int begin_x); DESCRIPTION Refer to derwin(). CHANGE HISTORY First released in Issue 2. Issue 4 The functionality previously described by this entry is moved to the entry for derwin(). Curses Interfaces CURSES nl() NAME nl, nonl - enable/disable newline translation SYNOPSIS #include int nl(void); int nonl(void); DESCRIPTION The nl() function enables a mode in which carriage return is translated to newline on input. The nonl() function disables the above translation. Initially, the above translation is enabled. RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. APPLICATION USAGE The default translation adapts the terminal to environments in which newline is the line termination character. However, by disabling the translation with nonl(), the application can sense the pressing of the carriage return key. SEE ALSO . CHANGE HISTORY First released in Issue 2. Issue 4 The entry is rewritten for clarity. The argument list for the nl() and nonl() functions is explicitly declared as void. no CURSES Curses Interfaces NAME no - pointer page for functions with no prefix DESCRIPTION The no prefix indicates that a Curses function disables a mode. (The corresponding functions without the no prefix enable the same mode.) The no functions are discussed together with the corresponding functions that do not have these prefixes.2 They are found on the following entries: Function Refer to nocbreak() cbreak() noecho() echo() nonl() nl() noraw() cbreak() CHANGE HISTORY First released in Issue 4. __________ 2. The nodelay() function has an entry under its own name because there is no corresponding delay() function. The noqiflush() and notimeout() functions have an entry under their own names because they precede the corresponding function without the no prefix in alphabetical order. Curses Interfaces CURSES nodelay() NAME nodelay - enable or disable block during read SYNOPSIS #include int nodelay(WINDOW *win, bool bf); DESCRIPTION The nodelay() function specifies whether Delay Mode or No Delay Mode is in effect for the screen associated with the specified window. If bf is TRUE, this screen is set to No Delay Mode. If bf is FALSE, this screen is set to Delay Mode. The initial state is FALSE. RETURN VALUE Upon successful completion, nodelay() returns OK. Otherwise, it returns ERR. ERRORS No errors are defined. SEE ALSO Section 3.5, getch(), halfdelay(), , XBD specification, Section 9.2, Parameters That Can Be Set. CHANGE HISTORY First released in Issue 2. Issue 4 The entry is rewritten for clarity. noqiflush() ENHANCED CURSES Curses Interfaces NAME noqiflush, qiflush - enable/disable queue flushing SYNOPSIS EC #include void noqiflush(void); void qiflush(void); ? DESCRIPTION The qiflush() function causes all output in the display driver queue to be flushed whenever an interrupt key (interrupt, suspend, or quit) is pressed. The noqiflush() causes no such flushing to occur. The default for the option is inherited from the display driver settings. RETURN VALUE These functions do not return a value. ERRORS No errors are defined. APPLICATION USAGE Calling qiflush() provides faster response to interrupts, but causes Curses to have the wrong idea of what is on the screen. The same effect is achieved outside Curses using the NOFLSH local mode flag specified in the XBD specification (General Terminal Interface). SEE ALSO Section 3.5, intrflush(), , XBD specification, Section 9.2, Parameters That Can Be Set (NOFLSH flag). CHANGE HISTORY First released in Issue 4. Curses Interfaces ENHANCED CURSES notimeout() NAME notimeout, timeout, wtimeout - control blocking on input SYNOPSIS EC #include int notimeout(WINDOW *win, bool bf); void timeout(int delay); void wtimeout(WINDOW *win, int delay); ? DESCRIPTION The notimeout() function specifies whether Timeout Mode or No Timeout Mode is in effect for the screen associated with the specified window. If bf is TRUE, this screen is set to No Timeout Mode. If bf is FALSE, this screen is set to Timeout Mode. The initial state is FALSE. The timeout() and wtimeout() functions set blocking or non-blocking read for the current or specified window based on the value of delay: delay < 0 One or more blocking reads (indefinite waits for input) are used. delay = 0 One or more non-blocking reads are used. Any Curses input function will fail if every character of the requested string is not immediately available. delay > 0 Any Curses input function blocks for delay milliseconds and fails if there is still no input. RETURN VALUE Upon successful completion, the notimeout() function returns OK. Otherwise, it returns ERR. The timeout() and wtimeout() functions do not return a value. ERRORS No errors are defined. SEE ALSO Section 3.5, getch(), halfdelay(), nodelay(), , XBD specification, Section 9.2, Parameters That Can Be Set. notimeout() ENHANCED CURSES Curses Interfaces CHANGE HISTORY First released in Issue 4. Curses Interfaces CURSES overlay() NAME overlay, overwrite - copy overlapped windows SYNOPSIS #include int overlay(WINDOW * const srcwin, WINDOW *dstwin); int overwrite(WINDOW * const srcwin, WINDOW *dstwin); DESCRIPTION The overlay() and overwrite() functions overlay srcwin on top of dstwin. The scrwin and dstwin arguments need not be the same size; only text where the two windows overlap is copied. The overwrite() function copies characters as though a sequence of win_wch() and wadd_wch() were performed with the destination window's attributes and background attributes cleared. The overlay() function does the same thing, except that, whenever a character to be copied is the background character of the source window, overlay() does not copy the character but merely moves the destination cursor the width of the source background character. If any portion of the overlaying window border is not the first column of a multi-column character then all the column positions will be replaced with the background character and rendition before the overlay is done. If the default background character is a multi-column character when this occurs, then these functions fail. RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. SEE ALSO copywin(), . CHANGE HISTORY First released in Issue 2. Issue 4 The entry is rewritten for clarity. The type of argument srcwin() is changed from WINDOW * to overlay() CURSES Curses Interfaces WINDOW *CONST. Curses Interfaces ENHANCED CURSES pair_content() NAME pair_content, PAIR_NUMBER - get information on a colour pair SYNOPSIS EC #include int pair_content(short pair, short *f, short *b); int PAIR_NUMBER(int value); ? DESCRIPTION Refer to can_change_color(). CHANGE HISTORY First released in Issue 4. pechochar() ENHANCED CURSES Curses Interfaces NAME pechochar, pecho_wchar - write a character and rendition and immediately refresh the pad SYNOPSIS EC #include int pechochar(WINDOW *pad, chtype *ch); int pecho_wchar(WINDOW *pad, cchar_t *const wch); ? DESCRIPTION The pechochar() and pecho_wchar() functions output one character to a pad and immediately refresh the pad. They are equivalent to a call to waddch() or wadd_wch(), respectively, followed by a call to prefresh(). The last location of the pad on the screen is reused for the arguments to prefresh(). RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. APPLICATION USAGE The pechochar() function is only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. SEE ALSO echochar(), echo_char(), newpad(), . CHANGE HISTORY First released in Issue 4. Curses Interfaces CURSES pnoutrefresh() NAME pnoutrefresh, prefresh - refresh pads SYNOPSIS #include int pnoutrefresh(WINDOW *pad, int pminrow, int pmincol, int sminrow, int smincol, int smaxrow, int smaxcol); int prefresh(WINDOW *pad, int pminrow, int pmincol, int sminrow, int smincol, int smaxrow, int smaxcol); DESCRIPTION Refer to newpad(). CHANGE HISTORY First released in Issue 2. Issue 4 The functionality previously described by this entry is moved to the entry for newpad(). printw() CURSES Curses Interfaces NAME printw - print formatted output in the current window SYNOPSIS #include int printw(char *fmt, ...); DESCRIPTION Refer to mvprintw(). CHANGE HISTORY First released in Issue 2. Issue 4 The functionality previously described by this entry is moved to the entry for mvprintw(). Curses Interfaces ENHANCED CURSES putp() NAME putp, tputs - output commands to the terminal SYNOPSIS EC #include int putp(char *const str); int tputs(char *const str, int affcnt, int (*putfunc)(int)); ? DESCRIPTION These functions output commands contained in the terminfo database to the terminal. The putp() function is equivalent to tputs(str, 1, putchar). The output of putp() always goes to stdout, not to the fildes specified in setupterm(). The tputs() function outputs str to the terminal. The str argument must be a terminfo string variable or the return value from tgetstr(), tgoto(), tigetstr() or tparm(). The affcnt argument is the number of lines affected, or 1 if not applicable. If the terminfo database indicates that the terminal in use requires padding after any command in the generated string, tputs() inserts pad characters into the string that is sent to the terminal, at positions indicated by the terminfo database. The tputs() function outputs each character of the generated string by calling the user-supplied function putfunc (see below). The user-supplied function putfunc (specified as an argument to tputs()) is either putchar() or some other function with the same prototype. The tputs() function ignores the return value of putfunc. RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. APPLICATION USAGE After use of any of these functions, the model Curses maintains of the state of the terminal might not match the actual state of the terminal. The application should touch and refresh the window before resuming conventional use of Curses. putp() ENHANCED CURSES Curses Interfaces Use of these functions requires that the application contain so much information about a particular class of terminal that it defeats the purpose of using Curses. On some terminals, a command to change rendition conceptually occupies space in the screen buffer (with or without width). Thus, a command to set the terminal to a new rendition would change the rendition of some characters already displayed. SEE ALSO doupdate(), is_linetouched(), putchar() (in the XSH specification), tgetent(), tigetflag(), . CHANGE HISTORY First released in Issue 4. Curses Interfaces ENHANCED CURSES putwin() NAME putwin - dump window to a file SYNOPSIS EC #include int putwin(WINDOW *win, FILE *filep); ? DESCRIPTION Refer to getwin(). CHANGE HISTORY First released in Issue 4. qiflush() ENHANCED CURSES Curses Interfaces NAME qiflush - enable queue flushing SYNOPSIS EC #include void qiflush(void); ? DESCRIPTION Refer to noqiflush(). CHANGE HISTORY First released in Issue 4. Curses Interfaces CURSES raw() NAME raw - set Raw Mode SYNOPSIS #include int raw(void); DESCRIPTION Refer to cbreak(). CHANGE HISTORY First released in Issue 2. Issue 4 The functionality previously described by this entry is moved to the entry for cbreak(). redrawwin() ENHANCED CURSES Curses Interfaces NAME redrawwin, wredrawln - line update status functions SYNOPSIS EC #include int redrawwin(WINDOW *win); int wredrawln(WINDOW *win, int beg_line, int num_lines); ? DESCRIPTION The redrawwin() and wredrawln() functions inform the implementation that some or all of the information physically displayed for the specified window may have been corrupted. The redrawwin() function marks the entire window; wredrawln() marks only num_lines lines starting at line number beg_line. The functions prevent the next refresh operation on that window from performing any optimisation based on assumptions about what is physically displayed there. RETURN VALUE Upon successful completion, these functions return OK. Otherwise they return ERR. ERRORS No errors are defined. APPLICATION USAGE The redrawwin() and wredrawln() functions could be used in a text editor to implement a command that redraws some or all of the screen. SEE ALSO clearok(), doupdate(), . CHANGE HISTORY First released in Issue 4. Curses Interfaces CURSES refresh() NAME refresh - refresh current window SYNOPSIS #include int refresh(void); DESCRIPTION Refer to doupdate(). CHANGE HISTORY First released in Issue 2. Issue 4 The functionality previously described by this entry is moved to the entry for doupdate(). reset_prog_mode() CURSES Curses Interfaces NAME reset_prog_mode, reset_shell_mode - restore program or shell terminal modes SYNOPSIS #include int reset_prog_mode(void); int reset_shell_mode(void); DESCRIPTION Refer to def_prog_mode(). CHANGE HISTORY First released in Issue 2. Issue 4 The functionality previously described by this entry is moved to the entry for def_prog_mode(). Curses Interfaces CURSES resetty() NAME resetty, savetty - save/restore terminal mode SYNOPSIS #include int resetty(void); int savetty(void); DESCRIPTION The resetty() function restores the program mode as of the most recent call to savetty(). The savetty() function saves the state that would be put in place by a call to reset_prog_mode(). RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. SEE ALSO def_prog_mode(), . CHANGE HISTORY First released in Issue 2. Issue 4 The entry is rewritten for clarity. The argument list for the resetty() and savetty() functions is explicitly declared as void. restartterm() ENHANCED CURSES Curses Interfaces NAME restartterm - change terminal type SYNOPSIS EC #include int restartterm(char *term, int fildes, int *errret); ? DESCRIPTION Refer to del_curterm(). CHANGE HISTORY First released in Issue 4. Curses Interfaces ENHANCED CURSES ripoffline() NAME ripoffline - reserve a line for a dedicated purpose SYNOPSIS EC #include int ripoffline(int line, int (*init)(WINDOW *win, int)); ? DESCRIPTION The ripoffline() function reserves a screen line for use by the application. Any call to ripoffline() must precede the call to initscr() or newterm(). If line is positive, one line is removed from the beginning of stdscr; if line is negative, one line is removed from the end. Removal occurs during the subsequent call to initscr() or newterm(). When the subsequent call is made, the function pointed to by init is called with two arguments: a WINDOW pointer to the one-line window that has been allocated and an integer with the number of columns in the window. The initialisation function cannot use the LINES and COLS external variables and cannot call wrefresh() or doupdate(), but may call wnoutrefresh(). Up to five lines can be ripped off. Calls to ripoffline() above this limit have no effect but report success. RETURN VALUE The ripoffline() function returns OK. ERRORS No errors are defined. APPLICATION USAGE Calling slk_init() reduces the size of the screen by one line if initscr() eventually uses a line from stdscr to emulate the soft labels. If slk_init() rips off a line, it thereby reduces by one the number of lines an application can reserve by subsequent calls to ripoffline(). Thus, portable applications that use soft label functions should not call ripoffline() more than four times. When initscr() or newterm() calls the initialisation function pointed to by init, the implementation may pass NULL for the WINDOW pointer argument win. This indicates inability to allocate a one-line window for the line that the call to ripoffline() ripped ripoffline() ENHANCED CURSES Curses Interfaces off. Portable applications should verify that win is not NULL before performing any operation on the window it represents. SEE ALSO doupdate(), initscr(), slk_attroff(), . CHANGE HISTORY First released in Issue 4. Curses Interfaces CURSES savetty() NAME savetty - save terminal mode SYNOPSIS #include int savetty(void); DESCRIPTION Refer to resetty(). CHANGE HISTORY First released in Issue 4. scanw() CURSES Curses Interfaces NAME scanw - convert formatted input from the current window SYNOPSIS #include int scanw(char *fmt, ...); DESCRIPTION Refer to mvscanw(). CHANGE HISTORY First released in Issue 2. Issue 4 The functionality previously described by this entry is moved to the entry for mvscanw(). Curses Interfaces ENHANCED CURSES scr_dump() NAME scr_dump, scr_init, scr_restore, scr_set - screen file input/output functions SYNOPSIS EC #include int scr_dump(char *const filename); int scr_init(char *const filename); int scr_restore(char *const filename); int scr_set(char *const filename); ? DESCRIPTION The scr_dump() function writes the current contents of the virtual screen to the file named by filename in an unspecified format. The scr_restore() function sets the virtual screen to the contents of the file named by filename, which must have been written using scr_dump(). The next refresh operation restores the screen to the way it looked in the dump file. The scr_init() function reads the contents of the file named by filename and uses them to initialise the Curses data structures to what the terminal currently has on its screen. The next refresh operation bases any updates on this information, unless either of the following conditions is true: o The terminal has been written to since the virtual screen was dumped to filename o The terminfo capabilities rmcup and nrrmc are defined for the current terminal. The scr_set() function is a combination of scr_restore() and scr_init(). It tells the program that the information in the file named by filename is what is currently on the screen, and also what the program wants on the screen. This can be thought of as a screen inheritance function. RETURN VALUE On successful completion, these functions return OK. Otherwise, they return ERR. scr_dump() ENHANCED CURSES Curses Interfaces ERRORS No errors are defined. APPLICATION USAGE The scr_init() function is called after initscr() or a system() call to share the screen with another process that has done a scr_dump() after its endwin() call. To read a window from a file, call getwin(); to write a window to a file, call putwin(). SEE ALSO delscreen(), doupdate(), endwin(), getwin(), open() (in the XSH specification), read() (in the XSH specification), write() (in the XSH specification), . CHANGE HISTORY First released in Issue 4. Curses Interfaces CURSES scrl() NAME scrl, scroll, wscrl - scroll a Curses window SYNOPSIS #include EC int scrl(int n); int scroll(WINDOW *win); EC int wscrl(WINDOW *win, int n); ? DESCRIPTION The scroll() function scrolls win one line in the direction of the first line. EC The scrl() and wscrl() functions scroll the current or specified window. If n is positive, the window scrolls n lines toward the first line. Otherwise, the window scrolls -n lines toward the last line. ? These functions do not change the cursor position. If scrolling is disabled for the current or specified window, these functions have no effect. RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. SEE ALSO . CHANGE HISTORY First released in Issue 4. In previous issues, the scroll() function was described in an entry of its own. It has been merged with this entry in Issue 4. Its description has been rewritten for clarity, but otherwise its functionality is identical. scrollok() CURSES Curses Interfaces NAME scrollok - enable or disable scrolling on a window SYNOPSIS #include int scrollok(WINDOW *win, bool bf); DESCRIPTION Refer to clearok(). CHANGE HISTORY First released in Issue 2. Issue 4 The functionality previously described by this entry is moved to the entry for clearok(). Curses Interfaces ENHANCED CURSES setcchar() NAME setcchar - set cchar_t from a wide character string and rendition SYNOPSIS EC #include int setcchar(cchar_t *wcval, wchar_t *const wch, const attr_t attrs, short color_pair, void *const opts); ? DESCRIPTION The setcchar() function initialises the object pointed to by wcval according to the character attributes in attrs, the colour pair in color_pair and the wide character string pointed to by wch. The opts argument is reserved for definition in a future edition of this document. Currently, the application must provide a null pointer as opts. RETURN VALUE Upon successful completion, setcchar() returns OK. Otherwise, it returns ERR. ERRORS No errors are defined. SEE ALSO Section 3.3, attroff(), can_change_color(), getcchar(), . CHANGE HISTORY First released in Issue 4. set_curterm() ENHANCED CURSES Curses Interfaces NAME set_curterm - set current terminal SYNOPSIS EC #include TERMINAL *set_curterm(TERMINAL *nterm); ? DESCRIPTION Refer to del_curterm(). CHANGE HISTORY First released in Issue 4. Curses Interfaces CURSES setscrreg() NAME setscrreg, wsetscrreg - define software scrolling region SYNOPSIS #include int setscrreg(int top, int bot); int wsetscrreg(WINDOW *win, int top, int bot); DESCRIPTION Refer to clearok(). CHANGE HISTORY First released in Issue 2. Issue 4 The functionality previously described by this entry is moved to the entry for clearok(). set_term() CURSES Curses Interfaces NAME set_term - switch between screens SYNOPSIS #include SCREEN *set_term(SCREEN *new); DESCRIPTION The set_term() function switches between different screens. The new argument specifies the new current screen. RETURN VALUE Upon successful completion, set_term() returns a pointer to the previous screen. Otherwise, it returns a null pointer. ERRORS No errors are defined. APPLICATION USAGE This is the only function that manipulates SCREEN pointers; all other functions affect only the current screen. SEE ALSO Section 3.2, initscr(), . CHANGE HISTORY First released in Issue 2. Issue 4 The entry is rewritten for clarity. Curses Interfaces ENHANCED CURSES setupterm() NAME setupterm - access the terminfo database SYNOPSIS EC #include int setupterm(char *term, int fildes, int *errret); ? DESCRIPTION Refer to del_curterm(). CHANGE HISTORY First released in Issue 4. slk_attroff() ENHANCED CURSES Curses Interfaces NAME slk_attroff, slk_attr_off, slk_attron, slk_attr_on, slk_attrset, slk_attr_set, slk_clear, slk_init, slk_label, slk_noutrefresh, slk_refresh, slk_restore, slk_set, slk_touch, slk_wset - soft label functions SYNOPSIS EC #include int slk_attroff(const chtype attrs); int slk_attr_off(const attr_t attrs); int slk_attron(const chtype attrs); int slk_attr_on(const attr_t attrs); int slk_attrset(const chtype attrs); int slk_attr_set(const attr_t attrs); int slk_clear(void); int slk_init(int fmt); char *slk_label(int labnum); int slk_noutrefresh(void); int slk_refresh(void); int slk_restore(void); int slk_set(int labnum, char *const label, int justify); int slk_touch(void); int slk_wset(int labnum, wchar_t *const label, int justify); ? DESCRIPTION The Curses interface manipulates the set of soft function-key labels that exist on many terminals. For those terminals that do not have soft labels, Curses takes over the bottom line of stdscr, reducing the size of stdscr and the value of the LINES external variable. There can be up to eight labels of up to eight display columns each. To use soft labels, slk_init() must be called before initscr(), newterm() or ripoffline() is called. If Curses Interfaces ENHANCED CURSES slk_attroff() initscr() eventually uses a line from stdscr to emulate the soft labels, then fmt determines how the labels are arranged on the screen. Setting fmt to 0 indicates a 3-2-3 arrangement of the labels; 1 indicates a 4-4 arrangement. Other values for fmt are unspecified. The slk_init() function has the effect of calling ripoffline() to reserve one screen line to accommodate the requested format. The slk_set() and slk_wset() functions specify the text of soft label number labnum, within the range from 1 to and including 8. The label argument is the string to be put on the label. With slk_set(), and slk_wset(), the width of the label is limited to eight column positions. A null string or a null pointer specifies a blank label. The justify argument can have the following values to indicate how to justify label within the space reserved for it: 0 Align the start of label with the start of the space 1 Center label within the space 2 Align the end of label with the end of the space The slk_refresh() and slk_noutrefresh() functions correspond to the wrefresh() and wnoutrefresh() functions. The slk_label() function obtains soft label number labnum. The slk_clear() function immediately clears the soft labels from the screen. The slk_restore() function immediately restores the soft labels to the screen after a call to slk_clear(). The slk_touch() function forces all the soft labels to be output the next time slk_noutrefresh() or slk_refresh() is called. The slk_attron(), slk_attrset() and slk_attroff() functions correspond to attron(), attrset(), and attroff(). They have an effect only if soft labels are simulated on the bottom line of the screen. slk_attroff() ENHANCED CURSES Curses Interfaces The slk_attr_off(), slk_attr_on() and slk_attr_set() functions correspond to slk_attroff(), slk_attron() and slk_attrset(), respectively, but take an argument of type attr_t and thus support the attribute constants with the WA_ prefix. RETURN VALUE Upon successful completion, slk_label() returns the requested label with leading and trailing blanks stripped. Otherwise, it returns a null pointer. Upon successful completion, the other functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. APPLICATION USAGE When using multi-byte character sets, applications should check the width of the string by calling mbstowcs() and then wcswidth() before calling slk_set(). When using wide characters, applications should check the width of the string by calling wcswidth() before calling slk_set(). Since the number of columns that a wide character string will occupy is codeset-specific, call wcwidth() and wcswidth() to check the number of column positions in the string before calling slk_wset(). Most applications would use slk_noutrefresh() because a wrefresh() is likely to follow soon. SEE ALSO attr_get(), attroff(), delscreen(), mbstowcs() (in the XSH specification), ripoffline(), wcswidth() (in the XSH specification), . CHANGE HISTORY First released in Issue 4. Curses Interfaces CURSES standend() NAME standend, standout, wstandend, wstandout - set and clear window attributes SYNOPSIS #include int standend(void); int standout(void); int wstandend(WINDOW *win); int wstandout(WINDOW *win); DESCRIPTION The standend() and wstandend() functions turn off all attributes of the current or specified window. The standout() and wstandout() functions turn on the standout attribute of the current or specified window. RETURN VALUE These functions always return 1. ERRORS No errors are defined. SEE ALSO attroff(), attr_get(), . CHANGE HISTORY Derived from the attroff() entry in Issue 3. The entry is reworded for clarity, but otherwise the functionality is identical to previous issues. start_color() ENHANCED CURSES Curses Interfaces NAME start_color - initialise use of colours on terminal SYNOPSIS EC #include int start_color(void); ? DESCRIPTION Refer to can_change_color(). CHANGE HISTORY First released in Issue 4. Curses Interfaces ENHANCED CURSES stdscr NAME stdscr - default window SYNOPSIS EC #include extern WINDOW *stdscr; ? DESCRIPTION The external variable stdscr specifies the default window used by functions that do not specify a window using an argument of type WINDOW *. Other windows may be created using newwin(). SEE ALSO derwin(), . CHANGE HISTORY First released in Issue 4. subpad() ENHANCED CURSES Curses Interfaces NAME subpad - create a subwindow in a pad SYNOPSIS EC #include WINDOW *subpad(WINDOW *orig, int nlines, int ncols, int begin_y, int begin_x); ? DESCRIPTION Refer to newpad(). CHANGE HISTORY First released in Issue 4. Curses Interfaces CURSES subwin() NAME subwin - create a subwindow SYNOPSIS #include WINDOW *subwin(WINDOW *orig, int nlines, int ncols, int begin_y, int begin_x); DESCRIPTION Refer to derwin(). CHANGE HISTORY First released in Issue 2. Issue 4 The functionality previously described by this entry is moved to the entry for derwin(). syncok() ENHANCED CURSES Curses Interfaces NAME syncok, wcursyncup, wsyncdown, wsyncup - synchronise a window with its parents or children SYNOPSIS EC #include int syncok(WINDOW *win, bool bf); void wcursyncup(WINDOW *win); void wsyncdown(WINDOW *win); void wsyncup(WINDOW *win); ? DESCRIPTION The syncok() function determines whether all ancestors of the specified window are implicitly touched whenever there is a change in the window. If bf is TRUE, such implicit touching occurs. If bf is FALSE, such implicit touching does not occur. The initial state is FALSE. The wcursyncup() function updates the current cursor position of the ancestors of win to reflect the current cursor position of win. The wsyncdown() function touches win if any ancestor window has been touched. The wsyncup() function unconditionally touches all ancestors of win. RETURN VALUE Upon successful completion, syncok() returns OK. Otherwise, it returns ERR. The other functions do not return a value. ERRORS No errors are defined. APPLICATION USAGE Applications seldom call wsyncdown() because it is called by all refresh operations. SEE ALSO doupdate(), is_linetouched(), . CHANGE HISTORY First released in Issue 4. Curses Interfaces ENHANCED CURSES syncok() termattrs() ENHANCED CURSES Curses Interfaces NAME termattrs - get supported terminal video attributes SYNOPSIS EC #include attr_t termattrs(void); ? DESCRIPTION The termattrs() function extracts the video attributes of the current terminal. RETURN VALUE The termattrs() function returns a logical OR of all video attributes supported by the terminal. ERRORS No errors are defined. SEE ALSO Section 3.3.3, attroff(), attr_get(), . CHANGE HISTORY First released in Issue 4. Curses Interfaces ENHANCED CURSES termname() NAME termname - get terminal name SYNOPSIS EC #include char *termname(void); ? DESCRIPTION The termname() function obtains the terminal name as recorded by setupterm(). RETURN VALUE The termname() function returns a pointer to the terminal name. ERRORS No errors are defined. SEE ALSO Section 6.1.1, del_curterm(), getenv() (in the XSH specification), initscr(), . CHANGE HISTORY First released in Issue 4. tgetent() ENHANCED CURSES Curses Interfaces NAME tgetent, tgetflag, tgetnum, tgetstr, tgoto - termcap database emulation (TO BE WITHDRAWN) SYNOPSIS EC #include int tgetent(char *bp, char *const name); int tgetflag(char id[2]); int tgetnum(char id[2]); char *tgetstr(char id[2], char **area); char *tgoto(char *const cap, int col, int row); ? DESCRIPTION The tgetent() function looks up the termcap entry for name. The emulation ignores the buffer pointer bp. The tgetflag() function gets the boolean entry for id. The tgetnum() function gets the numeric entry for id. The tgetstr() function gets the string entry for id. If area is not a null pointer and does not point to a null pointer, tgetstr() copies the string entry into the buffer pointed to by *area and advances the variable pointed to by area to the first byte after the copy of the string entry. The tgoto() function instantiates col and row into cap and returns a pointer to the resulting string. All of the information available in the terminfo database need not be available through these functions. RETURN VALUE Upon successful completion, functions that return an integer return OK. Otherwise, they return ERR. Functions that return pointers return a null pointer on error. ERRORS No errors are defined. Curses Interfaces ENHANCED CURSES tgetent() APPLICATION USAGE These functions are included as a conversion aid for programs that use the termcap library. Their arguments are the same and the functions are emulated using the terminfo database. These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. Any terminal capabilities from the terminfo database that cannot be retrieved using these interfaces can be retrieved using the interfaces described on the tigetflg() page. Portable applications must use tputs() to output the strings returned by tgetstr() and tgoto(). SEE ALSO putc(), setupterm(), tigetflg(), . CHANGE HISTORY First released in Issue 4. tigetflag() ENHANCED CURSES Curses Interfaces NAME tigetflag, tigetnum, tigetstr, tparm - retrieve capabilities from the terminfo database SYNOPSIS EC #include int tigetflag(char *capname); int tigetnum(char *capname); char *tigetstr(char *capname); char *tparm(char *cap, long p1, long p2, long p3, long p4, long p5, long p6, long p7, long p8, long p9); ? DESCRIPTION The tigetflag(), tigetnum(), and tigetstr() functions obtain boolean, numeric and string capabilities, respectively, from the selected record of the terminfo database. For each capability, the value to use as capname appears in the Capname column in the table in Section 6.1.3. The tparm() function takes as cap a string capability. If cap is parameterised (as described in Section 6.2.2), tparm() resolves the parameterisation. If the parameterised string refers to parameters %p1 through %p9, then tparm() substitutes the values of p1 through p9, respectively. RETURN VALUE Upon successful completion, tigetflg(), tigetnum() and tigetstr() return the specified capability. The tigetflag() function returns -1 if capname is not a boolean capability. The tigetnum() function returns -2 if capname is not a numeric capability. The tigetstr() function returns (char *)-1 if capname is not a string capability. Upon successful completion, tparm() returns str with parameterisation resolved. Otherwise, it returns a null pointer. ERRORS No errors are defined. APPLICATION USAGE For parameterised string capabilities, the application should pass the return value from Curses Interfaces ENHANCED CURSES tigetflag() tigetstr() to tparm(), as described above. Applications intending to send terminal capabilities directly to the terminal (which should only be done using tputs() or putp()) instead of using Curses, normally should obey the following rules: o Call reset_shell_mode() to restore the display modes before exiting. o If using cursor addressing, output enter_ca_mode upon startup and output exit_ca_mode before exiting. o If using shell escapes, output exit_ca_mode and call reset_shell_mode() before calling the shell; call reset_prog_mode() and output enter_ca_mode after returning from the shell. All parameterised terminal capabilities defined in this document can be passed to tparm(). Some implementations create their own capabilities, create capabilities for non-terminal devices, and redefine the capabilities in this document. These practices are non-conforming because it may be that tparm() cannot parse these user-defined strings. SEE ALSO def_prog_mode(), tgetent(), putp(), . CHANGE HISTORY First released in Issue 4. timeout() ENHANCED CURSES Curses Interfaces NAME timeout - control blocking on input SYNOPSIS EC #include void timeout(int delay); ? DESCRIPTION Refer to notimeout(). CHANGE HISTORY First released in Issue 4. Curses Interfaces CURSES touchline() NAME touchline, touchwin - window refresh control functions SYNOPSIS #include EC int touchline(WINDOW *win, int start, int count); int touchwin(WINDOW *win); DESCRIPTION Refer to is_linetouched(). CHANGE HISTORY First released in Issue 4. tparm() ENHANCED CURSES Curses Interfaces NAME tparm - retrieve capabilities from the terminfo database SYNOPSIS EC #include char *tparm(char *cap, long p1, long p2, long p3, long p4, long p5, long p6, long p7, long p8, long p9); ? DESCRIPTION Refer to tigetflag(). CHANGE HISTORY First released in Issue 4. Curses Interfaces ENHANCED CURSES tputs() NAME tputs - output commands to the terminal SYNOPSIS EC #include int tputs(char *const str, int affcnt, int (*putfunc)(int)); ? DESCRIPTION Refer to putp(). CHANGE HISTORY First released in Issue 4. typeahead() CURSES Curses Interfaces NAME typeahead - control checking for typeahead SYNOPSIS #include int typeahead(int fildes); DESCRIPTION The typeahead() function controls the detection of typeahead during a refresh, based on the value of fildes: o If fildes is a valid file descriptor, typeahead is enabled during refresh; Curses periodically checks fildes for input and aborts the refresh if any character is available. (This is the initial setting, and the typeahead file descriptor corresponds to the input file associated with the screen created by initscr() or newterm().) The value of fildes need not be the file descriptor on which the refresh is occurring. o If fildes is -1, Curses does not check for typeahead during refresh. RETURN VALUE Upon successful completion, typeahead() returns OK. Otherwise, it returns ERR. ERRORS No errors are defined. SEE ALSO Section 3.5, doupdate(), getch(), initscr(), , XBD specification, Section 9.2, Parameters That Can Be Set. CHANGE HISTORY First released in Issue 2. Issue 4 The entry is rewritten for clarity. The RETURN VALUE section now states that the function returns OK on success and ERR on failure. No return values were defined in previous issues. Curses Interfaces CURSES unctrl() NAME unctrl - generate printable representation of a character SYNOPSIS #include char *unctrl(chtype c); DESCRIPTION The unctrl() function generates a character string that is a printable representation of c. If c is a control character, it is converted to the ^X notation. If c contains rendition information, the effect is undefined. RETURN VALUE Upon successful completion, unctrl() returns the generated string. Otherwise, it returns a null pointer. ERRORS No errors are defined. SEE ALSO keyname(), wunctrl(), . CHANGE HISTORY First released in Issue 2. Issue 4 The entry is rewritten for clarity. The RETURN VALUE section now states that the function may return a null pointer. This condition was not specified in previous issues. ungetch() ENHANCED CURSES Curses Interfaces NAME ungetch, unget_wch - push a character onto the input queue SYNOPSIS EC #include int ungetch(int ch); int unget_wch(const wchar_t wch); ? DESCRIPTION The ungetch() function pushes the single-byte character ch onto the head of the input queue. The unget_wch() function pushes the wide character wch onto the head of the input queue. One character of push-back is guaranteed. If these functions are called too many times without an intervening call to getch() or get_wch(), the operation may fail. RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. SEE ALSO Section 3.5, getch(), get_wch(), . CHANGE HISTORY First released in Issue 4. Curses Interfaces ENHANCED CURSES untouchwin() NAME untouchwin - window refresh control function SYNOPSIS EC #include int untouchwin(WINDOW *win); ? DESCRIPTION Refer to is_linetouched(). CHANGE HISTORY First released in Issue 4. use_env() ENHANCED CURSES Curses Interfaces NAME use_env - specify source of screen size information SYNOPSIS EC #include void use_env(char bool); ? DESCRIPTION The use_env() function specifies the technique by which the implementation determines the size of the screen. If bool is FALSE, the implementation uses the values of lines and columns specified in the terminfo database. If bool is TRUE, the implementation uses the LINES and COLUMNS environment variables. The initial value is TRUE. Any call to use_env() must precede calls to initscr(), newterm() or setupterm(). RETURN VALUE The function does not return a value. ERRORS No errors are defined. SEE ALSO del_curterm(), initscr(), . CHANGE HISTORY First released in Issue 4. Curses Interfaces ENHANCED CURSES vidattr() NAME vidattr, vid_attr, vidputs, vid_puts - output attributes to the terminal SYNOPSIS EC #include int vidattr(chtype attr); int vid_attr(attr_t attr); int vidputs(chtype attr, int (*putfunc)(int)); int vid_puts(attr_t attr, wint_t (*putwfunc)(wint_t)); ? DESCRIPTION These functions output commands to the terminal that change the terminal's attributes. If the terminfo database indicates that the terminal in use can display characters in the rendition specified by attr, then vidattr() outputs one or more commands to request that the terminal display subsequent characters in that rendition. The function outputs by calling putchar(). The vidattr() function neither relies on nor updates the model Curses maintains of the prior rendition mode. The vidputs() function computes the same terminal output string that vidattr() does, based on attr, but vidputs() outputs by calling the user-supplied function putfunc. The user-supplied function putfunc (specified as an argument to vidputs()) is either putchar() or some other function with the same prototype. The vidputs() function ignores the return value of putfunc. The vid_attr() and vid_puts() functions correspond to vidattr() and vidputs(), respectively, but take an argument of type attr_t and thus support the attribute constants with the WA_ prefix. The user-supplied function putwfunc (specified as an argument to vid_puts()) is either putwchar() or some other function with the same prototype. The vid_puts() function ignores the return value of putwfunc. vidattr() ENHANCED CURSES Curses Interfaces RETURN VALUE Upon successful completion, these functions return OK. Otherwise, they return ERR. ERRORS No errors are defined. APPLICATION USAGE After use of any of these functions, the model Curses maintains of the state of the terminal might not match the actual state of the terminal. The application should touch and refresh the window before resuming conventional use of Curses. Use of these functions requires that the application contain so much information about a particular class of terminal that it defeats the purpose of using Curses. On some terminals, a command to change rendition conceptually occupies space in the screen buffer (with or without width). Thus, a command to set the terminal to a new rendition would change the rendition of some characters already displayed. SEE ALSO doupdate(), is_linetouched(), putchar() (in the XSH specification), putwchar() (in the XSH specification), tigetflag(), . CHANGE HISTORY First released in Issue 4. Curses Interfaces ENHANCED CURSES vline() NAME vline - draw vertical line SYNOPSIS EC #include int vline(chtype ch, int n); ? DESCRIPTION Refer to hline(). CHANGE HISTORY First released in Issue 4. vline_set() ENHANCED CURSES Curses Interfaces NAME vline_set - draw vertical line from complex character and rendition SYNOPSIS EC #include int vline_set(cchar_t *const ch, int n); ? DESCRIPTION Refer to hline_set(). CHANGE HISTORY First released in Issue 4. Curses Interfaces ENHANCED CURSES vwprintw() NAME vwprintw - print formatted output in window (TO BE WITHDRAWN) SYNOPSIS EC #include #include int vwprintw(WINDOW *win, char *fmt, va_list varglist); ? DESCRIPTION The vwprintw() function achieves the same effect as wprintw() using a variable argument list. The third argument is a va_list, as defined in . RETURN VALUE Upon successful completion, vwprintw() returns OK. Otherwise, it returns ERR. ERRORS No errors are defined. APPLICATION USAGE The vwprintw() function is deprecated because it relies on deprecated functions in the XSH specification. The vw_printw() function is preferred. SEE ALSO mvprintw(), fprintf() (in the XSH specification), vw_printw(), , (in the XSH specification). CHANGE HISTORY First released in Issue 4. vw_printw() ENHANCED CURSES Curses Interfaces NAME vw_printw - print formatted output in window SYNOPSIS EC #include #include int vw_printw(WINDOW *win, char *fmt, va_list varglist); ? DESCRIPTION The vw_printw() function achieves the same effect as wprintw() using a variable argument list. The third argument is a va_list, as defined in . RETURN VALUE Upon successful completion, vw_printw() returns OK. Otherwise, it returns ERR. ERRORS No errors are defined. SEE ALSO mvprintw(), fprintf() (in the XSH specification), , (in the XSH specification). CHANGE HISTORY First released in Issue 4. Curses Interfaces ENHANCED CURSES vwscanw() NAME vwscanw - convert formatted input from a window (TO BE WITHDRAWN) SYNOPSIS EC #include #include int vwscanw(WINDOW *win, char *fmt, va_list varglist); ? DESCRIPTION The vwscanw() function achieves the same effect as wscanw() using a variable argument list. The third argument is a va_list, as defined in . RETURN VALUE Upon successful completion, vwscanw() returns OK. Otherwise, it returns ERR. ERRORS No errors are defined. APPLICATION USAGE The vwscanw() function is deprecated because it relies on deprecated functions in the XSH specification. The vw_scanw() function is preferred. SEE ALSO fscanf() (in the XSH specification), mvscanw(), vw_scanw(), , (in the XSH specification). CHANGE HISTORY First released in Issue 4. vw_scanw() ENHANCED CURSES Curses Interfaces NAME vw_scanw - convert formatted input from a window SYNOPSIS EC #include #include int vw_scanw(WINDOW *win, char *fmt, va_list varglist); ? DESCRIPTION The vw_scanw() function achieves the same effect as wscanw() using a variable argument list. The third argument is a va_list, as defined in . RETURN VALUE Upon successful completion, vw_scanw() returns OK. Otherwise, it returns ERR. ERRORS No errors are defined. SEE ALSO fscanf() (in the XSH specification), mvscanw(), , (in the XSH specification). CHANGE HISTORY First released in Issue 4. Curses Interfaces CURSES w NAME w - pointer page for functions with w prefix DESCRIPTION Most uses of the w prefix indicate that a Curses function takes a win argument that specifies the affected window.3 (The corresponding functions without the w prefix operate on the current window.) The w functions are discussed together with the corresponding functions without the w prefix. They are found on the following entries: Function Refer to waddch() addch() waddchnstr() addchstr() waddchstr() addchstr() waddnstr() addnstr() waddstr() addnstr() waddnwstr() addnwstr() waddwstr() addnwstr() wadd_wch() add_wch() wadd_wchnstr() add_wchnstr() wadd_wchstr() add_wchnstr() wattroff() attroff() wattron() attroff() wattrset() attroff() wattr_get() attr_get() wattr_off() attr_get() wattr_on() attr_get() wattr_set() attr_get() wbkgd() bkgd() wbkgdset() bkgd() wbkgrnd() bkgrnd() wbkgrndset() bkgrnd() wborder() border() wborder_set() border_set() wchgat() chgat() wclear() clear() wclrtobot() clrtobot() __________ 3. The wunctrl() function is an exception to this rule and has an entry under its own name. w CURSES Curses Interfaces Function Refer to wclrtoeol() clrtoeol() wcursyncup() * syncok() wdelch() delch() wdeleteln() deleteln() wechochar() echochar() wecho_wchar() echo_wchar() werase() clear() wgetbkgrnd() bkgrnd() wgetch() getch() wgetnstr() getnstr() wgetn_wstr() getn_wstr() wgetstr() getnstr() wget_wch() get_wch() wget_wstr() getn_wstr() whline() hline() whline_set() hline_set() winch() inch() winchnstr() inchnstr() winchstr() inchnstr() winnstr() innstr() winnwstr() innwstr() winsch() insch() winsdelln() insdelln() winsertln() insertln() winsnstr() insnstr() winsstr() insnstr() winstr() innstr() wins_nwstr() ins_nwstr() wins_wch() ins_wch() wins_wstr() ins_nwstr() winwstr() innwstr() win_wch() in_wch() win_wchnstr() in_wchnstr() win_wchstr() in_wchnstr() wmove() move() wnoutrefresh() * doupdate() wprintw() mvprintw() wredrawln() redrawln() wrefresh() doupdate() wscanw() mvscanw() wscrl() scrl() __________ * There is no corresponding function without the w prefix. Curses Interfaces CURSES w Function Refer to wsetscrreg() clearok() wstandend() standend() wstandout() standend() wsyncdown() * syncok() wsyncup() * syncok() wtimeout() notimeout() wtouchln() * is_linetouch() wvline() hline() wvline_set() hline_set() CHANGE HISTORY First released in Issue 4. __________ * There is no corresponding function without the w prefix. wunctrl() ENHANCED CURSES Curses Interfaces NAME wunctrl - generate printable representation of a wide character SYNOPSIS EC #include wchar_t *wunctrl(cchar_t *wc); ? DESCRIPTION The wunctrl() function generates a wide character string that is a printable representation of the wide character wc. This function also performs the following processing on the input argument: o Control characters are converted to the ^X notation. o Any rendition information is removed. RETURN VALUE Upon successful completion, wunctrl() returns the generated string. Otherwise, it returns a null pointer. ERRORS No errors are defined. SEE ALSO keyname(), unctrl(), . CHANGE HISTORY First released in Issue 4. Chapter 5 Headers This chapter describes the contents of headers used by the Curses functions, macros and external variables. Headers contain the definition of symbolic constants, common structures, preprocessor macros and defined types. Each function in Chapter 4 specifies the headers that an application must include in order to use that function. In most cases only one header is required. These headers are present on an application development system; they do not have to be present on the target execution system. CURSES Headers NAME curses.h - definitions for screen handling and optimisation functions SYNOPSIS #include DESCRIPTION Objects EC The header provides a declaration for COLOR_PAIRS, COLORS, COLS, curscr, LINES and stdscr. Constants The following constants are defined: EOF Function return value for end-of- file ERR Function return value for failure FALSE Boolean false value OK Function return value for success TRUE Boolean true value WEOF Wide-character function return value for end-of-file, as defined in . Data Types The following data types are defined through typedef: EC attr_t An OR-ed set of attributes ? bool Boolean data type EC chtype A character, attributes !and a colour-pair ? SCREEN An opaque terminal representation EC wchar_t As described in ? EC wint_t As described in ? EC cchar_t References a string of wide characters ? WINDOW An opaque window representation These data types are described in more detail in Section 2.4. The inclusion of may make visible all symbols from the headers , , and . Headers CURSES Attribute Bits EC The following symbolic constants are used to manipulate objects of type attr_t: WA_ALTCHARSET Alternate character set WA_BLINK Blinking WA_BOLD Extra bright or bold WA_DIM Half bright WA_HORIZONTAL Horizontal highlight WA_INVIS Invisible WA_LEFT Left highlight WA_LOW Low highlight WA_PROTECT Protected WA_REVERSE Reverse video WA_RIGHT Right highlight WA_STANDOUT Best highlighting mode of the terminal WA_TOP Top highlight WA_UNDERLINE Underlining WA_VERTICAL Vertical highlight These attribute flags shall be distinct. ? The following symbolic constants are used to manipulate attribute bits in objects of type chtype: EC A_ALTCHARSET Alternate character set A_BLINK Blinking A_BOLD Extra bright or bold A_DIM Half bright EC A_INVIS Invisible A_PROTECT Protected A_REVERSE Reverse video A_STANDOUT Best highlighting mode of the terminal A_UNDERLINE Underlining EC These attribute flags need not be distinct !except when _XOPEN_CURSES is defined and the application sets _XOPEN_SOURCE_EXTENDED to 1. ? The following symbolic constants can be used as bit-masks to extract the components of a chtype: A_ATTRIBUTES Bit-mask to extract attributes A_CHARTEXT Bit-mask to extract a character EC A_COLOR Bit-mask to extract colour-pair information ? The following symbolic constants can be used as bit-masks to extract the components of a chtype: CURSES Headers A_ATTRIBUTES Bit-mask to extract attributes A_CHARTEXT Bit-mask to extract a character EC A_COLOR Bit-mask to extract colour-pair information ? Line-Drawing Constants EC The header defines the symbolic constants shown in the leftmost two columns of the following table for use in drawing lines. The symbolic constants that begin with ACS_ are char constants. The symbolic constants that begin with WACS_ are cchar_t constants for use with the wide-character interfaces that take a pointer to a cchar_t. In the POSIX locale, the characters shown in the POSIX Locale Default column are used when the terminal database does not specify a value using the acsc capability as described in Section 6.2.12. POSIX Locale char Constant cchar_t Constant Default Glyph Description EC ACS_ULCORNER WACS_ULCORNER + upper left-hand corner ACS_LLCORNER WACS_LLCORNER + lower left-hand corner ACS_URCORNER WACS_URCORNER + upper right-hand corner ACS_LRCORNER WACS_LRCORNER + lower right-hand corner ACS_RTEE WACS_RTEE + right tee (-|) ACS_LTEE WACS_LTEE + left tee (|-) ACS_BTEE WACS_BTEE + bottom tee (|) ACS_TTEE WACS_TTEE + top tee (|) ACS_HLINE WACS_HLINE - horizontal line ACS_VLINE WACS_VLINE | vertical line ACS_PLUS WACS_PLUS + plus ACS_S1 WACS_S1 - scan line 1 ACS_S9 WACS_S9 _ scan line 9 ACS_DIAMOND WACS_DIAMOND + diamond ACS_CKBOARD WACS_CKBOARD : checker board (stipple) ACS_DEGREE WACS_DEGREE ' degree symbol ACS_PLMINUS WACS_PLMINUS # plus/minus ACS_BULLET WACS_BULLET o bullet ACS_LARROW WACS_LARROW < arrow pointing left ACS_RARROW WACS_RARROW > arrow pointing right ACS_DARROW WACS_DARROW v arrow pointing down ACS_UARROW WACS_UARROW ^ arrow pointing up ACS_BOARD WACS_BOARD # board of squares Headers CURSES ACS_LANTERN WACS_LANTERN # lantern symbol ACS_BLOCK WACS_BLOCK # solid square block ? Colour-related Macros EC The following colour-related macros are defined: ? EC COLOR_PAIR(n) Colour-pair number n PAIR_NUMBER(attrs) Returns the pair number associated with the COLOR_PAIR(n) attribute. COLOR_BLACK COLOR_BLUE COLOR_GREEN COLOR_CYAN COLOR_RED COLOR_MAGENTA COLOR_YELLOW COLOR_WHITE ? Coordinate-related Macros The following coordinate-related macros are defined: EC void getbegyx(WINDOW *win, int y, int x); void getmaxyx(WINDOW *win, int y, int x); void getparyx(WINDOW *win, int y, int x); void getyx(WINDOW *win, int y, int x); CURSES Headers Key Codes The following symbolic constants representing function key values are defined: Key Code Description EC KEY_CODE_YES Used to indicate that a wchar_t variable contains a key code KEY_BREAK Break key KEY_DOWN Down arrow key KEY_UP Up arrow key KEY_LEFT Left arrow key KEY_RIGHT Right arrow key KEY_HOME Home key KEY_BACKSPACE Backspace KEY_F0 Function keys; space for 64 keys is reserved KEY_F(n) For 0_ The virtual keypad is a 3-by-3 keypad arranged as follows: A1 UP A3 LEFT B2 RIGHT C1 DOWN C3 Each legend, such as A1, corresponds to a symbolic constant for a key code from the preceding table, such as KEY_A1. CURSES Headers EC The following symbolic constants representing function key values are also defined: ? Key Code Description KEY_BTAB Back tab key KEY_BEG Beginning key KEY_CANCEL Cancel key KEY_CLOSE Close key KEY_COMMAND Cmd (command) key KEY_COPY Copy key KEY_CREATE Create key KEY_END End key KEY_EXIT Exit key KEY_FIND Find key KEY_HELP Help key KEY_MARK Mark key KEY_MESSAGE Message key KEY_MOVE Move key KEY_NEXT Next object key KEY_OPEN Open key KEY_OPTIONS Options key KEY_PREVIOUS Previous object key KEY_REDO Redo key KEY_REFERENCE Reference key KEY_REFRESH Refresh key KEY_REPLACE Replace key KEY_RESTART Restart key KEY_RESUME Resume key KEY_SAVE Save key KEY_SBEG Shifted beginning key KEY_SCANCEL Shifted cancel key KEY_SCOMMAND Shifted command key KEY_SCOPY Shifted copy key KEY_SCREATE Shifted create key KEY_SDC Shifted delete char key KEY_SDL Shifted delete line key KEY_SELECT Select key KEY_SEND Shifted end key KEY_SEOL Shifted clear line key KEY_SEXIT Shifted exit key KEY_SFIND Shifted find key KEY_SHELP Shifted help key KEY_SHOME Shifted home key KEY_SIC Shifted input key KEY_SLEFT Shifted left arrow key KEY_SMESSAGE Shifted message key KEY_SMOVE Shifted move key Headers CURSES Key Code Description KEY_SNEXT Shifted next key KEY_SOPTIONS Shifted options key KEY_SPREVIOUS Shifted prev key KEY_SPRINT Shifted print key KEY_SREDO Shifted redo key KEY_SREPLACE Shifted replace key KEY_SRIGHT Shifted right arrow KEY_SRSUME Shifted resume key KEY_SSAVE Shifted save key KEY_SSUSPEND Shifted suspend key KEY_SUNDO Shifted undo key KEY_SUSPEND Suspend key KEY_UNDO Undo key CURSES Headers Function Prototypes The following are declared as functions, and may also be defined as macros: int addch(const chtype ch); int addchstr(chtype *const chstr); EC int addchnstr(chtype *const chstr, int n); int addnstr(char *const str, int n); int addstr(char *const str); int addnwstr(wchar_t *const wstr, int n); int addwstr(wchar_t *const wstr); int add_wch(cchar_t *const wch); int add_wchnstr(cchar_t *const wchstr, int n); int add_wchstr(cchar_t *const wchstr); int attroff(int attrs); int attron(int attrs); int attrset(int attrs); EC attr_t attr_get(void); int attr_off(attr_t attrs); int attr_on(attr_t attrs); int attr_set(attr_t attrs); int baudrate(void); int beep(void); EC int bkgd(chtype ch); void bkgdset(chtype ch); void bkgrndset(cchar_t *const wch); int bkgrnd(cchar_t *const wch); int border(chtype ls, chtype rs, chtype ts, chtype bs, chtype tl, chtype tr, chtype bl, chtype br); int border_set(cchar_t *const ls, cchar_t *const rs, cchar_t *const ts, cchar_t *const bs, cchar_t *const tl, cchar_t *const tr, cchar_t *const bl, cchar_t *const br); int box(WINDOW *win, chtype verch, chtype horch); EC int box_set(WINDOW *win, cchar_t *const verch, cchar_t *const horch); bool can_change_color(void); int cbreak(void); EC int chgat(int n, attr_t attr, short color, void *const opts); int clear(void); int clearok(WINDOW *win, bool bf); int clrtobot(void); int clrtoeol(void); EC int color_content(short color, short *red, short *green, short *blue); int COLOR_PAIR(int n); int copywin(WINDOW * const srcwin, WINDOW *dstwin, int sminrow, int smincol, int dminrow, int dmincol, int dmaxrow, int dmaxcol, int overlay); int curs_set(int visibility); int def_prog_mode(void); Headers CURSES int def_shell_mode(void); int delay_output(int ms); int delch(void); EC void delscreen(SCREEN *sp); int delwin(WINDOW *win); int deleteln(void); EC WINDOW *derwin(WINDOW *orig, int nlines, int ncols, int begin_y, int begin_x); int doupdate(void); EC WINDOW *dupwin(WINDOW *win); int echo(void); EC int echochar(const chtype ch); int echo_wchar(cchar_t *const wch); int endwin(void); int erase(void); char erasechar(void); EC int erasewchar(wchar_t *ch); void filter(void); int flash(void); int flushinp(void); EC chtype getbkgd(WINDOW *win); int getbkgrnd(cchar_t *wch); int getcchar(cchar_t *const wcval, wchar_t *wch, attr_t *attrs, short *color_pair, void *opts); int getch(void); EC int getnstr(char *str, int n); int getn_wstr(wint_t *wstr, int n); int getstr(char *str); EC int get_wch(wint_t *ch); WINDOW *getwin(FILE *filep); int get_wstr(wint_t *wstr); int halfdelay(int tenths); bool has_colors(void); bool has_ic(void); bool has_il(void); EC int hline(chtype ch, int n); int hline_set(cchar_t *const wch, int n); void idcok(WINDOW *win, bool bf); int idlok(WINDOW *win, bool bf); EC void immedok(WINDOW *win, bool bf); chtype inch(void); EC int inchnstr(chtype *chstr, int n); int inchstr(chtype *chstr); WINDOW *initscr(void); EC int init_color(short color, short red, short green, short blue); int init_pair(short pair, short f, short b); int innstr(char *str, int n); int innwstr(wchar_t *wstr, int n); CURSES Headers int insch(chtype ch); EC int insdelln(int n); int insertln(void); EC int insnstr(char *const str, int n); int insstr(char *const str); int instr(char *str); int ins_nwstr(wchar_t *const wstr, int n); int ins_wch(cchar_t *const wch); int ins_wstr(wchar_t *const wstr); int intrflush(WINDOW *win, bool bf); EC int in_wch(cchar_t *wcval); int in_wchstr(cchar_t *wchstr); int in_wchnstr(cchar_t *wchstr, int n); int inwstr(wchar_t *wstr); bool isendwin(void); bool is_linetouched(WINDOW *win, int line); bool is_wintouched(WINDOW *win); char *keyname(int c); char *key_name(wchar_t c); int keypad(WINDOW *win, bool bf); char killchar(void); EC int killwchar(wchar_t *ch); int leaveok(WINDOW *win, bool bf); char *longname(void); EC int meta(WINDOW *win, bool bf); int move(int y, int x); int mvaddch(int y, int x, const chtype ch); EC int mvaddchnstr(int y, int x, chtype *const chstr, int n); int mvaddchstr(int y, int x, chtype *const chstr); EC int mvaddnstr(int y, int x, char *const str, int n); int mvaddnwstr(int y, int x, wchar_t *const wstr, int n); int mvaddstr(int y, int x, char *const str); int mvaddwstr(int y, int x, wchar_t *const wstr); int mvadd_wch(int y, int x, cchar_t *const wch); int mvadd_wchnstr(int y, int x, cchar_t *const wchstr, int n); int mvadd_wchstr(int y, int x, cchar_t *const wchstr); int mvchgat(int y, int x, int n, attr_t attr, short color, void *const opts); int mvcur(int oldrow, int oldcol, int newrow, int newcol); int mvdelch(int y, int x); EC int mvderwin(WINDOW *win, int par_y, int par_x); int mvgetch(int y, int x); EC int mvgetnstr(int y, int x, char *str, int n); int mvgetn_wstr(int y, int x, wint_t *wstr, int n); int mvgetstr(int y, int x, char *str); EC int mvget_wch(int y, int x, wint_t *ch); int mvget_wstr(int y, int x, wint_t *wstr); int mvhline(int y, int x, chtype ch, int n); int mvhline_set(int y, int x, cchar_t *const wch, int n); Headers CURSES chtype mvinch(int y, int x); EC int mvinchnstr(int y, int x, chtype *chstr, int n); int mvinchstr(int y, int x, chtype *chstr); int mvinnstr(int y, int x, char *str, int n); int mvinnwstr(int y, int x, wchar_t *wstr, int n); int mvinsch(int y, int x, chtype ch); EC int mvinsnstr(int y, int x, char *const str, int n); int mvinsstr(int y, int x, char *const str); int mvinstr(int y, int x, char *str); int mvins_nwstr(int y, int x, wchar_t *const wstr, int n); int mvins_wch(int y, int x, cchar_t *const wch); int mvins_wstr(int y, int x, wchar_t *const wstr); int mvinwstr(int y, int x, wchar_t *wstr); int mvin_wch(int y, int x, cchar_t *wcval); int mvin_wchnstr(int y, int x, cchar_t *wchstr, int n); int mvin_wchstr(int y, int x, cchar_t *wchstr); int mvprintw(int y, int x, char *fmt, ...); int mvscanw(int y, int x, char *fmt, ...); EC int mvvline(int y, int x, chtype ch, int n); int mvvline_set(int y, int x, cchar_t *const wch, int n); int mvwaddch(WINDOW *win, int y, int x, const chtype ch); EC int mvwaddchnstr(WINDOW *win, int y, int x, chtype *const chstr, int n); int mvwaddchstr(WINDOW *win, int y, int x, chtype *const chstr); EC int mvwaddnstr(WINDOW *win, int y, int x, char *const str, int n); int mvwaddnwstr(WINDOW *win, int y, int x, wchar_t *const wstr, int n); int mvwaddstr(WINDOW *win, int y, int x, char *const str); int mvwaddwstr(WINDOW *win, int y, int x, wchar_t *const wstr); int mvwadd_wch(WINDOW *win, int y, int x, cchar_t *const wch); int mvwadd_wchnstr(WINDOW *win, int y, int x, cchar_t *const wchstr, int n); int mvwadd_wchstr(WINDOW *win, int y, int x, cchar_t *const wchstr); int mvwchgat(WINDOW *win, int y, int x, int n, attr_t attr, short color, void *const opts); int mvwdelch(WINDOW *win, int y, int x); int mvwgetch(WINDOW *win, int y, int x); EC int mvwgetnstr(WINDOW *win, int y, int x, char *str, int n); int mvwgetn_wstr(WINDOW *win, int y, int x, wint_t *wstr, int n); int mvwgetstr(WINDOW *win, int y, int x, char *str); EC int mvwget_wch(WINDOW *win, int y, int x, wint_t *ch); int mvwget_wstr(WINDOW *win, int y, int x, wint_t *wstr); int mvwhline(WINDOW *win, int y, int x, chtype ch, int n); int mvwhline_set(WINDOW *win, int y, int x, cchar_t *const wch, int n); int mvwin(WINDOW *win, int y, int x); chtype mvwinch(WINDOW *win, int y, int x); EC int mvwinchnstr(WINDOW *win, int y, int x, chtype *chstr, int n); int mvwinchstr(WINDOW *win, int y, int x, chtype *chstr); int mvwinnstr(WINDOW *win, int y, int x, char *str, int n); int mvwinnwstr(WINDOW *win, int y, int x, wchar_t *wstr, int n); CURSES Headers int mvwinsch(WINDOW *win, int y, int x, chtype ch); EC int mvwinsnstr(WINDOW *win, int y, int x, char *const str, int n); int mvwinsstr(WINDOW *win, int y, int x, char *const str); int mvwinstr(WINDOW *win, int y, int x, char *str); int mvwins_nwstr(WINDOW *win, int y, int x, wchar_t *const wstr, int n); int mvwins_wch(WINDOW *win, int y, int x, cchar_t *const wch); int mvwins_wstr(WINDOW *win, int y, int x, wchar_t *const wstr); int mvwinwstr(WINDOW *win, int y, int x, wchar_t *wstr); int mvwin_wch(WINDOW *win, int y, int x, cchar_t *wcval); int mvwin_wchnstr(WINDOW *win, int y, int x, cchar_t *wchstr, int n); int mvwin_wchstr(WINDOW *win, int y, int x, cchar_t *wchstr); int mvwprintw(WINDOW *win, int y, int x, char *fmt, ...); int mvwscanw(WINDOW *win, int y, int x, char *fmt, ...); EC int mvwvline(WINDOW *win, int y, int x, chtype ch, int n); int mvwvline_set(WINDOW *win, int y, int x, cchar_t *const wch, int n); int napms(int ms); WINDOW *newpad(int nlines, int ncols); SCREEN *newterm(char *type, FILE *outfile, FILE *infile); WINDOW *newwin(int nlines, int ncols, int begin_y, int begin_x); int nl(void); int nonl(void); int nocbreak(void); int nodelay(WINDOW *win, bool bf); int noecho(void); EC void noqiflush(void); int noraw(void); EC int notimeout(WINDOW *win, bool bf); int overlay(WINDOW * const srcwin, WINDOW *dstwin); int overwrite(WINDOW * const srcwin, WINDOW *dstwin); EC int pair_content(short pair, short *f, short *b); int PAIR_NUMBER(int value); int pechochar(WINDOW *pad, chtype *ch); int pecho_wchar(WINDOW *pad, cchar_t *const wch); int pnoutrefresh(WINDOW *pad, int pminrow, int pmincol, int sminrow, int smincol, int smaxrow, int smaxcol); int prefresh(WINDOW *pad, int pminrow, int pmincol, int sminrow, int smincol, int smaxrow, int smaxcol); int printw(char *fmt, ...); EC int putp(char *const str); int putwin(WINDOW *win, FILE *filep); void qiflush(void); int raw(void); EC int redrawwin(WINDOW *win); int refresh(void); int resetty(void); int reset_prog_mode(void); int reset_shell_mode(void); EC int ripoffline(int line, int (*init)(WINDOW *win, int)); Headers CURSES int savetty(void); int scanw(char *fmt, ...); EC int scr_dump(char *const filename); int scr_init(char *const filename); int scrl(int n); int scroll(WINDOW *win); int scrollok(WINDOW *win, bool bf); EC int scr_restore(char *const filename); int scr_set(char *const filename); int setcchar(cchar_t *wcval, wchar_t *const wch, const attr_t attrs, short color_pair, void *const opts); int setscrreg(int top, int bot); SCREEN *set_term(SCREEN *new); EC int slk_attroff(const chtype attrs); int slk_attr_off(const attr_t attrs); int slk_attron(const chtype attrs); int slk_attr_on(const attr_t attrs); int slk_attrset(const chtype attrs); int slk_attr_set(const attr_t attrs); int slk_clear(void); int slk_init(int fmt); char *slk_label(int labnum); int slk_noutrefresh(void); int slk_refresh(void); int slk_restore(void); int slk_set(int labnum, char *const label, int justify); int slk_touch(void); int slk_wset(int labnum, wchar_t *const label, int justify); int standend(void); int standout(void); EC int start_color(void); WINDOW *subpad(WINDOW *orig, int nlines, int ncols, int begin_y, int begin_x); WINDOW *subwin(WINDOW *orig, int nlines, int ncols, int begin_y, int begin_x); EC int syncok(WINDOW *win, bool bf); attr_t termattrs(void); char *termname(void); int tigetflag(char *capname); int tigetnum(char *capname); char *tigetstr(char *capname); void timeout(int delay); int touchline(WINDOW *win, int start, int count); int touchwin(WINDOW *win); EC char *tparm(char *cap, long p1, long p2, long p3, long p4, long p5, long p6, long p7, long p8, long p9); int typeahead(int fildes); EC int ungetch(int ch); int unget_wch(const wchar_t wch); int untouchwin(WINDOW *win); void use_env(char bool); CURSES Headers int vidattr(chtype attr); int vid_attr(attr_t attr); int vidputs(chtype attr, int (*putfunc)(int)); int vid_puts(attr_t attr, wint_t (*putwfunc)(wint_t)); int vline(chtype ch, int n); int vline_set(cchar_t *const wch, int n); int vwprintw(WINDOW *win, char *fmt, va_list varglist); int vw_printw(WINDOW *win, char *fmt, va_list varglist); int vwscanw(WINDOW *win, char *fmt, va_list varglist); int vw_scanw(WINDOW *win, char *fmt, va_list varglist); int waddch(WINDOW *win, const chtype ch); EC int waddchnstr(WINDOW *win, chtype *const chstr, int n); int waddchstr(WINDOW *win, chtype *const chstr); EC int waddnstr(WINDOW *win, char *const str, int n); int waddnwstr(WINDOW *win, wchar_t *const wstr, int n); int waddstr(WINDOW *win, char *const str); int waddwstr(WINDOW *win, wchar_t *const wstr); int wadd_wch(WINDOW *win, cchar_t *const wch); int wadd_wchnstr(WINDOW *win, cchar_t *const wchstr, int n); int wadd_wchstr(WINDOW *win, cchar_t *const wchstr); int wattroff(WINDOW *win, int attrs); int wattron(WINDOW *win, int attrs); int wattrset(WINDOW *win, int attrs); EC attr_t wattr_get(WINDOW *win); int wattr_off(WINDOW *win, attr_t attrs); int wattr_on(WINDOW *win, attr_t attrs); int wattr_set(WINDOW *win, attr_t attrs); int wbkgd(WINDOW *win, chtype ch); void wbkgdset(WINDOW *win, chtype ch); int wbkgrnd(WINDOW *win, cchar_t *const wch); void wbkgrndset(WINDOW *win, cchar_t *const wch); int wborder(WINDOW *win, chtype ls, chtype rs, chtype ts, chtype bs, chtype tl, chtype tr, chtype bl, chtype br); int wborder_set(WINDOW *win, cchar_t *const ls, cchar_t *const rs, cchar_t *const ts, cchar_t *const bs, cchar_t *const tl, cchar_t *const tr, cchar_t *const bl, cchar_t *const br); int wchgat(WINDOW *win, int n, attr_t attr, short color, void *const opts); int wclear(WINDOW *win); int wclrtobot(WINDOW *win); int wclrtoeol(WINDOW *win); EC void wcursyncup(WINDOW *win); int wdelch(WINDOW *win); int wdeleteln(WINDOW *win); EC int wechochar(WINDOW *win, const chtype ch); int wecho_wchar(WINDOW *win, cchar_t *const wch); int werase(WINDOW *win); EC int wgetbkgrnd(WINDOW *win, cchar_t *wch); Headers CURSES int wgetch(WINDOW *win); EC int wgetnstr(WINDOW *win, char *str, int n); int wgetn_wstr(WINDOW *win, wint_t *wstr, int n); int wgetstr(WINDOW *win, char *str); EC int wget_wch(WINDOW *win, wint_t *ch); int wget_wstr(WINDOW *win, wint_t *wstr); int whline(WINDOW *win, chtype ch, int n); int whline_set(WINDOW *win, cchar_t *const wch, int n); chtype winch(WINDOW *win); EC int winchnstr(WINDOW *win, chtype *chstr, int n); int winchstr(WINDOW *win, chtype *chstr); int winnstr(WINDOW *win, char *str, int n); int winnwstr(WINDOW *win, wchar_t *wstr, int n); int winsch(WINDOW *win, chtype ch); EC int winsdelln(WINDOW *win, int n); int winsertln(WINDOW *win); EC int winsnstr(WINDOW *win, char *const str, int n); int winsstr(WINDOW *win, char *const str); int winstr(WINDOW *win, char *str); int wins_nwstr(WINDOW *win, wchar_t *const wstr, int n); int wins_wch(WINDOW *win, cchar_t *const wch); int wins_wstr(WINDOW *win, wchar_t *const wstr); int winwstr(WINDOW *win, wchar_t *wstr); int win_wch(WINDOW *win, cchar_t *wcval); int win_wchnstr(WINDOW *win, cchar_t *wchstr, int n); int win_wchstr(WINDOW *win, cchar_t *wchstr); int wmove(WINDOW *win, int y, int x); int wnoutrefresh(WINDOW *win); int wprintw(WINDOW *win, char *fmt, ...); EC int wredrawln(WINDOW *win, int beg_line, int num_lines); int wrefresh(WINDOW *win); int wscanw(WINDOW *win, char *fmt, ...); EC int wscrl(WINDOW *win, int n); int wsetscrreg(WINDOW *win, int top, int bot); int wstandend(WINDOW *win); int wstandout(WINDOW *win); EC void wsyncdown(WINDOW *win); void wsyncup(WINDOW *win); void wtimeout(WINDOW *win, int delay); int wtouchln(WINDOW *win, int y, int n, int changed); wchar_t *wunctrl(cchar_t *wc); int wvline(WINDOW *win, chtype ch, int n); int wvline_set(WINDOW *win, cchar_t *const wch, int n); ? SEE ALSO Chapter 1, (in the XSH specification), , (in the XSH specification), , (in the XSH specification). CHANGE HISTORY First released in Issue 2. CURSES Headers Issue 4 The entry is completely rewritten to include new constants, data types and function prototypes. Headers ENHANCED CURSES NAME term.h - terminal capabilities SYNOPSIS EC #include ? DESCRIPTION The following data type is defined through typedef: TERMINAL A pointer to a structure containing a record for a single terminal from the terminfo database. The header provides a declaration for the following object: cur_term. It represents the current terminal record from the terminfo database that the application has selected by calling set_curterm(). The header contains the variable names listed in the Variable column in the table in Section 6.1.3. The following are declared as functions, and may also be defined as macros: int del_curterm(TERMINAL *oterm); int putp(char *const str); int restartterm(char *term, int fildes, int *errret); TERMINAL *set_curterm(TERMINAL *nterm); int setupterm(char *term, int fildes, int *errret); int tgetent(char *bp, char *const name); int tgetflag(char id[2]); int tgetnum(char id[2]); char *tgetstr(char id[2], char **area); char *tgoto(char *const cap, int col, int row); int tigetflag(char *capname); int tigetnum(char *capname); char *tigetstr(char *capname); char *tparm(char *cap, long p1, long p2, long p3, long p4, long p5, long p6, long p7, long p8, long p9); int tputs(char *const str, int affcnt, int (*putfunc)(int)); SEE ALSO Chapter 6, printf(), putp(), tigetflag(), tgetent(), . CHANGE HISTORY First released in Issue 4. CURSES Headers NAME unctrl.h - definitions for unctrl() DESCRIPTION The header defines the chtype type as defined in . The following is declared as a function, and may also be defined as a macro: char *unctrl(chtype c); SEE ALSO unctrl(), . CHANGE HISTORY First released in Issue 4. Chapter 6 Terminfo Source Format (ENHANCED CURSES) The terminfo database contains a description of the capabilities of a variety of devices, such as terminals and printers. Devices are described by specifying a set of capabilities, by quantifying certain aspects of the device, and by specifying character sequences that effect particular results. This chapter specifies the format of terminfo source files. Section 6.1 describes the syntax of terminfo source files. A grammar and lexical conventions appear in Section 6.1.2. A list of all terminal capabilities defined by X/Open appears in Section 6.1.3. An example follows in Section 6.1.4. Section 6.2 describes the specification of devices in general, such as video terminals. Section 6.3 describes the specification of printers. The terminfo database is often used by screen-oriented applications such as vi and Curses programs, as well as by some utilities such as ls and more. This usage allows them to work with a variety of devices without changes to the programs. Source File Syntax Terminfo Source Format (ENHANCED CURSES) 6.1 Source File Syntax Source files can use the ISO 8859-1 codeset. The behaviour when the source file is in another codeset is unspecified. Traditional practice has been to translate information from other codesets into the source file syntax. terminfo source files consist of one or more device descriptions. Each description defines a mnemonic name for the terminal model. Each description consists of a header (beginning in column 1) and one or more lines that list the features for that particular device. Every line in a terminfo source file must end in a comma. Every line in a terminfo source file except the header must be indented with one or more white spaces (either spaces or tabs). Entries in terminfo source files consist of a number of comma-separated fields. White space after each comma is ignored. Embedded commas must be escaped by using a backslash. The following example shows the format of a terminfo source file: alias1 | alias2 | ... | aliasn | longname, am, lines #24, home=\Eeh, The first line, commonly referred to as the header line, must begin in column one and must contain at least two aliases separated by vertical bars. The last field in the header line must be the long name of the device and it may contain any string. Alias names must be unique in the terminfo database and they must conform to file naming conventions established by implementation-specific terminfo compilation utilities; for example, a typical restriction is that they cannot contain white space or slashes. There may be further constraints imposed on source file values by the implementation-specific terminfo compilation utilities. Section 6.5.1 provides conventions for choosing alias names. Each capability in terminfo is of one of the following types: o Boolean capabilities show that a device has or does not have a particular feature. o Numeric capabilities quantify particular features of a device. Terminfo Source Format (ENHANCED CURSES) Source File Syntax o String capabilities provide sequences that can be used to perform particular operations on devices. Capability names adhere to an informal length limit of five characters. Whenever possible, capability names are chosen to be the same as or similar to those specified by the ANSI X3.64-1979 standard. Semantics are also intended to match those of the ANSI standard. All string capabilities may have padding specified, with the exception of those used for input. Input capabilities, listed under the Strings section in the following tables, have names beginning with key_. These capabilities are defined in . 6.1.1 Minimum Guaranteed Limits Source File Characteristic Minimum Guaranteed Value Length of a line 1023 bytes Length of a terminal alias 14 bytes Length of a terminal model name 128 bytes Width of a single field 128 bytes Length of a string value 1000 bytes Length of a string representing a numeric value 99 digits Magnitude of a numeric value 0 up to 32767 An implementation may support higher limits than those specified above. 6.1.2 Formal Grammar The grammar and lexical conventions in this section together describe the syntax for terminfo terminal descriptions within a terminfo source file. A terminal description that satisfies the requirements of this section will be accepted by all implementations. descriptions : START_OF_HEADER_LINE4 rest_of_header_line feature_lines | descriptions START_OF_HEADER_LINE rest_of_header_line | feature_lines ; rest_of_header_line : PIPE LONGNAME COMMA NEWLINE | aliases PIPE LONGNAME COMMA NEWLINE ; feature_lines : start_feature_line rest_of_feature_line | feature_lines start_feature_line rest_of_feature_line Source File Syntax Terminfo Source Format (ENHANCED CURSES) ; start_feature_line : START_FEATURE_LINE_BOOLEAN5 | START_FEATURE_LINE_NUMERIC6 | START_FEATURE_LINE_STRING7 ; rest_of_feature_line : features COMMA NEWLINE | COMMA NEWLINE ; features : COMMA feature | features COMMA feature ; aliases : PIPE ALIAS | aliases PIPE ALIAS ; feature : BOOLEAN | NUMERIC | STRING ; The lexical conventions for terminfo descriptions are as follows: 1. White space consists of the ' ' and character. 2. An ALIAS may contain any graph8 characters other than ',' and '|'. 3. A LONGNAME may contain any print9 characters other than ',' and '|'. 4. A BOOLEAN feature may contain any print characters other than ',', '=', and '#'. 5. A NUMERIC feature consists of: a. A name which may contain any print character other than ',', '=', and '#'. b. The '#' character. c. A positive integer which conforms to the C language convention for integer constants. 6. A STRING feature consists of: a. A name which may contain any print character other than ',', '=', and '#'. b. The '=' character. Terminfo Source Format (ENHANCED CURSES) Source File Syntax c. A string which may contain any print characters other than ','. 7. White space immediately following a ',' is ignored. 8. Comments consist of , optional whitespace, a required '#', and a terminating . 9. A header line must begin in column one. 10. A feature line must not begin in column one. 11. Blank lines are ignored. 6.1.3 Defined Capabilities The table of capabilities has the following columns: Variable Names for use by the Curses functions that operate on the terminfo database. These names are reserved and the application must not define them. Capname The short name for a capability specified in the terminfo source file. It is used for updating the source file and by the tput command. Termcap Codes provided for compatibility with older applications. These codes are TO BE WITHDRAWN. Because of this, not all Capnames have Termcap codes. Booleans Cap- Term- Variable name cap Description auto_left_margin bw bw cub1 wraps from column 0 to last column auto_right_margin am am Terminal has automatic margins back_color_erase bce ut Screen erased with background colour can_change ccc cc Terminal can re-define existing colour ceol_standout_glitch xhp xs Standout not erased by overwriting (hp) col_addr_glitch xhpa YA Only positive motion for hpa/mhpa caps cpi_changes_res cpix YF Changing char pitch changes resolution cr_cancels_micro_mode crxm YB Using cr turns off micro mode dest_tabs_magic_smso xt xt Destructive tab, magic smso char (t1061) eat_newline_glitch xenl xn Newline ignored after 80 cols (Concept) erase_overstrike eo eo Can erase overstrikes with a blank generic_type gn gn Generic line type (e.g., dialup, switch) get_mouse getm Gm Curses should get button events hard_copy hc hc Hardcopy terminal hard_cursor chts HC Cursor is hard to see has_meta_key km km Has a meta key (shift, sets parity bit) has_print_wheel daisy YC Printer needs operator to change character set has_status_line hs hs Has extra "status line" hue_lightness_saturation hls hl Terminal uses only HLS colour notation (Tektronix) insert_null_glitch in in Insert mode distinguishes nulls lpi_changes_res lpix YG Changing line pitch changes resolution memory_above da da Display may be retained above the screen memory_below db db Display may be retained below the screen move_insert_mode mir mi Safe to move while in insert mode move_standout_mode msgr ms Safe to move in standout modes needs_xon_xoff nxon nx Padding won't work, xon/xoff required no_esc_ctlc xsb xb Beehive (f1=escape, f2=ctrl C) no_pad_char npc NP Pad character doesn't exist non_dest_scroll_region ndscr ND Scrolling region is nondestructive non_rev_rmcup nrrmc NR smcup does not reverse rmcup over_strike os os Terminal overstrikes on hard-copy terminal prtr_silent mc5i 5i Printer won't echo on screen row_addr_glitch xvpa YD Only positive motion for vpa/mvpa caps semi_auto_right_margin sam YE Printing in last column causes cr status_line_esc_ok eslok es Escape can be used on the status line tilde_glitch hz hz Hazeltine; can't print tilde (~) transparent_underline ul ul Underline character overstrikes xon_xoff xon xo Terminal uses xon/xoff handshaking Numbers Cap- Term- Variable name cap Description bit_image_entwining bitwin Yo Number of passes for each bit-map row bit_image_type bitype Yp Type of bit image device buffer_capacity bufsz Ya Number of bytes buffered before printing buttons btns BT Number of buttons on the mouse columns cols co Number of columns in a line dot_horz_spacing spinh Yc Spacing of dots horizontally in dots per inch dot_vert_spacing spinv Yb Spacing of pins vertically in pins per inch init_tabs it it Tabs initially every # spaces label_height lh lh Number of rows in each label label_width lw lw Number of columns in each label lines lines li Number of lines on a screen or a page lines_of_memory lm lm Lines of memory if > lines; 0 means varies Maximum combined video attributes terminal can display max_attributes ma ma magic_cookie_glitch xmc sg Number of blank characters left by smso or rmso max_colors colors Co Maximum number of colours on the screen max_micro_address maddr Yd Maximum value in micro_..._address max_micro_jump mjump Ye Maximum value in parm_..._micro max_pairs pairs pa Maximum number of colour-pairs on the screen maximum_windows Wnum MW Maximum number of definable windows micro_char_size mcs Yg Character step size when in micro mode micro_line_size mls Yf Line step size when in micro mode no_color_video ncv NC Video attributes that can't be used with colours num_labels nlab Nl Number of labels on screen (start at 1) number_of_pins npins Yh Number of pins in print-head output_res_char orc Yi Horizontal resolution in units per character output_res_line orl Yj Vertical resolution in units per line output_res_horz_inch orhi Yk Horizontal resolution in units per inch output_res_vert_inch orvi Yl Vertical resolution in units per inch padding_baud_rate pb pb Lowest baud rate where padding needed print_rate cps Ym Print rate in characters per second virtual_terminal vt vt Virtual terminal number wide_char_size widcs Yn Character step size when in double-wide mode width_status_line wsl ws Number of columns in status line Strings Cap- Term- Variable name cap Description acs_chars acsc ac Graphic charset pairs aAbBcC alt_scancode_esc scesa S8 Alternate escape for scancode emulation (default is for VT100) back_tab cbt bt Back tab bell bel bl Audible signal (bell) bit_image_carriage_return bicr Yv Move to beginning of same row bit_image_newline binel Zz Move to next row of the bit image bit_image_repeat birep Xy Repeat bit-image cell #1 #2 times carriage_return cr cr Carriage return change_char_pitch cpi ZA Change number of characters per inch change_line_pitch lpi ZB Change number of lines per inch change_res_horz chr ZC Change horizontal resolution change_res_vert cvr ZD Change vertical resolution change_scroll_region csr cs Change to lines #1 through #2 (VT100) char_padding rmp rP Like ip but when in replace mode char_set_names csnm Zy Returns a list of character set names clear_all_tabs tbc ct Clear all tab stops clear_margins mgc MC Clear all margins (top, bottom, and sides) clear_screen clear cl Clear screen and home cursor clr_bol el1 cb Clear to beginning of line, inclusive clr_eol el ce Clear to end of line clr_eos ed cd Clear to end of display code_set_init csin ci Init sequence for multiple codesets color_names colornm Yw Give name for colour #1 column_address hpa ch Set horizontal position to absolute #1 command_character cmdch CC Terminal settable cmd character in prototype create_window cwin CW Define win #1 to go from #2,#3 to #4,#5 cursor_address cup cm Move to row #1 col #2 cursor_down cud1 do Down one line cursor_home home ho Home cursor (if no cup) cursor_invisible civis vi Make cursor invisible cursor_left cub1 le Move left one space. cursor_mem_address mrcup CM Memory relative cursor addressing cursor_normal cnorm ve Make cursor appear normal (undo vs/vi) cursor_right cuf1 nd Non-destructive space (cursor or carriage right) cursor_to_ll ll ll Last line, first column (if no cup) cursor_up cuu1 up Upline (cursor up) cursor_visible cvvis vs Make cursor very visible define_bit_image_region defbi Yx Define rectangular bit-image region Cap- Term- Variable name cap Description define_char defc ZE Define a character in a character set delete_character dch1 dc Delete character delete_line dl1 dl Delete line device_type devt dv Indicate language/codeset support dial_phone dial DI Dial phone number #1 dis_status_line dsl ds Disable status line display_clock dclk DK Display time-of-day clock display_pc_char dispc S1 Display PC character down_half_line hd hd Half-line down (forward 1/2 linefeed) ena_acs enacs eA Enable alternate character set end_bit_image_region endbi Yy End a bit-image region enter_alt_charset_mode smacs as Start alternate character set enter_am_mode smam SA Turn on automatic margins enter_blink_mode blink mb Turn on blinking enter_bold_mode bold md Turn on bold (extra bright) mode enter_ca_mode smcup ti String to begin programs that use cup enter_delete_mode smdc dm Delete mode (enter) enter_dim_mode dim mh Turn on half-bright mode enter_doublewide_mode swidm ZF Enable double wide printing enter_draft_quality sdrfq ZG Set draft quality print enter_horizontal_hl_mode ehhlm Turn on horizontal highlight mode enter_insert_mode smir im Insert mode (enter) enter_italics_mode sitm ZH Enable italics enter_left_hl_mode elhlm Turn on left highlight mode enter_leftward_mode slm ZI Enable leftward carriage motion enter_low_hl_mode elohlm Turn on low highlight mode enter_micro_mode smicm ZJ Enable micro motion capabilities enter_near_letter_quality snlq ZK Set near-letter quality print enter_normal_quality snrmq ZL Set normal quality print enter_pc_charset_mode smpch S2 Enter PC character display mode enter_protected_mode prot mp Turn on protected mode enter_reverse_mode rev mr Turn on reverse video mode enter_right_hl_mode erhlm Turn on right highlight mode enter_scancode_mode smsc S4 Enter PC scancode mode enter_secure_mode invis mk Turn on blank mode (characters invisible) enter_shadow_mode sshm ZM Enable shadow printing enter_standout_mode smso so Begin standout mode enter_subscript_mode ssubm ZN Enable subscript printing enter_superscript_mode ssupm ZO Enable superscript printing enter_top_hl_mode ethlm Turn on top highlight mode enter_underline_mode smul us Start underscore mode enter_upward_mode sum ZP Enable upward carriage motion enter_vertical_hl_mode evhlm Turn on vertical highlight mode enter_xon_mode smxon SX Turn on xon/xoff handshaking erase_chars ech ec Erase #1 characters Cap- Term- Variable name cap Description exit_alt_charset_mode rmacs ae End alternate character set exit_am_mode rmam RA Turn off automatic margins exit_attribute_mode sgr0 me Turn off all attributes exit_ca_mode rmcup te String to end programs that use cup exit_delete_mode rmdc ed End delete mode exit_doublewide_mode rwidm ZQ Disable double wide printing exit_insert_mode rmir ei End insert mode exit_italics_mode ritm ZR Disable italics exit_leftward_mode rlm ZS Enable rightward (normal) carriage motion exit_micro_mode rmicm ZT Disable micro motion capabilities exit_pc_charset_mode rmpch S3 Disable PC character display mode exit_scancode_mode rmsc S5 Disable PC scancode mode exit_shadow_mode rshm ZU Disable shadow printing exit_standout_mode rmso se End standout mode exit_subscript_mode rsubm ZV Disable subscript printing exit_superscript_mode rsupm ZW Disable superscript printing exit_underline_mode rmul ue End underscore mode exit_upward_mode rum ZX Enable downward (normal) carriage motion exit_xon_mode rmxon RX Turn off xon/xoff handshaking fixed_pause pause PA Pause for 2-3 seconds flash_hook hook fh Flash the switch hook flash_screen flash vb Visible bell (may move cursor) form_feed ff ff Hardcopy terminal page eject from_status_line fsl fs Return from status line goto_window wingo WG Go to window #1 hangup hup HU Hang-up phone init_1string is1 i1 Terminal or printer initialisation string init_2string is2 is Terminal or printer initialisation string init_3string is3 i3 Terminal or printer initialisation string init_file if if Name of initialisation file init_prog iprog iP Path name of program for initialisation initialize_color initc IC Set colour #1 to RGB #2, #3, #4 initialize_pair initp Ip Set colour-pair #1 to fg #2, bg #3 insert_character ich1 ic Insert character insert_line il1 al Add new blank line insert_padding ip ip Insert pad after character inserted The ``key_'' strings are sent by specific keys. The ``key_'' descriptions include the macro, defined in , for the code returned by getch() when the key is pressed (see getch()). Source File Syntax Terminfo Source Format (ENHANCED CURSES) Cap- Term- Variable name cap Description key_a1 ka1 K1 upper left of keypad key_a3 ka3 K3 upper right of keypad key_b2 kb2 K2 center of keypad key_backspace kbs kb sent by backspace key key_beg kbeg @1 sent by beg(inning) key key_btab kcbt kB sent by back-tab key key_c1 kc1 K4 lower left of keypad key_c3 kc3 K5 lower right of keypad key_cancel kcan @2 sent by cancel key key_catab ktbc ka sent by clear-all-tabs key key_clear kclr kC sent by clear-screen or erase key key_close kclo @3 sent by close key key_command kcmd @4 sent by cmd (command) key key_copy kcpy @5 sent by copy key key_create kcrt @6 sent by create key key_ctab kctab kt sent by clear-tab key key_dc kdch1 kD sent by delete-character key key_dl kdl1 kL sent by delete-line key key_down kcud1 kd sent by terminal down-arrow key key_eic krmir kM sent by rmir or smir in insert mode key_end kend @7 sent by end key key_enter kent @8 sent by enter/send key key_eol kel kE sent by clear-to-end-of-line key key_eos ked kS sent by clear-to-end-of-screen key key_exit kext @9 sent by exit key key_f0 kf0 k0 sent by function key f0 key_f1 kf1 k1 sent by function key f1 . . . . . . . . . . . . key_f62 kf62 Fq sent by function key f62 key_f63 kf63 Fr sent by function key f63 key_find kfnd @0 sent by find key key_help khlp %1 sent by help key key_home khome kh sent by home key key_ic kich1 kI sent by ins-char/enter ins-mode key key_il kil1 kA sent by insert-line key key_left kcub1 kl sent by terminal left-arrow key key_ll kll kH sent by home-down key key_mark kmrk %2 sent by mark key key_message kmsg %3 sent by message key key_mouse kmous Km 0631, Mouse event has occured key_move kmov %4 sent by move key key_next knxt %5 sent by next-object key key_npage knp kN sent by next-page key key_open kopn %6 sent by open key key_options kopt %7 sent by options key key_ppage kpp kP sent by previous-page key key_previous kprv %8 sent by previous-object key key_print kprt %9 sent by print or copy key key_redo krdo %0 sent by redo key key_reference kref &1 sent by ref(erence) key key_refresh krfr &2 sent by refresh key key_replace krpl &3 sent by replace key key_restart krst &4 sent by restart key key_resume kres &5 sent by resume key key_right kcuf1 kr sent by terminal right-arrow key key_save ksav &6 sent by save key key_sbeg kBEG &9 sent by shifted beginning key key_scancel kCAN &0 sent by shifted cancel key key_scommand kCMD *1 sent by shifted command key key_scopy kCPY *2 sent by shifted copy key key_screate kCRT *3 sent by shifted create key key_sdc kDC *4 sent by shifted delete-char key key_sdl kDL *5 sent by shifted delete-line key key_select kslt *6 sent by select key key_send kEND *7 sent by shifted end key key_seol kEOL *8 sent by shifted clear-line key key_sexit kEXT *9 sent by shifted exit key key_sf kind kF sent by scroll-forward/down key key_sfind kFND *0 sent by shifted find key key_shelp kHLP #1 sent by shifted help key key_shome kHOM #2 sent by shifted home key key_sic kIC #3 sent by shifted input key key_sleft kLFT #4 sent by shifted left-arrow key key_smessage kMSG %a sent by shifted message key key_smove kMOV %b sent by shifted move key key_snext kNXT %c sent by shifted next key key_soptions kOPT %d sent by shifted options key key_sprevious kPRV %e sent by shifted prev key key_sprint kPRT %f sent by shifted print key key_sr kri kR sent by scroll-backward/up key key_sredo kRDO %g sent by shifted redo key key_sreplace kRPL %h sent by shifted replace key key_sright kRIT %i sent by shifted right-arrow key key_srsume kRES %j sent by shifted resume key key_ssave kSAV !1 sent by shifted save key key_ssuspend kSPD !2 sent by shifted suspend key key_stab khts kT sent by set-tab key key_sundo kUND !3 sent by shifted undo key key_suspend kspd &7 sent by suspend key key_undo kund &8 sent by undo key key_up kcuu1 ku sent by terminal up-arrow key keypad_local rmkx ke Out of ``keypad-transmit'' mode keypad_xmit smkx ks Put terminal in ``keypad-transmit'' mode lab_f0 lf0 l0 Labels on function key f0 if not f0 lab_f1 lf1 l1 Labels on function key f1 if not f1 lab_f2 lf2 l2 Labels on function key f2 if not f2 lab_f3 lf3 l3 Labels on function key f3 if not f3 lab_f4 lf4 l4 Labels on function key f4 if not f4 lab_f5 lf5 l5 Labels on function key f5 if not f5 lab_f6 lf6 l6 Labels on function key f6 if not f6 lab_f7 lf7 l7 Labels on function key f7 if not f7 lab_f8 lf8 l8 Labels on function key f8 if not f8 lab_f9 lf9 l9 Labels on function key f9 if not f9 lab_f10 lf10 la Labels on function key f10 if not f10 label_format fln Lf Label format label_off rmln LF Turn off soft labels label_on smln LO Turn on soft labels meta_off rmm mo Turn off "meta mode" meta_on smm mm Turn on "meta mode" (8th bit) micro_column_address mhpa ZY Like column_address for micro adjustment micro_down mcud1 ZZ Like cursor_down for micro adjustment micro_left mcub1 Za Like cursor_left for micro adjustment micro_right mcuf1 Zb Like cursor_right for micro adjustment micro_row_address mvpa Zc Like row_address for micro adjustment micro_up mcuu1 Zd Like cursor_up for micro adjustment mouse_info minfo Mi Mouse status information newline nel nw Newline (behaves like cr followed by lf) order_of_pins porder Ze Matches software bits to print-head pins orig_colors oc oc Set all colour(-pair)s to the original ones orig_pair op op Set default colour-pair to the original one pad_char pad pc Pad character (rather than null) parm_dch dch DC Delete #1 chars parm_delete_line dl DL Delete #1 lines parm_down_cursor cud DO Move down #1 lines. parm_down_micro mcud Zf Like parm_down_cursor for micro adjust. parm_ich ich IC Insert #1 blank chars parm_index indn SF Scroll forward #1 lines. parm_insert_line il AL Add #1 new blank lines parm_left_cursor cub LE Move cursor left #1 spaces parm_left_micro mcub Zg Like parm_left_cursor for micro adjust. parm_right_cursor cuf RI Move right #1 spaces. parm_right_micro mcuf Zh Like parm_right_cursor for micro adjust. parm_rindex rin SR Scroll backward #1 lines. parm_up_cursor cuu UP Move cursor up #1 lines. parm_up_micro mcuu Zi Like parm_up_cursor for micro adjust. pc_term_options pctrm S6 PC terminal options pkey_key pfkey pk Prog funct key #1 to type string #2 pkey_local pfloc pl Prog funct key #1 to execute string #2 pkey_plab pfxl xl Prog key #1 to xmit string #2 and show string #3 pkey_xmit pfx px Prog funct key #1 to xmit string #2 plab_norm pln pn Prog label #1 to show string #2 print_screen mc0 ps Print contents of the screen prtr_non mc5p pO Turn on the printer for #1 bytes prtr_off mc4 pf Turn off the printer prtr_on mc5 po Turn on the printer pulse pulse PU Select pulse dialing quick_dial qdial QD Dial phone number #1, without progress detection remove_clock rmclk RC Remove time-of-day clock repeat_char rep rp Repeat char #1 #2 times req_for_input rfi RF Send next input char (for ptys) req_mouse_pos reqmp RQ Request mouse position report reset_1string rs1 r1 Reset terminal completely to sane modes reset_2string rs2 r2 Reset terminal completely to sane modes reset_3string rs3 r3 Reset terminal completely to sane modes reset_file rf rf Name of file containing reset string restore_cursor rc rc Restore cursor to position of last sc row_address vpa cv Set vertical position to absolute #1 save_cursor sc sc Save cursor position scancode_escape scesc S7 Escape for scancode emulation scroll_forward ind sf Scroll text up scroll_reverse ri sr Scroll text down select_char_set scs Zj Select character set set0_des_seq s0ds s0 Shift into codeset 0 (EUC set 0, ASCII) set1_des_seq s1ds s1 Shift into codeset 1 set2_des_seq s2ds s2 Shift into codeset 2 set3_des_seq s3ds s3 Shift into codeset 3 set_a_attributes sgr1 Define second set of video attributes #1-#6 set_a_background setab AB Set background colour to #1 using ANSI escape set_a_foreground setaf AF Set foreground colour to #1 using ANSI escape set_attributes sgr sa Define first set of video attributes #1-#9 set_background setb Sb Set background colour to #1 set_bottom_margin smgb Zk Set bottom margin at current line set_bottom_margin_parm smgbp Zl Set bottom margin at line #1 or #2 lines from bottom set_clock sclk SC Set clock to hours (#1), minutes (#2), seconds (#3) set_color_band setcolor Yz Change to ribbon colour #1 set_color_pair scp sp Set current colour pair to #1 set_foreground setf Sf Set foreground colour to #1 set_left_margin smgl ML Set left margin at current column set_left_margin_parm smglp Zm Set left (right) margin at column #1 (#2) set_lr_margin smglr ML Sets both left and right margins set_page_length slines YZ Set page length to #1 lines set_pglen_inch slength YI Set page length to #1 hundredth of an inch set_right_margin smgr MR Set right margin at current column set_right_margin_parm smgrp Zn Set right margin at column #1 set_tab hts st Set a tab in all rows, current column set_tb_margin smgtb MT Sets both top and bottom margins set_top_margin smgt Zo Set top margin at current line set_top_margin_parm smgtp Zp Set top (bottom) margin at line #1 (#2) set_window wind wi Current window is lines #1-#2 cols #3-#4 start_bit_image sbim Zq Start printing bit image graphics start_char_set_def scsd Zr Start definition of a character set stop_bit_image rbim Zs End printing bit image graphics stop_char_set_def rcsd Zt End definition of a character set subscript_characters subcs Zu List of ``subscript-able'' characters superscript_characters supcs Zv List of ``superscript-able'' characters tab ht ta Tab to next 8-space hardware tab stop these_cause_cr docr Zw Printing any of these chars causes cr to_status_line tsl ts Go to status line, col #1 tone tone TO Select touch tone dialing user0 u0 u0 User string 0 user1 u1 u1 User string 1 user2 u2 u2 User string 2 user3 u3 u3 User string 3 user4 u4 u4 User string 4 user5 u5 u5 User string 5 user6 u6 u6 User string 6 user7 u7 u7 User string 7 user8 u8 u8 User string 8 user9 u9 u9 User string 9 underline_char uc uc Underscore one char and move past it up_half_line hu hu Half-line up (reverse 1/2 linefeed) wait_tone wait WA Wait for dial tone xoff_character xoffc XF X-off character xon_character xonc XN X-on character zero_motion zerom Zx No motion for the subsequent character 6.1.4 Sample Entry The following entry describes the AT&T 610 terminal. 610|610bct|ATT610|att610|AT&T610;80column;98key keyboard, am, eslok, hs, mir, msgr, xenl, xon, cols#80, it#8, lh#2, lines#24, lw#8, nlab#8, wsl#80, acsc=``aaffggjjkkllmmnnooppqqrrssttuuvvwwxxyyzz{{||}}~~, bel=^G, blink=\E[5m, bold=\E[1m, cbt=\E[Z, civis=\E[?25l, clear=\E[H\E[J, cnorm=\E[?25h\E[?12l, cr=\r, csr=\E[%i%p1%d;%p2%dr, cub=\E[%p1%dD, cub1=\b, cud=\E[%p1%dB, cud1=\E[B, cuf=\E[%p1%dC, cuf1=\E[C, cup=\E[%i%p1%d;%p2%dH, cuu=\E[%p1%dA, cuu1=\E[A, cvvis=\E[?12;25h, dch=\E[%p1%dP, dch1=\E[P, dim=\E[2m, dl=\E[%p1%dM, dl1=\E[M, ed=\E[J, el=\E[K, el1=\E[1K, flash=\E[?5h$<200>\E[?5l, fsl=\E8, home=\E[H, ht=\t, ich=\E[%p1%d@, il=\E[%p1%dL, il1=\E[L, ind=\ED, .ind=\ED$<9>, invis=\E[8m, is1=\E[8;0 | \E[?3;4;5;13;15l\E[13;20l\E[?7h\E[12h\E(B\E)0, is2=\E[0m^O, is3=\E(B\E)0, kLFT=\E[\s@, kRIT=\E[\sA, kbs=^H, kcbt=\E[Z, kclr=\E[2J, kcub1=\E[D, kcud1=\E[B, kcuf1=\E[C, kcuu1=\E[A, kfP=\EOc, kfP0=\ENp, kfP1=\ENq, kfP2=\ENr, kfP3=\ENs, kfP4=\ENt, kfI=\EOd, kfB=\EOe, kf4=\EOf, kf(CW=\EOg, kf6=\EOh, kf7=\EOi, kf8=\EOj, kf9=\ENo, khome=\E[H, kind=\E[S, kri=\E[T, ll=\E[24H, mc4=\E[?4i, mc5=\E[?5i, nel=\EE, pfxl=\E[%p1%d;%p2%l%02dq%?%p1%{9}%<%t\s\s\sF%p1%1d\s\s\s\s\s \s\s\s\s\s\s%;%p2%s, pln=\E[%p1%d;0;0;0q%p2%:-16.16s, rc=\E8, rev=\E[7m, ri=\EM, rmacs=^O, rmir=\E[4l, rmln=\E[2p, rmso=\E[m, rmul=\E[m, rs2=\Ec\E[?3l, sc=\E7, sgr=\E[0%?%p6%t;1%;%?%p5%t;2%;%?%p2%t;4%;%?%p4%t;5%; %?%p3%p1% | %t;7%;%?%p7%t;8%;m%?%p9%t^N%e^O%;, sgr0=\E[m^O, smacs=^N, smir=\E[4h, smln=\E[p, smso=\E[7m, smul=\E[4m, tsl=\E7\E[25;%i%p1%dx, 6.1.5 Types of Capabilities in the Sample Entry The sample entry shows the formats for the three types of terminfo capabilities: Boolean, numeric, and string. All capabilities specified in the terminfo source file must be followed by commas, including the last capability in the source file. In terminfo source files, capabilities are referenced by their capability names (as shown in the Capname column of the previous tables). Boolean Capabilities A boolean capability is true if its Capname is present in the entry, and false if its Capname is not present in the entry. The `@' character following a Capname is used to explicitly declare that a boolean capability is false, in situations described in Section 6.2.16. Source File Syntax Terminfo Source Format (ENHANCED CURSES) Numeric Capabilities Numeric capabilities are followed by the character `#' and then a positive integer value. The example assigns the value 80 to the cols numeric capability by coding: cols#80 Values for numeric capabilities may be specified in decimal, octal or hexadecimal, using normal C-language conventions. String Capabilities String-valued capabilities such as el (clear to end of line sequence) are listed by the Capname, an `=', and a string ended by the next occurrence of a comma. A delay in milliseconds may appear anywhere in such a capability, preceded by $ and enclosed in angle brackets, as in el=\EK$<3>. The Curses implementation achieves delays by outputting to the terminal an appropriate number of system-defined padding characters. The tputs() function provides delays when used to send such a capability to the terminal. The delay can be any of the following: a number, a number followed by an asterisk, such as 5*, a number followed by a slash, such as 5/, or a number followed by both, such as 5*/. o A `*' shows that the required delay is proportional to the number of lines affected by the operation, and the amount given is the delay required per affected unit. (In the case of insert characters, the factor is still the number of lines affected. This is always 1 unless the device has in and the software uses it.) When a `*' is specified, it is sometimes useful to give a delay of the form 3.5 to specify a delay per unit to tenths of milliseconds. (Only one decimal place is allowed.) o A `/' indicates that the delay is mandatory and padding characters are transmitted regardless of the setting of xon. If `/' is not specified or if a device has xon defined, the delay information is advisory and is only used for cost estimates or when the device is in raw mode. However, any delay specified for bel or flash is treated as mandatory. Terminfo Source Format (ENHANCED CURSES) Source File Syntax The following notation is valid in terminfo source files for specifying special characters: Notation Represents Character ^x Control-x (for any appropriate x) \a Alert \b Backspace \E or \e An ESCAPE character \f Form feed \l Linefeed \n Newline \r Carriage return \s Space \t Tab \^ Caret (^) \\ Backslash (\) \, Comma (,) \: Colon (:) \0 Null \nnn Any character, specified as three octal digits (See the XBD specification, General Terminal Interface.) Commented-out Capabilities Sometimes individual capabilities must be commented out. To do this, put a period before the capability name. For example, see the second ind in the example in Section 6.1.4. Note that capabilities are defined in a left-to-right order and, therefore, a prior definition will override a later definition. Device Capabilities Terminfo Source Format (ENHANCED CURSES) 6.2 Device Capabilities 6.2.1 Basic Capabilities The number of columns on each line for the device is given by the cols numeric capability. If the device has a screen, then the number of lines on the screen is given by the lines capability. If the device wraps around to the beginning of the next line when it reaches the right margin, then it should have the am capability. If the terminal can clear its screen, leaving the cursor in the home position, then this is given by the clear string capability. If the terminal overstrikes (rather than clearing a position when a character is struck over) then it should have the os capability. If the device is a printing terminal, with no soft copy unit, specify both hc and os. If there is a way to move the cursor to the left edge of the current row, specify this as cr. (Normally this will be carriage return, control-M.) If there is a way to produce an audible signal (such as a bell or a beep), specify it as bel. If, like most devices, the device uses the xon-xoff flow-control protocol, specify xon. If there is a way to move the cursor one position to the left (such as backspace), that capability should be given as cub1. Similarly, sequences to move to the right, up, and down should be given as cuf1, cuu1, and cud1, respectively. These local cursor motions must not alter the text they pass over; for example, you would not normally use ``cuf1=\s'' because the space would erase the character moved over. A very important point here is that the local cursor motions encoded in terminfo are undefined at the left and top edges of a screen terminal. Programs should never attempt to backspace around the left edge, unless bw is specified, and should never attempt to go up locally off the top. To scroll text up, a program goes to the bottom left corner of the screen and sends the ind (index) string. To scroll text down, a program goes to the top left corner of the screen and sends the ri (reverse index) string. The strings ind and ri are undefined when not on their respective corners of the screen. Parameterised versions of the scrolling sequences are indn and rin. These versions have the same semantics as ind and ri, except that they take one argument and scroll the number of lines specified by that argument. Terminfo Source Format (ENHANCED CURSES) Device Capabilities They are also undefined except at the appropriate edge of the screen. The am capability tells whether the cursor sticks at the right edge of the screen when text is output, but this does not necessarily apply to a cuf1 from the last column. Backward motion from the left edge of the screen is possible only when bw is specified. In this case, cub1 will move to the right edge of the previous row. If bw is not given, the effect is undefined. This is useful for drawing a box around the edge of the screen, for example. If the device has switch-selectable automatic margins, am should be specified in the terminfo source file. In this case, initialisation strings should turn on this option, if possible. If the device has a command that moves to the first column of the next line, that command can be given as nel (newline). It does not matter if the command clears the remainder of the current line, so if the device has no cr and lf it may still be possible to craft a working nel out of one or both of them. These capabilities suffice to describe hardcopy and screen terminals. Thus the AT&T 5320 hardcopy terminal is described as follows: 5320|att5320|AT&T 5320 hardcopy terminal, am, hc, os, cols#132, bel=^G, cr=\r, cub1=\b, cnd1=\n, dch1=\E[P, dl1=\E[M, ind=\n, while the Lear Siegler ADM-3 is described as adm3|lsi adm3, am, bel=^G, clear=^Z, cols#80, cr=^M, cub1=^H, cud1=^J, ind=^J, lines#24, 6.2.2 Parameterised Strings Cursor addressing and other strings requiring arguments are described by a argumentised string capability with escapes in a form (%x) comparable to printf(). For example, to address the cursor, the cup capability is given, using two arguments: the row and column to address to. (Rows and columns are numbered from zero and refer to the physical screen visible to the user, not to any unseen memory.) If the terminal has memory relative cursor addressing, that can be Device Capabilities Terminfo Source Format (ENHANCED CURSES) indicated by mrcup. The argument mechanism uses a stack and special % codes to manipulate the stack in the manner of Reverse Polish Notation (postfix). Typically a sequence pushes one of the arguments onto the stack and then prints it in some format. Often more complex operations are necessary. Operations are in postfix form with the operands in the usual order. That is, to subtract 5 from the first argument, one would use %p1%{5}%-. The % encodings have the following meanings: %% Outputs `%'. %[[:]flags][width[.precision]][doxXs] As in printf(); flags are [-+#] and space. %c Print pop() gives %c. %p[1-9] Push the ith argument. %P[a-z] Set dynamic variable [a-z] to pop(). %g[a-z] Get dynamic variable [a-z] and push it. %P[A-Z] Set static variable [a-z] to pop(). %g[A-Z] Get static variable [a-z] and push it. %'c' Push char constant c. %{nn} Push decimal constant nn. %l Push strlen(pop()). %+ %- %* %/ %m Arithmetic (%m is mod): push(pop integer2 op pop integer1) where integer1 represents the top of the stack %& %| %^ Bit operations: push(pop integer2 op pop integer1) %= %> %< Logical operations: push(pop integer2 op pop integer1) Terminfo Source Format (ENHANCED CURSES) Device Capabilities %A %O Logical operations: and, or %! %~ Unary operations: push(op pop()) %i (For ANSI terminals) add 1 to the first argument (if one argument present), or first two arguments (if more than one argument present). %? expr %t thenpart %e elsepart %; If-then-else, %e elsepart is optional; else-if's are possible ala Algol 68: %? c1 %t b1 %e c2 %t b2 %e c3 %t b3 %e c4 %t b4 %e b5%; ci are conditions, bi are bodies. If the ``-'' flag is used with ``%[doxXs]'', then a colon must be placed between the ``%'' and the ``-'' to differentiate the flag from the binary ``%-'' operator. For example: ``%:-16.16s''. Consider the Hewlett-Packard 2645, which, to get to row 3 and column 12, needs to be sent \E&a12c03Y padded for 6 milliseconds. Note that the order of the rows and columns is inverted here, and that the row and column are zero-padded as two digits. Thus its cup capability is: cup=\E&a%p2%2.2dc%p1%2.2dY$<6> The Micro-Term ACT-IV needs the current row and column sent preceded by a ^T, with the row and column simply encoded in binary: cup=^T%p1%c%p2%c Devices that use ``%c'' need to be able to backspace the cursor (cub1), and to move the cursor up one line on the screen (cuu1). This is necessary because it is not always safe to transmit \n, ^D, and \r, as the system may change or discard them. (The library functions dealing with terminfo set tty modes so that tabs are never expanded, so \t is safe to send. This turns out to be essential for the Ann Arbor 4080.) A final example is the LSI ADM-3a, which uses row and column offset by a blank character, thus: cup=\E=%p1%'\s'%+%c%p2%'\s'%+%c After sending ``\E='', this pushes the first argument, pushes the ASCII value for a space (32), adds them Device Capabilities Terminfo Source Format (ENHANCED CURSES) (pushing the sum on the stack in place of the two previous values), and outputs that value as a character. Then the same is done for the second argument. More complex arithmetic is possible using the stack. 6.2.3 Cursor Motions If the terminal has a fast way to home the cursor (to very upper left corner of screen) then this can be given as home; similarly a fast way of getting to the lower left-hand corner can be given as ll; this may involve going up with cuu1 from the home position, but a program should never do this itself (unless ll does) because it can make no assumption about the effect of moving up from the home position. Note that the home position is the same as addressing to (0,0): to the top left corner of the screen, not of memory. (Thus, the \EH sequence on Hewlett-Packard terminals cannot be used for home without losing some of the other features on the terminal.) If the device has row or column absolute-cursor addressing, these can be given as single argument capabilities hpa (horizontal position absolute) and vpa (vertical position absolute). Sometimes these are shorter than the more general two-argument sequence (as with the Hewlett-Packard 2645) and can be used in preference to cup. If there are argumentised local motions (such as ``move n spaces to the right''), these can be given as cud, cub, cuf, and cuu with a single argument indicating how many spaces to move. These are primarily useful if the device does not have cup, such as the Tektronix 4025. If the device needs to be in a special mode when running a program that uses these capabilities, the codes to enter and exit this mode can be given as smcup and rmcup. This arises, for example, from terminals, such as the Concept, with more than one page of memory. If the device has only memory relative cursor addressing and not screen relative cursor addressing, a one screen-sized window must be fixed into the device for cursor addressing to work properly. This is also used for the Tektronix 4025, where smcup sets the command character to be the one used by terminfo. If the rmcup sequence will not restore the screen after an smcup sequence is output (to the state prior to outputting smcup), specify nrrmc. Terminfo Source Format (ENHANCED CURSES) Device Capabilities 6.2.4 Area Clears If the terminal can clear from the current position to the end of the line, leaving the cursor where it is, this should be given as el. If the terminal can clear from the beginning of the line to the current position inclusive, leaving the cursor where it is, this should be given as el1. If the terminal can clear from the current position to the end of the display, then this should be given as ed. ed is only defined from the first column of a line. (Thus, it can be simulated by a request to delete a large number of lines, if a true ed is not available.) 6.2.5 Insert/Delete Line If the terminal can open a new blank line before the line where the cursor is, this should be given as il1; this is done only from the first position of a line. The cursor must then appear on the newly blank line. If the terminal can delete the line which the cursor is on, then this should be given as dl1; this is done only from the first position on the line to be deleted. Versions of il1 and dl1 which take a single argument and insert or delete that many lines can be given as il and dl. If the terminal has a settable destructive scrolling region (like the VT100) the command to set this can be described with the csr capability, which takes two arguments: the top and bottom lines of the scrolling region. The cursor position is, alas, undefined after using this command. It is possible to get the effect of insert or delete line using this command - the sc and rc (save and restore cursor) commands are also useful. Inserting lines at the top or bottom of the screen can also be done using ri or ind on many terminals without a true insert/delete line, and is often faster even on terminals with those features. To determine whether a terminal has destructive scrolling regions or non-destructive scrolling regions, create a scrolling region in the middle of the screen, place data on the bottom line of the scrolling region, move the cursor to the top line of the scrolling region, and do a reverse index (ri) followed by a delete line (dl1) or index (ind). If the data that was originally on the bottom line of the scrolling region was restored into the scrolling region by the dl1 or ind, then the terminal has non- destructive scrolling regions. Otherwise, it has Device Capabilities Terminfo Source Format (ENHANCED CURSES) destructive scrolling regions. Do not specify csr if the terminal has non-destructive scrolling regions, unless ind, ri, indn, rin, dl, and dl1 all simulate destructive scrolling. If the terminal has the ability to define a window as part of memory, which all commands affect, it should be given as the argumentised string wind. The four arguments are the starting and ending lines in memory and the starting and ending columns in memory, in that order. If the terminal can retain display memory above, then the da capability should be given; if display memory can be retained below, then db should be given. These indicate that deleting a line or scrolling a full screen may bring non-blank lines up from below or that scrolling back with ri may bring down non-blank lines. 6.2.6 Insert/Delete Character There are two basic kinds of intelligent terminals with respect to insert/delete character operations which can be described using terminfo. The most common insert/delete character operations affect only the characters on the current line and shift characters off the end of the line rigidly. Other terminals, such as the Concept 100 and the Perkin- Elmer Owl, make a distinction between typed and untyped blanks on the screen, shifting upon an insert or delete only to an untyped blank on the screen which is either eliminated, or expanded to two untyped blanks. You can determine the kind of terminal you have by clearing the screen and then typing text separated by cursor motions. Type ``abc def'' using local cursor motions (not spaces) between the abc and the def. Then position the cursor before the abc and put the terminal in insert mode. If typing characters causes the rest of the line to shift rigidly and characters to fall off the end, then your terminal does not distinguish between blanks and untyped positions. If the abc shifts over to the def which then move together around the end of the current line and onto the next as you insert, you have the second type of terminal, and should give the capability in, which stands for ``insert null.'' While these are two logically separate attributes (one line versus multiline insert mode, and special treatment of untyped spaces) we have seen no terminals whose insert mode cannot be described with the single attribute. Terminfo Source Format (ENHANCED CURSES) Device Capabilities terminfo can describe both terminals that have an insert mode and terminals which send a simple sequence to open a blank position on the current line. Give as smir the sequence to get into insert mode. Give as rmir the sequence to leave insert mode. Now give as ich1 any sequence needed to be sent just before sending the character to be inserted. Most terminals with a true insert mode will not give ich1; terminals that send a sequence to open a screen position should give it here. (If your terminal has both, insert mode is usually preferable to ich1. Do not give both unless the terminal requires both to be used in combination.) If post-insert padding is needed, give this as a number of milliseconds padding in ip (a string option). Any other sequence which may need to be sent after an insert of a single character may also be given in ip. If your terminal needs both to be placed into an ``insert mode'' and a special code to precede each inserted character, then both smir/rmir and ich1 can be given, and both will be used. The ich capability, with one argument, n, will insert n blanks. If padding is necessary between characters typed while not in insert mode, give this as a number of milliseconds padding in rmp. It is occasionally necessary to move around while in insert mode to delete characters on the same line (for example, if there is a tab after the insertion position). If your terminal allows motion while in insert mode you can give the capability mir to speed up inserting in this case. Omitting mir will affect only speed. Some terminals (notably Datamedia) must not have mir because of the way their insert mode works. Finally, you can specify dch1 to delete a single character, dch with one argument, n, to delete n characters, and delete mode by giving smdc and rmdc to enter and exit delete mode (any mode the terminal needs to be placed in for dch1 to work). A command to erase n characters (equivalent to outputting n blanks without moving the cursor) can be given as ech with one argument. Device Capabilities Terminfo Source Format (ENHANCED CURSES) 6.2.7 Highlighting, Underlining, and Visible Bells Your device may have one or more kinds of display attributes that allow you to highlight selected characters when they appear on the screen. The following display modes (shown with the names by which they are set) may be available: o A blinking screen (blink) o Bold or extra-bright characters (bold) o Dim or half-bright characters (dim) o Blanking or invisible text (invis) o Protected text (prot) o A reverse-video screen (rev) o An alternate character set (smacs to enter this mode and rmacs to exit it) (If a command is necessary before you can enter alternate character set mode, give the sequence in enacs or ``enable alternate-character-set'' mode.) Turning on any of these modes singly may turn off other modes. sgr0 should be used to turn off all video enhancement capabilities. It should always be specified because it represents the only way to turn off some capabilities, such as dim or blink. Choose one display method as standout mode and use it to highlight error messages and other text to which you want to draw attention. Choose a form of display that provides strong contrast but that is easy on the eyes. (We recommend reverse-video plus half-bright or reverse-video alone.) The sequences to enter and exit standout mode are given as smso and rmso, respectively. If the code to change into or out of standout mode leaves one or even two blank spaces on the screen, as the TVI 912 and Teleray 1061 do, then xmc should be given to tell how many spaces are left. Sequences to begin underlining and end underlining can be specified as smul and rmul, respectively. If the device has a sequence to underline the current character and to move the cursor one space to the right (such as the Micro-Term MIME), this sequence can be specified as uc. Terminfo Source Format (ENHANCED CURSES) Device Capabilities Terminals with the ``magic cookie'' glitch (xmc) deposit special ``cookies'' when they receive mode- setting sequences, which affect the display algorithm rather than having extra bits for each character. Some terminals, such as the Hewlett-Packard 2621, automatically leave standout mode when they move to a new line or the cursor is addressed. Programs using standout mode should exit standout mode before moving the cursor or sending a newline, unless the msgr capability, asserting that it is safe to move in standout mode, is present. If the terminal has a way of flashing the screen to indicate an error quietly (a bell replacement), then this can be given as flash; it must not move the cursor. A good flash can be done by changing the screen into reverse video, pad for 200 ms, then return the screen to normal video. If the cursor needs to be made more visible than normal when it is not on the bottom line (to make, for example, a non-blinking underline into an easier to find block or blinking underline) give this sequence as cvvis. The boolean chts should also be given. If there is a way to make the cursor completely invisible, give that as civis. The capability cnorm should be given, which undoes the effects of either of these modes. If your terminal generates underlined characters by using the underline character (with no special sequences needed) even though it does not otherwise overstrike characters, then specify the capability ul. For devices on which a character overstriking another leaves both characters on the screen, specify the capability os. If overstrikes are erasable with a blank, then this should be indicated by specifying eo. If there is a sequence to set arbitrary combinations of modes, this should be given as sgr (set attributes), taking nine arguments. Each argument is either 0 or non-zero, as the corresponding attribute is on or off. The nine arguments are, in order: standout, underline, reverse, blink, dim, bold, blank, protect, alternate character set. Not all modes need to be supported by sgr; only those for which corresponding separate attribute commands exist should be supported. For example, let's assume that the terminal in question needs the following escape sequences to turn on various modes. Device Capabilities Terminfo Source Format (ENHANCED CURSES) tparm Argument Attribute Escape Sequence none \E[0m p1 standout \E[0;4;7m p2 underline \E[0;3m p3 reverse \E[0;4m p4 blink \E[0;5m p5 dim \E[0;7m p6 bold \E[0;3;4m p7 invis \E[0;8m p8 protect not available p9 altcharset ^O (off) ^N (on) Note that each escape sequence requires a 0 to turn off other modes before turning on its own mode. Also note that, as suggested above, standout is set up to be the combination of reverse and dim. Also, because this terminal has no bold mode, bold is set up as the combination of reverse and underline. In addition, to allow combinations, such as underline+blink, the sequence to use would be \E[0;3;5m. The terminal doesn't have protect mode, either, but that cannot be simulated in any way, so p8 is ignored. The altcharset mode is different in that it is either ^O or ^N, depending on whether it is off or on. If all modes were to be turned on, the sequence would be: \E[0;3;4;5;7;8m^N Now look at when different sequences are output. For example, ;3 is output when either p2 or p6 is true, that is, if either underline or bold modes are turned on. Writing out the above sequences, along with their dependencies, gives the following: Sequence When to Output terminfo Translation \E[0 always \E[0 ;3 if p2 or p6 %?%p2%p6%|%t;3%; ;4 if p1 or p3 or p6 %?%p1%p3%|%p6%|%t;4%; ;5 if p4 %?%p4%t;5%; ;7 if p1 or p5 %?%p1%p5%|%t;7%; ;8 if p7 %?%p7%t;8%; m always m ^N or ^O if p9 ^N, else ^O %?%p9%t^N%e^O%; Putting this all together into the sgr sequence gives: sgr=\E[0%?%p2%p6%|%t;3%;%?%p1%p3%|%p6% |%t;4%;%?%p5%t;5%;%?%p1%p5% |%t;7%;%?%p7%t;8%;m%?%p9%t^N%e^O%;, Terminfo Source Format (ENHANCED CURSES) Device Capabilities Remember that sgr and sgr0 must always be specified. 6.2.8 Keypad If the device has a keypad that transmits sequences when the keys are pressed, this information can also be specified. Note that it is not possible to handle devices where the keypad only works in local (this applies, for example, to the unshifted Hewlett-Packard 2621 keys). If the keypad can be set to transmit or not transmit, specify these sequences as smkx and rmkx. Otherwise the keypad is assumed to always transmit. The sequences sent by the left arrow, right arrow, up arrow, down arrow, and home keys can be given as kcub1, kcuf1, kcuu1, kcud1 and khome, respectively. If there are function keys such as f0, f1, ..., f63, the sequences they send can be specified as kf0, kf1, ..., kf63. If the first 11 keys have labels other than the default f0 through f10, the labels can be given as lf0, lf1, ..., lf10. The codes transmitted by certain other special keys can be given: kll (home down), kbs (backspace), ktbc (clear all tabs), kctab (clear the tab stop in this column), kclr (clear screen or erase key), kdch1 (delete character), kdl1 (delete line), krmir (exit insert mode), kel (clear to end of line), ked (clear to end of screen), kich1 (insert character or enter insert mode), kil1 (insert line), knp (next page), kpp (previous page), kind (scroll forward/down), kri (scroll backward/up), khts (set a tab stop in this column). In addition, if the keypad has a 3 by 3 array of keys including the four arrow keys, the other five keys can be given as ka1, ka3, kb2, kc1, and kc3. These keys are useful when the effects of a 3 by 3 directional pad are needed. Further keys are defined above in the capabilities list. Strings to program function keys can be specified as pfkey, pfloc, and pfx. A string to program screen labels should be specified as pln. Each of these strings takes two arguments: a function key identifier and a string to program it with. pfkey causes pressing the given key to be the same as the user typing the given string; pfloc causes the string to be executed by the terminal in local mode; and pfx causes the string to be transmitted to the computer. The capabilities nlab, lw and lh define the number of programmable screen labels and their width and height. Device Capabilities Terminfo Source Format (ENHANCED CURSES) If there are commands to turn the labels on and off, give them in smln and rmln. smln is normally output after one or more pln sequences to make sure that the change becomes visible. 6.2.9 Tabs and Initialisation If the device has hardware tabs, the command to advance to the next tab stop can be given as ht (usually control-I). A ``backtab'' command that moves leftward to the next tab stop can be given as cbt. By convention, if tty modes show that tabs are being expanded by the computer rather than being sent to the device, programs should not use ht or cbt (even if they are present) because the user might not have the tab stops properly set. If the device has hardware tabs that are initially set every n spaces when the device is powered up, the numeric argument it is given, showing the number of spaces the tabs are set to. This is normally used by tput init to determine whether to set the mode for hardware tab expansion and whether to set the tab stops. If the device has tab stops that can be saved in nonvolatile memory, the terminfo description can assume that they are properly set. If there are commands to set and clear tab stops, they can be given as tbc (clear all tab stops) and hts (set a tab stop in the current column of every row). Other capabilities include: is1, is2, and is3, initialisation strings for the device; iprog, the path name of a program to be run to initialise the device; and if, the name of a file containing long initialisation strings. These strings are expected to set the device into modes consistent with the rest of the terminfo description. They must be sent to the device each time the user logs in and be output in the following order: run the program iprog; output is1; output is2; set the margins using mgc, smgl and smgr; set the tabs using tbc and hts; print the file if; and finally output is3. This is usually done using the init option of tput. Most initialisation is done with is2. Special device modes can be set up without duplicating strings by putting the common sequences in is2 and special cases in is1 and is3. Sequences that do a reset from a totally unknown state can be given as rs1, rs2, rf, and rs3, analogous to is1, is2, is3, and if. (The method using files, if and rf, is used for a few terminals however, the recommended method is to use Terminfo Source Format (ENHANCED CURSES) Device Capabilities the initialisation and reset strings.) These strings are output by tput reset, which is used when the terminal gets into a wedged state. Commands are normally placed in rs1, rs2, rs3, and rf only if they produce annoying effects on the screen and are not necessary when logging in. For example, the command to set a terminal into 80-column mode would normally be part of is2, but on some terminals it causes an annoying glitch on the screen and is not normally needed because the terminal is usually already in 80- column mode. If a more complex sequence is needed to set the tabs than can be described by using tbc and hts, the sequence can be placed in is2 or if. Any margin can be cleared with mgc. (For instructions on how to specify commands to set and clear margins, see Margins) 6.2.10Delays Certain capabilities control padding in the tty driver. These are primarily needed by hard-copy terminals, and are used by tput init to set tty modes appropriately. Delays embedded in the capabilities cr, ind, cub1, ff, and tab can be used to set the appropriate delay bits to be set in the tty driver. If pb (padding baud rate) is given, these values can be ignored at baud rates below the value of pb. 6.2.11Status Lines If the terminal has an extra ``status line'' that is not normally used by software, this fact can be indicated. If the status line is viewed as an extra line below the bottom line, into which one can cursor address normally (such as the Heathkit H19's 25th line, or the 24th line of a VT100 which is set to a 23-line scrolling region), the capability hs should be given. Special strings that go to a given column of the status line and return from the status line can be given as tsl and fsl. (fsl must leave the cursor position in the same place it was before tsl. If necessary, the sc and rc strings can be included in tsl and fsl to get this effect.) The capability tsl takes one argument, which is the column number of the status line the cursor is to be moved to. Device Capabilities Terminfo Source Format (ENHANCED CURSES) If escape sequences and other special commands, such as tab, work while in the status line, the flag eslok can be given. A string which turns off the status line (or otherwise erases its contents) should be given as dsl. If the terminal has commands to save and restore the position of the cursor, give them as sc and rc. The status line is normally assumed to be the same width as the rest of the screen (that is, cols). If the status line is a different width (possibly because the terminal does not allow an entire line to be loaded) the width, in columns, can be indicated with the numeric argument wsl. 6.2.12Line Graphics If the device has a line drawing alternate character set, the mapping of glyph to character would be given in acsc. The definition of this string is based on the alternate character set used in the Digital VT100 terminal, extended slightly with some characters from the AT&T 4410v1 terminal. VT100+ Glyph Name Character arrow pointing right + arrow pointing left , arrow pointing down . solid square block 0 lantern symbol I arrow pointing up - diamond ` checker board (stipple) a degree symbol f plus/minus g board of squares h lower right corner j upper right corner k upper left corner l lower left corner m plus n scan line 1 o horizontal line q scan line 9 s left tee (|-) t right tee (-|) u bottom tee (|) v Terminfo Source Format (ENHANCED CURSES) Device Capabilities top tee (|) w vertical line x bullet ~ The best way to describe a new device's line graphics set is to add a third column to the above table with the characters for the new device that produce the appropriate glyph when the device is in alternate- character-set mode. For example: VT100+ Character Used Glyph Name Character on New Device upper left corner l R lower left corner m F upper right corner k T lower right corner j G horizontal line q , vertical line x . Now write down the characters left to right; for example: acsc=lRmFkTjGq\,x. In addition, terminfo lets you define multiple character sets (see Section 6.3.5). 6.2.13Colour Manipulation Most colour terminals belong to one of two classes of terminal: o Tektronix-style The Tektronix method uses a set of N predefined colours (usually 8) from which an application can select "current" foreground and background colours. Thus a terminal can support up to N colours mixed into N*N colour-pairs to be displayed on the screen at the same time. o Hewlett-Packard-style In the HP method, the application cannot define the foreground independently of the background, or vice-versa. Instead, the application must define an entire colour-pair at once. Up to M colour-pairs, made from 2*M different colours, can be defined this way. Device Capabilities Terminfo Source Format (ENHANCED CURSES) The numeric variables colors and pairs define the number of colours and colour-pairs that can be displayed on the screen at the same time. If a terminal can change the definition of a colour (for example, the Tektronix 4100 and 4200 series terminals), this should be specified with ccc (can change colour). To change the definition of a colour (Tektronix 4200 method), use initc (initialise colour). It requires four arguments: colour number (ranging from 0 to colors-1) and three RGB (red, green, and blue) values or three HLS colours (Hue, Lightness, Saturation). Ranges of RGB and HLS values are terminal-dependent. Tektronix 4100 series terminals only use HLS colour notation. For such terminals (or dual-mode terminals to be operated in HLS mode) one must define a boolean variable hls; that would instruct the init_color() functions to convert its RGB arguments to HLS before sending them to the terminal. The last three arguments to the initc string would then be HLS values. If a terminal can change the definitions of colours, but uses a colour notation different from RGB and HLS, a mapping to either RGB or HLS must be developed. If the terminal supports ANSI escape sequences to set background and foreground, they should be coded as setab and setaf, respectively. If the terminal supports other escape sequences to set background and foreground, they should be coded as setb and setf, respectively. The vidputs() function and the refresh functions use setab and setaf if they are defined. Each of these capabilities requires one argument: the number of the colour. By convention, the first eight colours (0-7) map to, in order: black, red, green, yellow, blue, magenta, cyan, white. However, colour re-mapping may occur or the underlying hardware may not support these colours. Mappings for any additional colours supported by the device (that is, to numbers greater than 7) are at the discretion of the terminfo entry writer. To initialise a colour-pair (HP method), use initp (initialise pair). It requires seven arguments: the number of a colour-pair (range=0 to pairs-1), and six RGB values: three for the foreground followed by three for the background. (Each of these groups of three should be in the order RGB.) When initc or initp are used, RGB or HLS arguments should be in the order "red, green, blue" or "hue, lightness, saturation"), Terminfo Source Format (ENHANCED CURSES) Device Capabilities respectively. To make a colour-pair current, use scp (set colour-pair). It takes one argument, the number of a colour-pair. Some terminals (for example, most colour terminal emulators for PCs) erase areas of the screen with current background colour. In such cases, bce (background colour erase) should be defined. The variable op (original pair) contains a sequence for setting the foreground and the background colours to what they were at the terminal start-up time. Similarly, oc (original colours) contains a control sequence for setting all colours (for the Tektronix method) or colour-pairs (for the HP method) to the values they had at the terminal start-up time. Some colour terminals substitute colour for video attributes. Such video attributes should not be combined with colours. Information about these video attributes should be packed into the ncv (no colour video) variable. There is a one-to-one correspondence between the nine least significant bits of that variable and the video attributes. The following table depicts this correspondence. Bit Decimal Characteristic Attribute Position Value That Sets WA_STANDOUT 0 1 sgr, parameter 1 WA_UNDERLINE 1 2 sgr, parameter 2 WA_REVERSE 2 4 sgr, parameter 3 WA_BLINK 3 8 sgr, parameter 4 WA_DIM 4 16 sgr, parameter 5 WA_BOLD 5 32 sgr, parameter 6 WA_INVIS 6 64 sgr, parameter 7 WA_PROTECT 7 128 sgr, parameter 8 WA_ALTCHARSET 8 256 sgr, parameter 9 WA_HORIZONTAL 9 512 sgr1, parameter 1 WA_LEFT 10 1024 sgr1, parameter 2 WA_LOW 11 2048 sgr1, parameter 3 WA_RIGHT 12 4096 sgr1, parameter 4 WA_TOP 13 8192 sgr1, parameter 5 WA_VERTICAL 14 16384 sgr1, parameter 6 When a particular video attribute should not be used with colours, set the corresponding ncv bit to 1; otherwise set it to 0. To determine the information to pack into the ncv variable, add the decimal values corresponding to those attributes that cannot coexist with colours. For example, if the terminal uses colours to simulate reverse video (bit number 2 and decimal value 4) and bold (bit number 5 and decimal Device Capabilities Terminfo Source Format (ENHANCED CURSES) value 32), the resulting value for ncv will be 36 (4 + 32). 6.2.14Miscellaneous If the terminal requires other than a null (zero) character as a pad, then this can be given as pad. Only the first character of the pad string is used. If the terminal does not have a pad character, specify npc. If the terminal can move up or down half a line, this can be indicated with hu (half-line up) and hd (half- line down). This is primarily useful for superscripts and subscripts on hardcopy terminals. If a hardcopy terminal can eject to the next page (form feed), give this as ff (usually control-L). If there is a command to repeat a given character a given number of times (to save time transmitting a large number of identical characters) this can be indicated with the argumentised string rep. The first argument is the character to be repeated and the second is the number of times to repeat it. Thus, tparm(repeat_char, 'x', 10) is the same as xxxxxxxxxx. If the terminal has a settable command character, such as the Tektronix 4025, this can be indicated with cmdch. A prototype command character is chosen which is used in all capabilities. This character is given in the cmdch capability to identify it. The following convention is supported on some systems: If the environment variable CC exists, all occurrences of the prototype character are replaced with the character in CC. Terminal descriptions that do not represent a specific kind of known terminal, such as switch, dialup, patch, and network, should include the gn (generic) capability so that programs can complain that they do not know how to talk to the terminal. (This capability does not apply to virtual terminal descriptions for which the escape sequences are known.) If the terminal is one of those supported by the virtual terminal protocol, the terminal number can be given as vt. A line-turn-around sequence to be transmitted before doing reads should be specified in rfi. If the device uses xon/xoff handshaking for flow control, give xon. Padding information should still Terminfo Source Format (ENHANCED CURSES) Device Capabilities be included so that functions can make better decisions about costs, but actual pad characters will not be transmitted. Sequences to turn on and off xon/xoff handshaking may be given in smxon and rmxon. If the characters used for handshaking are not ^S and ^Q, they may be specified with xonc and xoffc. If the terminal has a ``meta key'' which acts as a shift key, setting the 8th bit of any character transmitted, this fact can be indicated with km. Otherwise, software will assume that the 8th bit is parity and it will usually be cleared. If strings exist to turn this ``meta mode'' on and off, they can be given as smm and rmm. If the terminal has more lines of memory than will fit on the screen at once, the number of lines of memory can be indicated with lm. A value of lm#0 indicates that the number of lines is not fixed, but that there is still more memory than fits on the screen. Media copy strings which control an auxiliary printer connected to the terminal can be given as: mc0 Print the contents of the screen mc4 Turn off the printer mc5 Turn on the printer When the printer is on, all text sent to the terminal will be sent to the printer. A variation, mc5p, takes one argument, and leaves the printer on for as many characters as the value of the argument, then turns the printer off. The argument should not exceed 255. If the text is not displayed on the terminal screen when the printer is on, specify mc5i (silent printer). All text, including mc4, is transparently passed to the printer while an mc5p is in effect. 6.2.15Special Cases The working model used by terminfo fits most terminals reasonably well. However, some terminals do not completely match that model, requiring special support by terminfo. These are not meant to be construed as deficiencies in the terminals; they are just differences between the working model and the actual hardware. They may be unusual devices or, for some reason, do not have all the features of the terminfo model implemented. Device Capabilities Terminfo Source Format (ENHANCED CURSES) Terminals that cannot display tilde (~) characters, such as certain Hazeltine terminals, should indicate hz. Terminals that ignore a linefeed immediately after an am wrap, such as the Concept 100, should indicate xenl. Those terminals whose cursor remains on the right-most column until another character has been received, rather than wrapping immediately upon receiving the right-most character, such as the VT100, should also indicate xenl. If el is required to get rid of standout (instead of writing normal text on top of it), xhp should be given. Those Teleray terminals whose tabs turn all characters moved over to blanks, should indicate xt (destructive tabs). This capability is also taken to mean that it is not possible to position the cursor on top of a ``magic cookie.'' Therefore, to erase standout mode, it is necessary, instead, to use delete and insert line. For Beehive Superbee terminals that do not transmit the escape or control-C characters, specify xsb, indicating that the f1 key is to be used for escape and the f2 key for control-C. 6.2.16Similar Terminals If there are two similar terminals, one can be defined as being just like the other with certain exceptions. The string capability use can be given with the name of the similar terminal. The capabilities given before use override those in the terminal type invoked by use. A capability can be canceled by placing capability-name@ prior to the appearance of the string capability use. For example, the entry: att4424-2|Teletype 4424 in display function group ii, rev@, sgr@, smul@, use=att4424, defines an AT&T 04424 terminal that does not have the rev, sgr, and smul capabilities, and hence cannot do highlighting. This is useful for different modes for a terminal, or for different user preferences. More than one use capability may be given. Terminfo Source Format (ENHANCED CURSES)Printer Capabilities 6.3 Printer Capabilities The terminfo database lets you define capabilities of printers as well as terminals. Capabilities available for printers are included in the lists in Section 6.1.3. 6.3.1 Rounding Values Because argumentised string capabilities work only with integer values, terminfo designers should create strings that expect numeric values that have been rounded. Application designers should note this and should always round values to the nearest integer before using them with a argumentised string capability. 6.3.2 Printer Resolution A printer's resolution is defined to be the smallest spacing of characters it can achieve. In general, the horizontal and vertical resolutions are independent. Thus the vertical resolution of a printer can be determined by measuring the smallest achievable distance between consecutive printing baselines, while the horizontal resolution can be determined by measuring the smallest achievable distance between the leftmost edges of consecutive printed, identical, characters. All printers are assumed to be capable of printing with a uniform horizontal and vertical resolution. The view of printing that terminfo currently presents is one of printing inside a uniform matrix: All characters are printed at fixed positions relative to each ``cell'' in the matrix; furthermore, each cell has the same size given by the smallest horizontal and vertical step sizes dictated by the resolution. (The cell size can be changed as will be seen later.) Many printers are capable of ``proportional printing,'' where the horizontal spacing depends on the size of the character last printed. terminfo does not make use of this capability, although it does provide enough capability definitions to allow an application to simulate proportional printing. A printer must not only be able to print characters as close together as the horizontal and vertical resolutions suggest, but also of ``moving'' to a Printer CapabilitiesTerminfo Source Format (ENHANCED CURSES) position an integral multiple of the smallest distance away from a previous position. Thus printed characters can be spaced apart a distance that is an integral multiple of the smallest distance, up to the length or width of a single page. Some printers can have different resolutions depending on different ``modes.'' In ``normal mode,'' the existing terminfo capabilities are assumed to work on columns and lines, just like a video terminal. Thus the old lines capability would give the length of a page in lines, and the cols capability would give the width of a page in columns. In ``micro mode,'' many terminfo capabilities work on increments of lines and columns. With some printers the micro mode may be concomitant with normal mode, so that all the capabilities work at the same time. 6.3.3 Specifying Printer Resolution The printing resolution of a printer is given in several ways. Each specifies the resolution as the number of smallest steps per distance: Characteristic Number of Smallest Steps orhi Steps per inch horizontally orvi Steps per inch vertically orc Steps per column orl Steps per line When printing in normal mode, each character printed causes movement to the next column, except in special cases described later; the distance moved is the same as the per-column resolution. Some printers cause an automatic movement to the next line when a character is printed in the rightmost position; the distance moved vertically is the same as the per-line resolution. When printing in micro mode, these distances can be different, and may be zero for some printers. Automatic Motion after Printing Normal Mode: orc Steps moved horizontally orl Steps moved vertically Terminfo Source Format (ENHANCED CURSES)Printer Capabilities Micro Mode: mcs Steps moved horizontally mls Steps moved vertically Some printers are capable of printing wide characters. The distance moved when a wide character is printed in normal mode may be different from when a regular width character is printed. The distance moved when a wide character is printed in micro mode may also be different from when a regular character is printed in micro mode, but the differences are assumed to be related: If the distance moved for a regular character is the same whether in normal mode or micro mode (mcs=orc), then the distance moved for a wide character is also the same whether in normal mode or micro mode. This doesn't mean the normal character distance is necessarily the same as the wide character distance, just that the distances don't change with a change in normal to micro mode. However, if the distance moved for a regular character is different in micro mode from the distance moved in normal mode (mcs