Corrigendum:    U037

Date:            5 February 1999

Document:    C523 Networking Services (XNS), Issue 5

Code:           02/99 C523/U037

Contents:    This corrigendum comprises two new items:
			U037/XNS-500
			U037/XNS-501
		    plus two items originally contained in Corrigendum U031:
			U031/XNS-001
			U031/XNS-002
		    This Corrigendum therefore supersedes U031.

Change Number:  U037/XNS-500

Title:                 Behaviour of various headers under different values of _XOPEN_SOURCE

Qualifier:        Major technical and editorial

Rationale:       The "Networking Services, Issue 5" as published has some significant editorial and
                        technical problems and ambiguities relating to the behaviour of various headers under
                        different values of _XOPEN_SOURCE:

1. Any text that relates to behaviour of the implementation when _XOPEN_SOURCE is less than 500 is informative, not normative. This behaviour is specified normatively in earlier issues of XNS.
2. Conformant systems are not required to provide the OPT_NEXTHDR macro.
3. Protocol-specific symbols defined in <xti_inet.h> or <xti_osi.h> are not required to be available when <xti.h> is included by the application but <xti_inet.h> or <xti_osi.h> (respectively) is not included by the application.
4. An implementation is only required to provide protocol-specific headers for those protocols that it supports.
5. An implementation need not make available symbols marked in XNS5 as "LEGACY".
6. Although identifiers marked as "LEGACY" are not specified as being reserved for any use by the implementation, implementations may make them available.

While these changes may mean that XNS5 applications will have to be changed if they are to remain portable, it is believed that few, if any, such applications have been written at the time of publication of this Corrigendum, and that these changes are necessary, so they should therefore be made now.

Changes:        

Changes relating to _XOPEN_SOURCE

(1.1) Appendix A (ISO Transport Protocol Information), section A.1 (General), page 215
    Replace paragraph
        "Applications written to ......inclusion of <xti.h>"
    with replacement text [R2] below.

(1.2) Appendix B (Internet Protocol Specific Information), section B.1 (General), page 229
    Replace paragraph
        "Applications written to ......inclusion of <xti.h>"
    with replacement text [R2] below.

(1.3) Appendix D (Use of XTI to Access NetBIOS), section D.1(Introduction), last paragraph,
    Replace lines
        "Application written to ......inclusion of <xti.h> on platforms where XTI interfaces use is
        supported for NetBIOS transports"
    with replacement text [R2] below.

(1.4) Appendix I (SNA Transport Provider), Section I.1 (Introduction),
    Replace paragraph
        "Applications written to .....inclusion of <xti.h> on platforms where XTI interface use is
        supported for SNA transports."
    with replacement text [R2] below.

(1.5) Appendix F (Headers and definitions for XTI), page 281, second paragraph
    Replace paragraph,
        "Applications written to .... providers for which this may be the case."
    with replacement text [R1] below.

Replacement text [R1] was formulated from existing text in Appendix F and Replacement text [R2]
from existing text in Appendices A,B,D,I
Changes in creating the replacement text from existing text are addition of prefix "Note", and use of
the word "may" instead of "will" (since compatibility support for "_XOPEN_SOURCE less than 500"
environments is optional and not required, it seems more appropriate to use the word "may").
In [R1] only, "these" was changed to "the", to correct the English syntax.

The notes in replacement texts [R1] and [R2] are designated as informative, not normative.

Replacement text [R1]

Note
Applications written to compilation environments earlier than those required by this issue of the specification (see section 1.3 on page 3) and defining _XOPEN_SOURCE to be less than 500 may have the data structures and constants of certain protocol specific headers automatically exposed by the inclusion of <xti.h> for compatibility. The individual protocol-specific appendices document the providers for which this may be the case.

Replacement text [R2]

Note
Applications written to compilation environments earlier than those required by this issue of the specification
(see section 1.3 on page 3) and defining _XOPEN_SOURCE to be less than 500, may have these data
structures and constants exposed through the inclusion of <xti.h>

Changes relating to LEGACY symbols

(2.1) Appendix A (ISO Transport Protocol Information)
(2.1.1) Section A.4 delete all symbol definitions marked with (LEGACY)
(2.1.2) Delete on page 227, all symbols with TCO_ and TCL_ prefix. (TCO_LTPDU through upto
    TCL_CHECKSUM on page 227 retaining all T_ prefix symbols.)
    [Note These are symbols which have a T_ prefixed versions specified but (LEGACY) was missed from
    being added as editorial/typographical error. ]
