Previous section.

Networking Services (XNS) Issue 5
Copyright © 1997 The Open Group

Common Information

This chapter provides general information that applies to the XTI, Sockets and IP Address Resolution interfaces defined in this volume.

Terminology

The information in this section applies only to the Sockets and IP Address Resolution interfaces.

The following terms are used in this specification:

can

This describes a permissible optional feature or behaviour available to the user or application; all systems support such features or behaviour as mandatory requirements.

implementation-dependent

The value or behaviour is not consistent across all implementations. The provider of an implementation normally documents the requirements for correct program construction and correct data in the use of that value or behaviour. When the value or behaviour in the implementation is designed to be variable or customisable on each instantiation of the system, the provider of the implementation normally documents the nature and permissible ranges of this variation. Applications that are intended to be portable must not rely on implementation-dependent values or behaviour.

legacy

Certain features are legacy, which means that they are being retained for compatibility with older applications, but have limitations which make them inappropriate for developing portable applications. New applications should use alternative means of obtaining equivalent functionality. Legacy features are marked LEGACY.

may

With respect to implementations, the feature or behaviour is optional. Applications should not rely on the existence of the feature. To avoid ambiguity, the reverse sense of may is expressed as need not, instead of may not.

must

This describes a requirement on the application or user.

should

With respect to implementations, the feature is recommended, but it is not mandatory. Applications should not rely on the existence of the feature.

With respect to users or applications, the word means recommended programming practice that is necessary for maximum portability.

undefined

A value or behaviour is undefined if this document imposes no portability requirements on applications for erroneous program constructs or erroneous data. Implementations may specify the result of using that value or causing that behaviour, but such specifications are not guaranteed to be consistent across all implementations. An application using such behaviour is not fully portable to all systems.

unspecified

A value or behaviour is unspecified if this document imposes no portability requirements on applications for correct program construct or correct data. Implementations may specify the result of using that value or causing that behaviour, but such specifications are not guaranteed to be consistent across all implementations. An application requiring a specific behaviour, rather than tolerating any behaviour when using that functionality, is not fully portable to all systems.

will

This means that the behaviour described is a requirement on the implementation and applications can rely on its existence.

Use and Implementation of Interfaces

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.

For backward compatibility purposes, any of the function names within the header file may be redefined by the implementation, using the pre-processor "#define" mechanism (or any other similar compiler supported mechanism) to another function name. If redefined, the function name so defined will be in accordance with the name space rules in The Name Space .

As a result of changes in this issue of this document, 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 the XTI specification.

The Compilation Environment

Applications should ensure that the feature test macro _XOPEN_SOURCE is defined with the value 500 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 be undefined using the #undef directive as described in The Name Space . These #undef directives must follow all #include directives of any XSI headers.

Since this specification is aligned with the ISO C standard, and since all functionality enabled by _POSIX_C_SOURCE set greater than zero and less than or equal to 199506L should be enabled by _XOPEN_SOURCE set equal to 500, there should be no need to define either _POSIX_SOURCE or _POSIX_C_SOURCE if _XOPEN_SOURCE is defined. Therefore if _XOPEN_SOURCE is set equal to 500 and _POSIX_SOURCE is defined, or _POSIX_C_SOURCE is set greater than zero and less than or equal to 199506L, the behavior is the same as if only _XOPEN_SOURCE is defined and set equal to 500. However, should _POSIX_C_SOURCE be set to a value greater than 199506L, the behaviour is undefined.

The c89 and cc utilities recognise the additional -l operand for standard libraries:

-l xnet
If the implementation defines _XOPEN_UNIX, this operand makes visible all functions referenced in this document. An implementation may search this library in the absence of this operand.

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

If the implementation supports the utilities marked DEVELOPMENT in the XCU specification, the lint utility recognises the additional -l operand for standard libraries:

-l xnet
Names the library llib-lxnet.ln, which will contain functions specified in this document.

It is unspecified whether the library llib-lxnet.ln exists as a regular file.

The Name Space

All identifiers in this document are defined in at least one of the headers, as shown in Sockets Headers , IP Address Resolution Headers of XNS and Chapter 4 of XSH (see the referenced document XSH). 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.

If any header in the following table is included, identifiers with the following prefixes or suffixes shown are reserved for any use by the implementation.

