Previous section.
Networking Services (XNS) Issue 5
Copyright © 1997 The Open Group
XTI Library Functions and Parameters
The function synopses in this Chapter 6, and the function definitions in
Headers and Definitions for XTI
,
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
Headers and Definitions for XTI
.
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
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).
Why not acquire a nicely bound hard copy?
Click here to return to the publication details or order a copy
of this publication.