Previous section.

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

Common Information

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

Terminology

The information in this section applies only to the Sockets and IP Address Resolution interfaces, which are defined in Part 2.

The following terms are used in this document:

can

Describes a permissible optional feature or behavior available to the user or application. The feature or behavior is mandatory for an implementation that conforms to this document. An application can rely on the existence of the feature or behavior.

implementation-dependent

(Same meaning as implementation-defined.) Describes a value or behavior that is not defined by this document but is selected by an implementor. The value or behavior may vary among implementations that conform to this document. An application should not rely on the existence of the value or behavior. An application that relies on such a value or behavior cannot be assured to be portable across conforming implementations.

The implementor shall document such a value or behavior so that it can be used correctly by an application.

legacy

Describes a feature or behavior that is being retained for compatibility with older applications, but which has limitations which make it inappropriate for developing portable applications. New applications should use alternative means of obtaining equivalent functionality.

may

Describes a feature or behavior that is optional for an implementation that conforms to this document. An application should not rely on the existence of the feature or behavior. An application that relies on such a feature or behavior cannot be assured to be portable across conforming implementations.

To avoid ambiguity, the opposite of may is expressed as need not, instead of may not.

must

Describes a feature or behavior that is mandatory for an application or user. An implementation that conforms to this document shall support this feature or behavior.

shall

Describes a feature or behavior that is mandatory for an implementation that conforms to this document. An application can rely on the existence of the feature or behavior.

should

For an implementation that conforms to this document, describes a feature or behavior that is recommended but not mandatory. An application should not rely on the existence of the feature or behavior. An application that relies on such a feature or behavior cannot be assured to be portable across conforming implementations.

For an application, describes a feature or behavior that is recommended programming practice for optimum portability.

undefined

Describes the nature of a value or behavior not defined by this document which results from use of an invalid program construct or invalid data input.

The value or behavior may vary among implementations that conform to this document. An application should not rely on the existence or validity of the value or behavior. An application that relies on any particular value or behavior cannot be assured to be portable across conforming implementations.

unspecified

Describes the nature of a value or behavior not specified by this document which results from use of a valid program construct or valid data input.

The value or behavior may vary among implementations that conform to this document. An application should not rely on the existence or validity of the value or behavior. An application that relies on any particular value or behavior cannot be assured to be portable across conforming implementations.

will

Same meaning as shall; shall is the preferred term.

Use and Implementation of Interfaces

Each of the following statements applies unless explicitly stated otherwise in the ensuing descriptions. 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 520 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 headers defined in the referenced XCU specification.

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 greater than or 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 greater than or 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 greater than or 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 defined in the referenced XCU specification 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_  
<net/if.h> if_  
<netinet/in.h> in_, ip_, s_, sin_  
<sys/socket.h> _ss, sa_, if_, ifc_, ifru_, infu_, ifra_, msg_, cmsg_, l_  
<sys/un.h> sun_  
ANY header   _t

When the optional XTI is supported, identifiers with the following prefixes are reserved for any use by the implementation:

Header Prefix
<xti.h> l_, t_, 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
<net/if.h> IF_
<netinet/in.h> IMPLINK_, IN_, INADDR_, IP_, IPPORT_, IPPROTO_, SOCK_
<netinet/tcp.h> TCP_
<sys/socket.h> AF_, CMSG_, MSG_, PF_, SCM_, SHUT_, SO

When the optional XTI is supported, identifiers with the following prefixes are reserved for any use by the implementation:

Header Prefix
<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.

    Sockets:
    accept
    bind
    connect
    getpeername
    getsockname
    getsockopt
    if_freenameindex
    if_indextoname
    if_nameindex
    if_nametoindex
    listen
    recv
    recvfrom
    recvmsg
    send
    sendmsg
    sendto
    setsockopt
    shutdown
    socket
    socketpair
    IP Address Resolution:
    endhostent
    endnetent
    endprotoent
    endservent
    getaddrinfo
    gethostbyaddr
    gethostbyname
    gethostent
    gethostname
    getipnodebyaddr
    getipnodebyname
    getnameinfo
    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

    XTI - the following symbols are only reserved when optional XTI is supported:
    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

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

Contents Next section Index