XCURSES Revision Page 1 of 1 Submitted by Andrew Josey, The Open Group. May 15, 2007 Below are the current items for updates to form an XCURSES Issue 4 V3 specification. To participate in the development and review you can the ogcurses@opengroup.org mailing list If you have further items you believe should be addressed please submit a defect report at http://www.unix.org/defectform.html ============================== 1. Prototype updates for const Enclosed are the proposed prototype updates for C610 , X/Open Curses Issue 4 Version 2. extern const char * keyname (int); extern int mvscanw (int,int, const char *,...); extern int mvwscanw (WINDOW *,int,int, const char *,...); extern SCREEN * newterm (const char *,FILE *,FILE *); extern int scanw (const char *,...); extern int tigetflag (const char *); extern int tigetnum (const char *); extern char * tigetstr (const char *); extern char * tparm (const char *, ...); extern int vwscanw (WINDOW *, const char *,va_list); extern int vw_scanw (WINDOW *, const char *,va_list); extern int wscanw (WINDOW *, const char *,...); ======================= 2. Other changes to be rolled into a V3 edition of the specification: An X/Open Curses Issue 4 Version 3 specification could include the above prototype changes plus the following corrigenda U058 dated 03/03 which incorporates all corrigenda to date: Corrigendum: U058 Date: 03/03 Document: C610 X/Open Curses, Issue 4, Version 2 Code: 16320 03/03 C610/U058 Contents: This corrigendum incorporates: U056 (November 2001) U036 (September 1998) U022 (May 1997) U018 (February 1997) ---------------------------------------------------------------------------- Note: X/Open Curses, Issue 4, Version 2 can exist in either or all of the following environments: - System Interfaces and Headers, Issue 4, Version 2 - System Interfaces and Headers, Issue 5 - System Interfaces, Issue 6 The Base Environment section of each change denotes the environment to which the change is applicable. ---------------------------------------------------------------------------- Change Number: U058/1 In the header, move the function prototypes for COLOR_PAIR on Page 227 and PAIR_NUMBER on Page 231 from under the heading ``The following are declared as functions, and may also be defined as macros:'' to Page 223 under a new sub-heading ``Colour-related Macros'' as follows: Colour-related Macros The following colour-related macros are defined, and may also be declared as functions: int COLOR_PAIR(int n); int PAIR_NUMBER(int value); Base Environment(s): System Interfaces and Headers, Issue 4, Version 2 System Interfaces and Headers, Issue 5 System Interfaces, Issue 6 ---------------------------------------------------------------------------- ---------------------------------------------------------------------------- Start of Corrigendum U056 (November 2001). ---------------------------------------------------------------------------- Change Number: U056/1 On environments supporting System Interfaces, Issue 6, replace Section 2.2 with the following text: 2.2 The Compilation Environment Applications should ensure that the feature test macro _XOPEN_SOURCE is defined before inclusion of any header. This is needed to enable the functionality described in this document, and possibly to enable functionality defined elsewhere in the Common Applications Environment. The _XOPEN_SOURCE macro may be defined automatically by the compilation process, but to ensure maximum portability, applications should make sure that _XOPEN_SOURCE is defined by using either compiler options or #define directives in the source files, before any #include directives. Identifiers in this document may only be undefined using the #undef directive as described in Chapter 2 or Section 2.2.1. These #undef directives must follow all #include directives of any XSI headers. Most strictly conforming POSIX and ISO C applications will compile on systems conformant with this specification. However, an application which uses any of the items marked as an extension to POSIX and ISO C, for any purpose other than that shown here, may not compile. In such cases, it may be necessary to alter those applications to use alternative identifiers. Since this document is aligned with the ISO C standard, and since all functionality enabled by _POSIX_C_SOURCE set equal to 200xxxL is enabled by _XOPEN_SOURCE set equal to 600, there should be no need to define _POSIX_C_SOURCE if _XOPEN_SOURCE is so defined. Therefore, if _XOPEN_SOURCE is set equal to 600 and _POSIX_C_SOURCE is set equal to 200xxxL, the behavior is the same as if only _XOPEN_SOURCE is defined and set equal to 600. However, should _POSIX_C_SOURCE be set to a value greater than 200xxxL, the behavior is unspecified. The c99 utility shall recognize the additional -l operand for standard libraries: -l curses This operand makes visible all library functions referenced in this specification (except for those labelled ENHANCED CURSES and except for portions marked with the EC margin legend). [EC] If the implementation defines _XOPEN_CURSES and if the application defines the _XOPEN_SOURCE feature test macro with the value 600 before including any header, then -l curses also makes visible all library functions referenced in this specification and labelled ENHANCED CURSES and portions marked with the EC margin legend. [END EC] It is unspecified whether the library libcurses.a exists as a regular file. [EC] An application that uses any API specified as ENHANCED CURSES or relies on any portion of this specification marked with the EC margin legend must define _XOPEN_SOURCE = 600 in each source file or as part of its compilation environment. [END EC] Base Environment: System Interfaces, Issue 6 ------------------------------------------------------------------------- Change Number: U056/2 On environments supporting System Interfaces, Issue 6, change the following text within the reference page: From: These attribute flags need not be distinct [EC] except when _XOPEN_CURSES is defined and the application sets _XOPEN_SOURCE_EXTENDED to 1. [END EC] To: These attribute flags need not be distinct [EC] except when _XOPEN_CURSES is defined and the application sets _XOPEN_SOURCE = 600. [END EC] Base Environment: System Interfaces, Issue 6 ------------------------------------------------------------------------- Change Number: U056/3 On environments supporting System Interfaces, Issue 6, change the following text within the reference page: From: The following data types are defined through typedef: .... bool Boolean data type To: The following data types are defined through typedef: .... bool As described in Base Environment: System Interfaces, Issue 6 ---------------------------------------------------------------------------- ---------------------------------------------------------------------------- Start of Corrigendum U036 (September 1998). ---------------------------------------------------------------------------- Change Number: U036/1 On Page 11 add new text as follows: 2.3.2 Thread Safety The interfaces defined by this document need not be thread-safe. ---------------------------------------------------------------------------- ---------------------------------------------------------------------------- Start of Corrigendum U022 (May 1997). ---------------------------------------------------------------------------- Change Number: U022/1 On the manual page, shade the addchnstr() prototype as an EC extension and unshade the addchstr() prototype. ---------------------------------------------------------------------------- Change Number: U022/2 On the border() manual page, change the macros ACS_BLCORNER and ACS_BRCORNER to ACS_LLCORNER and ACS_LRCORNER respectively. ---------------------------------------------------------------------------- ---------------------------------------------------------------------------- Start of Corrigendum U018 (February 1997). Note: X/Open Curses, Issue 4, Version 2 can exist in either or both of the following environments: - System Interfaces and Headers, Issue 4, Version 2 - System Interfaces and Headers, Issue 5 The Base Environment section of each change denotes the environment to which the change is applicable. ---------------------------------------------------------------------------- Change Number: U018/1 On the getn_wstr() manual page (Page 96), replace the prototypes for getn_wstr() and get_wstr() with: int getn_wstr(wint_t *wstr, int n); int get_wstr(wint_t *wstr); Base Environment: System Interfaces and Headers, Issue 4, Version 2 System Interfaces and Headers, Issue 5 ------------------------------------------------------------------------- Change Number: U018/2 On environments supporting System Interfaces and Headers, Issue 5 replace Section 2.2 with the following text: 2.2 The Compilation Environment Applications should ensure that the feature test macro _XOPEN_SOURCE is defined before inclusion of any header. This is needed to enable the functionality described in this document, and possibly to enable functionality defined elsewhere in the Common Applications Environment. The _XOPEN_SOURCE macro may be defined automatically by the compilation process, but to ensure maximum portability, applications should make sure that _XOPEN_SOURCE is defined by using either compiler options or #define directives in the source files, before any #include directives. Identifiers in this document may only be undefined using the #undef directive as described in Chapter 2 on page 11 or Section 2.2.1 on page 14. These #undef directives must follow all #include directives of any XSI headers. Most strictly conforming POSIX and ISO C applications will compile on systems conformant with this specification. However, an application which uses any of the items marked as an extension to POSIX and ISO C, for any purpose other than that shown here, may not compile. In such cases, it may be necessary to alter those applications to use alternative identifiers. Since this document is aligned with the ISO C standard, and since all functionality enabled by _POSIX_C_SOURCE set greater than zero and less than or equal to 199506L should be enabled by _XOPEN_SOURCE, there should be no need to define either _POSIX_SOURCE or _POSIX_C_SOURCE if _XOPEN_SOURCE is defined. Therefore, if _XOPEN_SOURCE is defined and _POSIX_SOURCE is defined, or _POSIX_C_SOURCE is set greater than zero and less than or equal to 199506L, the behavior is the same as if only _XOPEN_SOURCE is defined. However, should _POSIX_C_SOURCE be set to a value greater than 199506L, the behavior is undefined. The c89 and cc utilities recognize the additional -l operand for standard libraries: -l curses This operand makes visible all library functions referenced in this specification (except for those labelled ENHANCED CURSES and except for portions marked with the EC margin legend). [EC] If the implementation defines _XOPEN_CURSES and if the application defines the _XOPEN_SOURCE feature test macro with the value 500 before including any header, then -l curses also makes visible all library functions referenced in this specification and labelled ENHANCED CURSES and portions marked with the EC margin legend. [END EC] It is unspecified whether the library libcurses.a exists as a regular file. [EC] An application that uses any API specified as ENHANCED CURSES or relies on any portion of this specification marked with the EC margin legend must define _XOPEN_SOURCE = 500 in each source file or as | part of its compilation environment. [END EC] If the implementation supports the utilities marked DEVELOPMENT in the XCU specification, the lint utility recognizes the additional -l curses operand for standard libraries: -l curses Names the library llib-lcurses.ln, which will contain functions specified in this document. It is unspecified whether the library llib-lcurses.ln exists as a regular file. Base Environment: System Interfaces and Headers, Issue 5 ------------------------------------------------------------------------- Change Number: U018/3 On environments supporting System Interfaces and Headers, Issue 5, change the following text within the manual page: From: These attribute flags need not be distinct [EC] except when _XOPEN_CURSES is defined and the application sets _XOPEN_SOURCE_EXTENDED to 1. [END EC] To: These attribute flags need not be distinct [EC] except when _XOPEN_CURSES is defined and the application sets _XOPEN_SOURCE=500. [END EC] Base Environment: System Interfaces and Headers, Issue 4, Version 2 System Interfaces and Headers, Issue 5 ------------------------------------------------------------------------- Change Number: U018/4 Replace the first three paragraphs of Section 3.2, Windows, with the following: The Curses functions permit manipulation of window objects which can be thought of as two-dimensional arrays of characters and their renditions representing all or part of a terminal's physical screen. Windows do not have to correspond to the entire screen. It is possible to create smaller windows and also to indicate that a window is only partially visible on the screen. It is possible to create windows larger than the terminal screen using pads. A default window called stdscr, which is the size of the terminal screen, is supplied. Others may be created with newterm(). Data structures declared as WINDOW refer to windows (and to subwindows, derived windows, pads and subpads, as described elsewhere). These data structures are manipulated with functions described in Chapter 6. Among the most basic functions are move() and addch() which manipulate the default window stdscr, and refresh() which tells Curses to update the user's screen from stdscr. More general versions of these functions enable specific windows to be manipulated and refreshed. Replace the definition of a pad with the following: A pad is a specialized case of a window which can be bigger than the actual screen size and is not necessarily associated with a particular part of the screen. Pads should be used whenever a window larger than the terminal screen is required. Add a definition of a subpad as follows: Subpad A subpad is a specialized case of a window created within another pad. On Page 74 (newwin()), add the following to the end of the 2nd paragraph of the DESCRIPTION: The size of a window cannot be greater than the physical size of the screen, or that defined using the environment variables LINES and COLUMNS. The behavior of a window which extends outside the terminal screen is undefined. Add the following paragraph to APPLICATION USAGE: Pads should be used whenever a window larger than the terminal screen is required. On Page 150 (newpad()), replace the first two paragraphs of the DESCRIPTION with the following: The newpad() function creates a specialized window called a pad with nlines lines and ncols columns. A pad is like a window, except that it is not restricted by the screen size and is not necessarily associated with a particular part of the screen. Automatic refreshes of pads (e.g., from scrolling or echoing of input) do not occur. The subpad() function creates a specialized window within a pad (called the parent pad) called a subpad with nlines lines and ncols columns. Unlike subwin() which uses screen coordinates, the subpad is created at position (begin_y, begin_x) within the parent pad. Changes made to either the parent pad or the subpad affect the other. The subpad must fit totally within the parent pad. Delete the second sentence in APPLICATION USAGE. Add the following paragraph to APPLICATION USAGE: Pads should be used whenever a window larger than the terminal screen is required. Base Environment: System Interfaces and Headers, Issue 4, Version 2 System Interfaces and Headers, Issue 5 ------------------------------------------------------------------------- Change Number: U018/5 The prototypes for vwprintw(), vw_printw(), vwscanw() and vw_scanw() differ between the manual pages and the header page. The correct prototypes are as per the manual pages. The should be updated as follows: int vwprintw(WINDOW *, char *, va_list); int vw_printw(WINDOW *, char *, va_list); int vwscanw(WINDOW *, char *, va_list); int vw_scanw(WINDOW *, char *, va_list); Base Environment: System Interfaces and Headers, Issue 4, Version 2 System Interfaces and Headers, Issue 5 ------------------------------------------------------------------------- ======= 3. Changes to Issue 7 We would also need to include changes to support Issue 7 environments