ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/_xopen_source.htm

525 lines
14 KiB
HTML
Raw Normal View History

2024-04-02 14:02:31 +00:00
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
<title>Using _XOPEN_SOURCE for UNIX 98 Compatibility</title>
<!-- Begin Header Records -->
<!-- All rights reserved. Licensed Materials Property of IBM -->
<!-- US Government Users Restricted Rights -->
<!-- Use, duplication or disclosure restricted by -->
<!-- GSA ADP Schedule Contract with IBM Corp. -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<a name="Top_Of_Page"></a>
<!--Java sync-link-->
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
</script>
<h2>Using _XOPEN_SOURCE for UNIX 98 Compatibility</h2>
<p>There are two versions of most sockets APIs. The base i5/OS<SUP>(TM)</SUP> API uses BSD
4.3 structures and syntax. The other uses syntax and structures compatible with
BSD 4.4 and the UNIX 98 programming interface specifications. You can select
the UNIX 98 compatible interface by defining the <strong>_XOPEN_SOURCE</strong>
macro to a value of 520 or greater.</p>
<p>When you develop in C-based languages and an application is compiled with
the _XOPEN_SOURCE macro defined to the value 520 or greater, some sockets APIs
are mapped to internal names, as shown in the following table:</p>
<table border cellpadding="2" cellspacing="2" width="50%">
<tr align="center">
<th valign="middle" align="center">Mapped name</th>
<th valign="middle" align="center">Internal name</th>
</tr>
<tr align="center">
<td valign="middle" align="center">accept()</td>
<td valign="middle" align="center">qso_accept98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">accept_and_recv()</td>
<td valign="middle" align="center">qso_accept_and_recv98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">bind()</td>
<td valign="middle" align="center">qso_bind98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">connect()</td>
<td valign="middle" align="center">qso_connect98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">endhostent()</td>
<td valign="middle" align="center">qso_endhostent98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">endnetent()</td>
<td valign="middle" align="center">qso_endnetent98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">endprotoent()</td>
<td valign="middle" align="center">qso_endprotoent98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">endservent()</td>
<td valign="middle" align="center">qso_endservent98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">getaddrinfo()</td>
<td valign="middle" align="center">qso_getaddrinfo98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">gethostbyaddr()</td>
<td valign="middle" align="center">qso_gethostbyaddr98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">gethostbyaddr_r()</td>
<td valign="middle" align="center">qso_gethostbyaddr_r98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">gethostname()</td>
<td valign="middle" align="center">qso_gethostname98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">gethostname_r()</td>
<td valign="middle" align="center">qso_gethostname_r98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">gethostbyname()</td>
<td valign="middle" align="center">qso_gethostbyname98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">gethostent()</td>
<td valign="middle" align="center">qso_gethostent98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">getnameinfo()</td>
<td valign="middle" align="center">qso_getnameinfo98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">getnetbyaddr()</td>
<td valign="middle" align="center">qso_getnetbyaddr98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">getnetbyname()</td>
<td valign="middle" align="center">qso_getnetbyname98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">getnetent()</td>
<td valign="middle" align="center">qso_getnetent98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">getpeername()</td>
<td valign="middle" align="center">qso_getpeername98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">getprotobyname()</td>
<td valign="middle" align="center">qso_getprotobyname98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">getprotobynumber()</td>
<td valign="middle" align="center">qso_getprotobynumber98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">getprotoent()</td>
<td valign="middle" align="center">qso_getprotoent98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">getsockname()</td>
<td valign="middle" align="center">qso_getsockname98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">getsockopt()</td>
<td valign="middle" align="center">qso_getsockopt98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">getservbyname()</td>
<td valign="middle" align="center">qso_getservbyname98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">getservbyport()</td>
<td valign="middle" align="center">qso_getservbyport98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">getservent()</td>
<td valign="middle" align="center">qso_getservent98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">inet_addr()</td>
<td valign="middle" align="center">qso_inet_addr98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">inet_lnaof()</td>
<td valign="middle" align="center">qso_inet_lnaof98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">inet_makeaddr()</td>
<td valign="middle" align="center">qso_inet_makeaddr98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">inet_netof()</td>
<td valign="middle" align="center">qso_inet_netof98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">inet_network()</td>
<td valign="middle" align="center">qso_inet_network98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">listen()</td>
<td valign="middle" align="center">qso_listen98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">Rbind()</td>
<td valign="middle" align="center">qso_Rbind98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">recv()</td>
<td valign="middle" align="center">qso_recv98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">recvfrom98()</td>
<td valign="middle" align="center">qso_recvfrom98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">recvmsg()</td>
<td valign="middle" align="center">qso_recvmsg98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">send()</td>
<td valign="middle" align="center">qso_send98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">sendmsg()</td>
<td valign="middle" align="center">qso_sendmsg98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">sendto()</td>
<td valign="middle" align="center">qso_sendto98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">sethostent()</td>
<td valign="middle" align="center">qso_sethostent98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">setnetent()</td>
<td valign="middle" align="center">qso_setnetent98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">setprotoent()</td>
<td valign="middle" align="center">qso_setprotoent98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">setservent()</td>
<td valign="middle" align="center">qso_setprotoent98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">setsockopt()</td>
<td valign="middle" align="center">qso_setsockopt98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">shutdown()</td>
<td valign="middle" align="center">qso_shutdown98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">socket()</td>
<td valign="middle" align="center">qso_socket98()</td>
</tr>
<tr align="center">
<td valign="middle" align="center">socketpair()</td>
<td valign="middle" align="center">qso_socketpair98()</td>
</tr>
</table>
<p>Application not using C-based languages can use the internal names if
necessary.</p>
<p>Using <strong>_XOPEN_SOURCE</strong> also changes some of the structures
used by sockets to match BSD 4.4/UNIX 98 standards. The differences are
summarized in the following table:</p>
<table border cellpadding="2" cellspacing="2" width="80%">
<tr align="center">
<th valign="middle" align="center"><strong>BSD 4.3 structure</strong></th>
<th valign="middle" align="center"><strong>BSD 4.4/UNIX 98 compatible structure</strong></th>
</tr>
<tr align="center">
<td valign="middle" align="left">
<pre>
typedef int socklen_t;
<strong>typedef unsigned short sa_family_t;</strong>
struct sockaddr {
u_short sa_family;
char sa_data[14];
};
struct sockaddr_un {
short sun_family;
char sun_path[126];
};
struct sockaddr_in {
short sin_family;
u_short sin_port;
struct in_addr sin_addr;
char sin_zero[8];
};
struct sockaddr_in6 {
sa_family_t sin6_family;
in_port_t sin6_port;
uint32_t sin6_flowinfo;
struct in6_addr sin6_addr;
uint32_t sin6_scope_id;
};
</pre>
</td>
<td valign="middle" align="left">
<pre>
typedef int socklen_t;
<strong>typedef uchar sa_family_t;</strong>
struct sockaddr {
<strong>uint8_t sa_len;</strong>
<strong>sa_family_t</strong> sa_family;
char sa_data[14];
};
struct sockaddr_un {
<strong> uint8_t sun_len;
sa_family_t</strong> sun_family;
char sun_path[126];
};
struct sockaddr_in {
<strong> uint8_t sin_len;
sa_family_t</strong> sin_family;
u_short sin_port;
struct in_addr sin_addr;
char sin_zero[8];
};
struct sockaddr_in6 {
<strong> uint8_t sin6_len; </strong>
sa_family_t sin6_family;
in_port_t sin6_port;
uint32_t sin6_flowinfo;
struct in6_addr sin6_addr;
uint32_t sin6_scope_id;
};
</pre>
</td>
</tr>
<tr align="center">
<td valign="middle" align="left">
<pre>
struct msghdr {
caddr_t msg_name;
int msg_namelen;
struct iovec *msg_iov;
int msg_iovlen;
caddr_t msg_accrights;
int msg_accrightslen;
};
</pre>
</td>
<td valign="middle" align="left">
<pre>
struct msghdr {
<strong>void</strong> *msg_name;
<strong>socklen_t</strong> msg_namelen;
struct iovec *msg_iov;
int msg_iovlen;
<strong>void *msg_control;
socklen_t msg_controllen;
int msg_flags;</strong>
};
</pre>
</td>
</tr>
<tr align="center">
<td valign="middle" align="left">
<pre>
(no equivalent)
</pre>
</td>
<td valign="middle" align="left">
<pre>
<strong>struct cmsghdr {
socklen_t cmsg_len;
int cmsg_level;
int cmsg_type;
};</strong>
</pre>
</td>
</tr>
<tr align="center">
<td valign="middle" align="left">
<pre>
#define _SS_MAXSIZE 304
#define _SS_ALIGNSIZE (sizeof (char*))
#define _SS_PAD1SIZE (_SS_ALIGNSIZE -
sizeof(sa_family_t))
#define _SS_PAD2SIZE (_SS_MAXSIZE -
(sizeof(sa_family_t) +
_SS_PAD1SIZE +
_SS_ALIGNSIZE))
struct sockaddr_storage {
sa_family_t ss_family;
char _ss_pad1[_SS_PAD1SIZE];
char* _ss_align;
char _ss_pad2[_SS_PAD2SIZE];
};
</pre>
</td>
<td valign="middle" align="left">
<pre>
#define _SS_MAXSIZE 304
#define _SS_ALIGNSIZE (sizeof (char*))
#define _SS_PAD1SIZE (_SS_ALIGNSIZE - (<strong>sizeof(uint8_t) +
</strong> sizeof(sa_family_t)))
#define _SS_PAD2SIZE (_SS_MAXSIZE - (<strong>sizeof(uint8_t) +
</strong> sizeof(sa_family_t) +
_SS_PAD1SIZE + _SS_ALIGNSIZE))
struct sockaddr_storage {
<strong> uint8_t ss_len;
</strong>
sa_family_t ss_family;
char _ss_pad1[_SS_PAD1SIZE];
char* _ss_align;
char _ss_pad2[_SS_PAD2SIZE];
};
</pre>
</td>
</tr>
<tr align="center">
<td valign="middle" align="left">
<pre>
(no equivalent)
</pre>
</td>
<td valign="middle" align="left">
<pre>
<strong>typedef int in_addr_t;
typedef unsigned short in_port_t;
</strong>
</pre>
</td>
</tr>
</table>
<h3>Usage Notes</h3>
<ol>
<li>The <strong>struct sockaddr</strong> length field (<strong>sa_len</strong>
and the address family specific equivalents: <strong>sun_len</strong>,
<strong>sin_len</strong>, and <strong>sin6_len</strong>) is only provided for
BSD 4.4 compatibility. It is not necessary to use this field even when using
BSD 4.4/UNIX 98 compatibility. The field is ignored on input addresses (like
the local_address parameter on bind()) and will be properly set on output
addresses (like the address parameter on accept()).<br><br></li>
<li>
The AF_UNIX_CCSID address <strong>sockaddr_unc</strong> has not been updated with
a length field equivalent to <strong>sa_len</strong>. If you use
<strong>sa_len</strong> to set a length on this address, it will be ignored
on input addresses and set to zero on output addresses.<br><br></li>
<li>The structure <strong>sockaddr_storage</strong> is used to declare storage
for any address family address. This structure is large enough and aligned for
any protocol-specific structure. It may then be cast as
<strong>sockaddr</strong> structure for use on the APIs. The
<strong>ss_family</strong> field of the <strong>sockaddr_storage</strong> will
always align with the family field of any protocol-specific structure.<br>
<br>
<strong>Note:</strong> The storage allocated is larger than 255 bytes so it's
size should not be used for <strong>sa_len</strong>. The actual
protocol-specific structure size should be used instead.</li>
</ol>
<hr>
<table cellpadding="2" cellspacing="2" align="center">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> |
<a href="unix.htm">UNIX-Type APIs</a> |
<a href="aplist.htm">APIs by category</a> </td>
</tr>
</table>
</body>
</html>