Header Prefix Suffix
<arpa/inet.h> in_, inet_  
<netdb.h> h_, n_, p_, s_  
<netinet/in.h> in_, ip_, s_, sin_  
<sys/socket.h> sa_, if_, ifc_, ifru_, infu_, ifra_, msg_, cmsg_, l_  
<sys/un.h> sun_  
<xti.h> l_, t_, T_  
ANY header   _t

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
<netinet/in.h> IMPLINK_, IN_, INADDR_, IP_, IPPORT_, IPPROTO_, SOCK_
<sys/socket.h> AF_, CMSG_, MSG_, PF_, SCM_, SHUT_, SO
<xti.h> OPT_, T_1, XTI_

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 in the table below are reserved for use as identifiers with external linkage.

    XTI:
    t_accept
    t_alloc
    t_bind
    t_close
    t_connect
    t_errno
    t_error
    t_free     		 
    t_getinfo
    t_getprotaddr
    t_getstate
    t_listen
    t_look
    t_open
    t_optmgmt     		 
    t_rcv
    t_rcvconnect
    t_rcvdis
    t_rcvrel
    t_rcvreldata
    t_rcvudata
    t_rcvuderr     		 
    t_rcvv
    t_rcvvudata
    t_snd
    t_snd
    t_snddis
    t_sndrel
    t_sndreldata     		 
    t_sndudata
    t_sndv
    t_sndvudata
    t_strerror
    t_sync
    t_sysconf
    t_unbind
    Sockets:
    accept
    bind
    connect
    getpeername     		 
    getsockname
    getsockopt
    listen
    recv     		 
    recvfrom
    recvmsg
    send     		 
    sendmsg
    sendto
    setsockopt     		 
    shutdown
    socket
    socketpair
    IP Address Resolution:
    endhostent
    endnetent
    endprotoent
    endservent
    gethostbyaddr
    gethostbyname
    gethostent     		gethostname
    getnetbyaddr
    getnetbyname
    getnetent
    getprotobyname
    getprotobynumber
    getprotoent     		getservbyname
    getservbyport
    getservent
    h_errno
    htonl
    htons     		inet_addr
    inet_lnaof
    inet_makeaddr
    inet_netof
    inet_network
    inet_ntoa     		ntohl
    ntohs
    sethostent
    setnetent
    setprotoent
    setservent

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.

Relationship to the XSH Specification

Error Numbers

Some 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.

Thread Safety

All interfaces defined by this document will be thread-safe, except for the following interfaces which need not be thread-safe:


gethostbyaddr()
gethostbyname()
gethostent()
getnetbyaddr()
getnetbyname()
getnetent()
getprotobynumber()
getprotobyname()
getprotoent()
getservbyname()
getservbyport()
getservent()
inet_ntoa()

Thread Cancellation Points

Cancellation points will occur when a thread is executing any of the following functions:


accept()
connect()
recv()
recvfrom()
recvmsg()
send()
sendmsg()
sendto()


t_close()
t_connect()
t_listen()
t_rcv()
t_rcvconnect()
t_rcvrel()
t_rcvreldata()
t_rcvudata()
t_rcvv()
t_rcvvudata()
t_snd()
t_sndrel()
t_sndreldata()
t_sndudata()
t_sndv()
t_sndvudata()

A cancellation point may also occur when a thread is executing any of the following functions:


endhostent()
endnetent()
endprotoent()
endservent()
gethostbyaddr()
gethostbyname()
gethostent()
gethostname()
getnetbyaddr()
getnetbyname()
getnetent()
getprotobynumber()
getprotobyname()
getprotoent()
getservbyport()
getservbyname()
getservent()
sethostent()
setnetent()
setprotoent()
setservent()

An implementation will not introduce cancellation points into any other function specified in this document.

See the referenced XSH, Section 2.8 for further information.

Relationship to Emerging Formal Standards

The IEEE 1003.1g standards committee is also developing interfaces to XTI and Sockets. X/Open is actively involved in the work of this committee.

Footnotes

1.
The following T_ prefixes are currently used: T_INET_, T_IP_, T_ISO_, T_, T_TCL_, T_TCP_, T_TCO_, T_UDP_.

Why not acquire a nicely bound hard copy?
Click here to return to the publication details or order a copy of this publication.

Contents Next section Index