Base WG Resolution Ref: bwg2000-005
Topic: OK return values

This is an unapproved draft Base Working Group Resolution for X/Open Curses Issue 4 Version 2.

Last update: 02 June,2000

								2000 #005


	Topic:			OK return values
	Relevant Sections:	tgetent, tgetflag, tgetnum
	Spec:			X/Open Curses Issue 4 Version 2

Resolution Request:

References in document (e.g. page, clause, figure, and/or table
numbers or URL if applicable):

Nature of defect (complete, concise explanation of the perceived

Historical practice is that tgetent() returns -1 if the terminfo/termcap
database is not found, 0 if the terminal name is not found, and 1
if successful.  tgetflag() returns 1 if the capability is present,
otherwise 0.

tgetnum() returns the numerical value if found, otherwise -1.  Almost all
current UNIX systems follow this historical practice (despite what their
manual pages say).

The specification says these functions return OK if successful,
otherwise ERR.

Most UNIX systems define OK as 0 in term.h/curses.h, and define ERR as -1.

An application which calls tgetent() and checks that it returns OK will
fail on most systems.

If an implementation is changed to conform to the specification, existing
applications which call tgetent() and check that it returns 1 will fail,
and tgetnum() will be almost useless.

(Since these functions are only provided as a "conversion aid",
applications which call them will have been written expecting the
historical practice.)

Solution proposed by the submitter (optional):

(in order of decreasing preference)

Change all return values to match historical practice.

OR Change return values of tgetflag() and tgetnum() to match historical
practice, and make the return value of tgetent() implementation-defined.

OR Withdraw the functions.  (This would allow implementations to keep
their existing behaviour.  The implementations would then be standard
conforming and existing applications would keep on working.)

Resolution Response

For this revision of the specification conforming implementations may
either  provide the behavior as currently
specified by XCurses, Issue 4, Version 2 or the historical behavior
as described the "Nature of defect" section  above.

In a future revision since these functions are marked To Be Withdrawn,
they will be withdrawn.

This is an agreed problem:  The tgetent(), tgetflag(), and tgetnum() can
only behave as specified if the value of the termcap entry for name is OK,
the Boolean value of an id being looked up by tgetflag() matches the value
of OK, or the numeric value of an id being looked up by tgetnum() is OK.

Circulated for review: 27 May 2000
Proposed resolution: 27 May 2000