(2.1.3) Delete on page 225, the symbol T_LTPDUDFLT which has the legend "/* define obsolete
    in XPG4 */".
(2.1.4) Create a new section "A.5 Compatibility" which mentions those comatibility symbols which may
    be exposed:

A.5 Compatibility.

Certain symbols may be exposed to applications including <xti_osi.h> for compatibility with applications transitioning from older issues of this specification where their semantics are specified.
Exposing these symbols is allowed but not required. Symbols that may be exposed in this implementation-dependent manner are:

T_LTPDUDFLT, ISO_TP, TCO_THROUGHPUT, TCO_TRANSDEL,
TCO_RESERRORRATE, TCO_TRANSFFAILPROB, TCO_ESTFAILPROB, TCO_RELFAILPROB, TCO_ESTDELAY, TCO_RELDELAY, TCO_CONNRESIL,
TCO_PROTECTION, TCO_PRIORITY, TCO_EXPD, TCL_TRANSDEL,
TCL_RESERRORRATE, TCL_PROTECTION, TCL_PRIORITY, TCO_LTPDU,
TCO_ACKTIME, TCO_REASTIME, TCO_EXTFORM, TCO_FLOWCTRL,
TCO_CHECKSUM, TCO_NETEXP, TCO_NETRECPTCF, TCO_PREFCLASS,
TCO_ALTCLASS1, TCO_ALTCLASS2, TCO_ALTCLASS3, TCO_ALTCLASS4,
TCL_CHECKSUM

(2.2) Appendix B (Internet Protocol-specific Information)
(2.2.1) Section B.4 delete all symbol definitions marked with (LEGACY)
(2.2.2) Delete symbol T_GARBAGE on page 238.
(2.2.3) Create a new section "B.5 Compatibility" which mentions those compatibility symbols
    which may be exposed.

B.5 Compatibility.

Certain symbols may be exposed to applications including <xti_inet.h> for compatibility with applications transitioning from older issues of this specification where their semantics are specified. Exposing these symbols is allowed but not required. Symbols that may be exposed in this implementation-dependent manner are:

INET_TCP
TCP_NODELAY, TCP_MAXSEG, TCP_KEEPALIVE
T_GARBAGE
INET_UDP
INET_IP
IP_OPTIONS, IP_TOS, IP_TTL, IP_REUSEADDR, IP_DONTROUTE, IP_BROADCAST

(2.3) Appendix D (Use of XTI to Access NetBIOS)
(2.3.1) In appendix D, delete all symbol definitions marked with (LEGACY)
    These are in sections D.5 (page 269) and section D.8 (page 275)
(2.3.2) Create a new section "D.9 Compatibility" which mentions those compatibility symbols which may be
    exposed:

D.9 Compatibility.

Certain symbols may be exposed to applications including <xti_netbios.h> for compatibility with applications transitioning from older issues of this specification where their semantics are specified.
Exposing these symbols is allowed but not required.

Symbols that may be exposed in this implementation-dependent manner are

NB_UNIQUE, NB_GROUP, NB_LOCAL, NB_NAMELEN, NB_BCAST_NAME
NB_ABORT, NB_CLOSED, NB_NOANSWER, NB_OPREJ

(2.4) Appendix I (SNA Transport Provider)
(2.4.1) In appendix I, delete all symbol definitions marked with (LEGACY). These are in Section I.2.2
    (page 321), Section I.2.4, (page 325)
(2.4.2) Create a new section "I.4 Compatibility" which mentions those compatibility symbols which
    may be exposed:

I.4 Compatibility.

Certain symbols may be exposed to applications including <xti_sna.h> for compatibility with applications transitioning from older issues of this specification where their semantics are specified. Exposing these symbols is allowed but not required. Symbols that may be exposed in this implementation-dependent manner are:

SNA_MAX_NETID_LEN, SNA_MAX_LU_LEN, SNA_MAX_TPN_LEN
SNA_CONNECTION_SETUP_FAILURE, SNA_USER_DISCONNECT,
SNA_SYSTEM_DISCONNECT, SNA_TIMEOUT, SNA_CONNECTION_OUTAGE

Changes relating to OPT_NEXTHDR macro

(3.1) t_optmgmt() man page, page 85, delete the text:
    "Note that OPT_NEXTHDR is also available for backward compatibility."

