Previous section.

Technical Standard: Networking Services (XNS), Issue 5.2 Draft 2.0
Copyright © 1999 The Open Group

XTI Library Functions and Parameters

The function synopses in this Chapter 6, and the function definitions in Example XTI Header Files, conform to ISO C standard (see referenced documents).

How to Prepare XTI Applications

In a software development environment, a program, for example file.c, that uses XTI functions must be compiled with the XTI Library.

An application may also have a requirement to define some feature test macro(s) as described in The Compilation Environment (The Compilation Environment) to enable the functionality described in this specification.

The generic XTI structures and constants are all defined in the <xti.h> header, which can be found in Example XTI Header Files.

Any protocol-specific header files described in Appendices of this specification and needed by the application must follow the inclusion of <xti.h>.

Note:
When _XOPEN_SOURCE is defined to be less than 500, the definitions from some protocol specific headers are automatically exposed by the inclusion of <xti.h>. The individual appendices for those protocols document the headers for which this applies.

Key for Parameter Arrays

For each XTI function description, a table is given which summarises the contents of the input and output parameter. The key is given below:

x
The parameter value is meaningful. (Input parameter must be set before the call and output parameter may be read after the call.)

(x)
The content of the object pointed to by the x pointer is meaningful.

?
The parameter value is meaningful but the parameter is optional.

(?)
The content of the object pointed to by the ? pointer is optional.

/
The parameter value is meaningless.

=
The parameter after the call keeps the same value as before the call.

Return of TLOOK Error

Many of the XTI functions contained in this chapter return a [TLOOK] error to report the occurrence of an asynchronous event. For these functions a complete list describing the function and the events is provided in Events and TLOOK Error Indication.

Use of "struct netbuf"

Many of the XTI functions have an argument that points to a structure with members of type struct netbuf. These are used to pass arbitrary length buffer items such as user data, network addresses and option buffers to and from the XTI interfaces.

struct netbuf contains the following members:


unsigned int maxlen unsigned int len void *buf

For guaranteed portability, the space pointed to by buf should be aligned appropriately to the most restrictive alignment of any of the data types it contains.

When a buffer item is being passed to the provider, buf and len are the address and length in bytes of the data in the user's buffer. maxlen is not used and may take any value.

When a buffer item is being passed to the user, prior to the call the user must set buf and maxlen to the address and length of the user's buffer. On return the provider will set len to the number of bytes of data placed into the user's buffer. If the user's buffer has a non-zero maxlen but is not long enough for the buffer item, then the provider will fail the XTI call, setting t_errno to TBUFOVFLW and discarding the event being returned to the user. If maxlen is zero then the provider will discard the data that would have been returned, and ignore len and buf (which need not have been a valid address).

Contents Next section Index