Use and Implementation of Curses Interfaces

See Corrigendum U018.

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.

As a result of changes introduced in this version of the Curses specification, application writers are only required to include the minimum number of headers. Implementations of XSI-conformant systems will make all necessary symbols visible as described in the Headers section of this document.

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.

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 or . These #undef directives must follow all #include directives of any XSI headers.

Most strictly conforming POSIX and ISO C applications will compile on systems compliant to 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 the _POSIX_C_SOURCE set equal to 2 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 equal to 1 or 2, the behaviour is the same as if only _XOPEN_SOURCE is defined. However should _POSIX_C_SOURCE be set to a value greater than 2, the behaviour is undefined.

The c89 and cc utilities recognise 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). If the implementation defines _XOPEN_CURSES and if the application defines the _XOPEN_SOURCE_EXTENDED feature test macro, 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.

It is unspecified whether the library libcurses.a exists as a regular file.

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_EXTENDED = 1 in each source file or as part of its compilation environment. When _XOPEN_SOURCE_EXTENDED = 1 is defined in a source file, it must appear before any header is included.

If the implementation supports the utilities marked DEVELOPMENT in the XCU specification, the lint utility recognises 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.

The X/Open Name Space (ENHANCED CURSES)

The requirements in this section are in effect only for implementations that claim Enhanced Curses compliance.

All identifiers in this document are defined in at least one of the headers, as shown in . When _XOPEN_SOURCE is defined, each header defines or declares some identifiers, potentially conflicting with identifiers used by the application. The set of identifiers visible to the application consists of precisely those identifiers from the header pages of the included headers, as well as additional identifiers reserved for the implementation. In addition, some headers may make visible identifiers from other headers as indicated on the relevant header pages.

The identifiers reserved for use by the implementation are described below.

1. Each identifier with external linkage described in the header section is reserved for use as an identifier with external linkage if the header is included.

2. Each macro name described in the header section is reserved for any use if the header is included.

3. Each identifier with file scope described in the header section is reserved for use as an identifier with file scope in the same name space if the header is included.

4. All identifiers consisting of exactly 2 upper-case letters.

If any header is included, identifiers with the _t suffix are reserved for any use by the implementation.

If any header in the following table is included, macros with the prefixes shown may be defined. After the last inclusion of a given header, an application may use identifiers with the corresponding prefixes for its own purpose, provided their use is preceded by an #undef of the corresponding macro.

Header	Prefix
<curses.h>	A_, ACS_, ALL_, BUTTON, COLOR_, KEY_, MOUSE, REPORT_, WA_, WACS_
<term.h>	ext_

The following identifiers are reserved regardless of the inclusion of headers:

1. All identifiers that begin with an underscore and either an upper-case letter or another underscore are always reserved for any use by the implementation.

2. All identifiers that begin with an underscore are always reserved for use as identifiers with file scope in both the ordinary identifier and tag name spaces.

3. All identifiers listed as reserved in the XSH specification are reserved for use as identifiers with external linkage.

All the identifiers defined in this document that have external linkage are always reserved for use as identifiers with external linkage.

No other identifiers are reserved.

Applications must not declare or define identifiers with the same name as an identifier reserved in the same context. Since macro names are replaced whenever found, independent of scope and name space, macro names matching any of the reserved identifier names must not be defined if any associated header is included.

Headers may be included in any order, and each may be included more than once in a given scope, with no difference in effect from that of being included only once.

If used, a header must be included outside of any external declaration or definition, and it must be first included before the first reference to any type or macro it defines, or to any function or object it declares. However, if an identifier is declared or defined in more than one header, the second and subsequent associated headers may be included after the initial reference to the identifier. Prior to the inclusion of a header, the program must not define any macros with names lexically identical to symbols defined by that header.

Interfaces Implemented as Macros (ENHANCED CURSES)

The requirements in this section are in effect only for implementations that claim Enhanced Curses compliance.

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 list other macros, like COLOR_BLACK, that do not take arguments.

Relationship to the XSH Specification

Error Numbers

Most functions provide an error number in errno which is either a variable or macro defined in <errno.h>; the macro expands to a modifiable lvalue of type int.

A list of valid values for errno and advice to application writers on the use of errno appears in the XSH specification.

Data Types

  All of the data types used by Curses functions are defined by the implementation. The following list describes these types:

attr_t

An integral type that can contain at least an unsigned short. The type attr_t is used to hold an OR-ed set of attributes defined in <curses.h> that begin with the prefix WA_.

bool

Boolean data type

chtype

An integral type that can contain at least an unsigned char and attributes. Values of type chtype are formed by OR-ing together an unsigned char value and zero or more of the base attribute flags defined in that have the A_ prefix. The application can extract these components of a chtype value using the base masks defined in <curses.h> for this purpose. The chtype data type also contains a colour-pair. Values of type chtype are formed by OR-ing together an unsigned char value, a colour pair, and zero or more of the attributes defined in <curses.h> that begin with the prefix A_. The application can extract these components of a chtype value using the masks defined in <curses.h> for this purpose.

SCREEN

An opaque terminal representation.

wchar_t

As described in <stddef.h>.

cchar_t

A type that can reference a string of wide characters of up to an implementation-dependent length, a colour-pair, and zero or more attributes from the set of all attributes defined in this document. A null cchar_t object is an object that references a empty wide-character string. Arrays of cchar_t objects are terminated by a null cchar_t object.

WINDOW

An opaque window representation.