(3.2) Appendix F (Headers and Definitions for XTI)
    Create a new section "Compatibility" and add it to the end of the appendix:

Compatibility

Certain symbols or macros may be exposed to applications including <xti.h> for compatibility with
applications transitioning from older issues of this specification where their semantics are specified. Exposing
these symbols or macros is allowed but not required. Symbols or macros that may be exposed in this
implementation-dependent manner are

OPT_NEXTHDR
T_ALIGN

All protocol specific symbols exposed through <xti_osi.h> as specified in Appendix A.

All protocol specific symbols exposed through <xti_inet.h> as specified in Appendix B.

Changes to Appendix F related to protocol-specific symbols

Appendix F (Headers and Definitions for XTI)

(4.1) Appendix F, page 281, delete paragraph:
    Certain items in this appendix are marked LEGACY...equivalent functionality

(4.2) Appendix F, page 288-293:
    Delete text including and following the comment on page 288
        "/* SPECIFIC ISO OPTION AND MANAGEMENT PARAMETERS */"
    through to page 293 SET_TOS macro definitions (end of printed appendix)

Change: Number:    U037/XNS-501

Title:                Various clarifications, including some header and macro definitions/examples

Qualifier:        Major editorial and technical

Rationale:       Various as listed below:

1. The name T_OPT_NXTHDR and T_OPT_NEXTHDR are both used (inconsistent spelling). Adopt T_OPT_NEXTHDR consistently.
2. Macro formal parameters are missing from t_optmgmt() man page specification
3. Clarify macro definition of T_OPT_NEXTHDR with respect to identifying last t_opthdr in option buffer. This definition is located in t_optmgmt() man page (currently uses spelling T_OPT_NXTHDR).
4. Alignment interactions for option buffers can affect portability and need clarifications and can be interpreted ambiguously.
5. Clarify that implementing compatibility by padding "struct t_opthdr" is allowed.
6. Provide example macro definition examples with clear articulation of assumptions about implementation environment. Current printed macros have errors and are inconsistent with prototypes in the specification.

Changes:

(1) Change all instances of T_OPT_NXTHDR to T_OPT_NEXTHDR in the specification.

(1.1) Section 6.2, page 40, 3rd paragraph, change T_OPT_NXTHDR to T_OPT_NEXTHDR

(1.2) t_optmgmt() man page, pages 84-85, change (two) instances of T_OPT_NXTHDR to
    T_OPT_NEXTHDR

(2) On t_optmgmt() man page, add macro formal parameters and clarify identification of
    "last t_opthdr" in option buffer.

(2.1) On page 85, macro definitions, add macro formal parameters consistent with section 6.2
    on page 40.
    The change here for T_OPT_NXTHDR overlaps with the case (1) change.
    Thus "T_OPT_DATA" would become "T_OPT_DATA(tohp)"
    "T_OPT_NXTHDR" becomes "T_OPT_NEXTHDR(nbp,tohp)", and
    "T_OPT_FIRSTHDR" becomes "T_OPT_FIRSTHDR(nbp)"

(2.2) On page 85, t_optmgmt() page, add to description of T_OPT_NEXTHDR macro definition
    (name spelling fixed from T_OPT_NXTHDR), add after the text
        "....or a null pointer if this t_opthdr is the last t_opthdr in the the option buffer."
    the words:
        "In this case, the space remaining in the option buffer is none or too small to accommodate
        a t_opthdr."

(3) Clarify alignment interactions for 'struct netbuf' option buffers and related portability issues.

(3.1) Section 7.4 "Use of struct netbuf", page 53, after the "void *buf", add the following paragraph:
        " For guaranteed portability, the space pointed to by buf should be aligned appropriate
        to the most restrictive alignment of any of the data types it contains."

(3.2) Page 58, t_alloc() definition, add to the second paragraph the text:
        "The pointer references to space allocations embedded in struct netbuf fields (pointed by
        the buf pointers) are also aligned in the same way.

(3.3) Appendix F, page 285, change comment:
        /* followed by option value */
    to
        /* implementation may add padding here */

(4) Provide example definitions of option macros consistent with the specification and
taking into account changes (1) and (2) above.

(4.1) In Appendix F, page 287, replace current content starting from (and including) the T_ALIGN
    definition up to (and including) the T_OPT_FIRSTHDR definition. The new content is as follows:

/*
* The following T_OPT_FIRSTHDR, T_OPT_NEXTHDR and T_OPT_DATA
* macros have the semantics required by the standard. They are used to store and
* retrieve multiple variable length objects delimited by a 'header' descriptor and
* the variable length value content while allowing aligned access to each in an
* arbitrary memory buffer.
*
* The required minimum alignment (based on types used internally in the
* specification for header and data alignment is "sizeof (t_uscalar_t)"
*
* The definitions shown for macro bodies are examples only and other forms
* are not only possible but are specifically permitted.
*
* The examples shown assume that the implementation chooses to align the
* header and data parts at the required minimum of "sizeof (t_uscalar_t)
* Stricter alignment is permitted by an implementation.
*
* Helper macros starting with "_T" prefix are used below.
* These are not a requirement of the specification and only used for
* constructing example macro body definitions.
*/

/*
* Helper macro
* _T_USCALAR_ALIGN - macro aligns to "sizeof (t_uscalar_t) boundary
*/

#define _T_USCALAR_ALIGN(p) (((uintptr_t)(p) + (sizeof (t_scalar_t) - 1))\
& ~(sizeof (t_scalar_t)-1))

/*
* struct t_opthdr *T_OPT_FIRSTHDR(struct netbuf *nbp)
* Get aligned start of first option header
*
* This implementation assumes option buffers are allocated by t_alloc().
* Hence appropriate alignment to start any sized object (including option
* header) is guaranteed.
*/

#define T_OPT_FIRSTHDR(nbp) \
((((char *)(nbp)->buf + sizeof (struct t_opthdr)) <= \
(char *)(nbp)->buf + (nbp)->len) ? \
(struct t_opthdr *)(nbp)->buf (struct t_opthdr *)0)

/*
* unsigned char *T_OPT_DATA(struct t_opthdr *tohp)
* Get aligned start of data part after option header
*
* This implementation assumes "sizeof (t_uscalar_t)" as the alignment size
* for its option data and option header with no padding in "struct t_opthdr"
* definition.
*/

#define T_OPT_DATA(tohp) \
((unsigned char *)(tohp) + sizeof (struct t_opthdr))

/*
* struct t_opthdr *_T_NEXTHDR(char *pbuf, unsigned int buflen,
* struct t_opthdr *popt)
*
* Helper macro for defining T_OPT_NEXTHDR macro.
* This implementation assumes "sizeof (t_uscalar_t)" as the alignment
* for its option data and option header. Also it assumes "struct t_opthdr"
* definitions contains no padding.
*/

#define _T_NEXTHDR(pbuf, buflen, popt) \
(((char *)(popt) + _T_USCALAR_ALIGN((popt)->len) + \
sizeof (struct t_opthdr) <= \
((char *)(pbuf) + (buflen))) ? \
(struct t_opthdr *)((char *)(popt) + _T_USCALAR_ALIGN((popt)->len) \
(struct t_opthdr *)0))

/*
* struct t_opthdr *T_OPT_NEXTHDR(struct netbuf *nbp, struct t_opthdr *tohp)
* Skip to next option header
* This implementation assumes "sizeof (t_uscalar_t)" as the alignment size
* for its option data and option header.
*/

#define T_OPT_NEXTHDR(nbp, tohp) _T_NEXTHDR((nbp)->buf, (nbp)->len, (tohp))

Corrigendum U031 (12 Feb 1998)

Change Number:  U031/XNS-001

Title:		Incorrect specification of "type" for getnetbyaddr()

Qualifier:	Major technical

Rationale:	The description in the endnetent() reference page (Page 190) of the "net" argument 
			of getnetbyaddr() being of type "in_addr_t" is an erratum. It should be of 
			type "uint32_t", as in the getnetbyaddr() reference page (Page 196) and on 
			Page 212. [Page numbers refer to The Open Group's printed XNS Issue 5 publication.]

Change:		Change the endnetent() reference page from:
				struct netent *getnetbyaddr(in_addr_t net, int type);
			to:
				struct netent *getnetbyaddr(uint32_t net, int type);

Change Number:  U031/XNS-002

Title:		Typographical error

Qualifier:	Minor editorial

Rationale:	In the list of thread-safe interfaces in Section 1.5,  Thread Safety, the first item in the list
			is incompletely shown.

Change:		Change the first item in the list of thread-safe interfaces shown in Section 1.5, Thread 
			Safety from:
				byaddr()
			to:
				gethostbyaddr()