TCP32DLL.LIB

TCP32DLL.LIB is one of two import libraries required to build 32-bit TCP/IP network applications for OS/2. It is distributed with IBM TCP/IP for OS/2 and the IBM OS/2 Developer's Toolkit. TCP32DLL.LIB provides the name resolution, resolver, and utility API stubs. The companion library SO32DLL.LIB provides the BSD socket API (accept, bind, connect, recv, send, etc.). Both libraries are needed for a complete TCP/IP application.

The libraries contain no executable code. They are OMF import libraries: each record maps an exported function name (or ordinal) to a symbol in the supplying DLL. A TCP/IP application links both alongside OS2386.LIB.

Library	DLL	Size (Toolkit 4.5)	Contents
TCP32DLL.LIB	TCP32DLL.DLL	15,872 bytes	Name resolution, inet_, resolver (res_), byte-swap utilities, remote exec, time
SO32DLL.LIB	SO32DLL.DLL	9,728 bytes	BSD socket API: socket, accept, bind, connect, listen, recv, send, select, …

Calling Convention Variants

Both libraries export every function under two names to support the two C calling conventions in use on OS/2:

Variant	Example	Calling convention	Compiler
Lowercase / mixed-case	`gethostbyname`	`_System` (OS/2 default)	IBM C Set++, VisualAge C++, OpenWatcom
Uppercase `MSC` suffix	`GETHOSTBYNAMEMSC`	`__cdecl` (Microsoft C default)	EMX/GCC, Borland C, Microsoft C
Underscore-prefixed `MSC` suffix	`_gethostbynameMSC`	`__cdecl`	Same as above (alternate form)

The TCP/IP header files (netdb.h, utils.h, tcpustubs.h) select the correct variant automatically based on the __cdecl or _System compiler setting. Application developers should not reference the MSC or ordinal forms directly.

TCP32DLL.LIB — Name Resolution and Utilities

Host lookups

These functions follow the BSD 4.3 netdb.h interface. Each returns a pointer to a static hostent structure. For multithreaded applications use the reentrant _r variants (see #Reentrant functions below).

gethostbyname(name): Returns a hostent for the given hostname. Queries the local hosts file and/or DNS in order. Returns NULL on failure; consult h_errno for the error code.

gethostbyaddr(addr, len, type): Reverse lookup — maps an IP address to a hostname.

gethostent() / sethostent(stayopen) / endhostent(): Sequential scan of the local hosts file. sethostent(1) keeps the file open between calls.

gethostname(name, namelen): Retrieves the local hostname as configured in TCP/IP.

Network lookups

getnetbyname(name) / getnetbyaddr(net, type): Looks up a network entry by name or address from /etc/networks.

getnetent() / setnetent(stayopen) / endnetent(): Sequential scan of the networks file.

Protocol lookups

getprotobyname(name) / getprotobynumber(proto): Looks up a protocol entry from /etc/protocol.

getprotoent() / setprotoent(stayopen) / endprotoent(): Sequential scan of the protocol file.

Service lookups

getservbyname(name, proto): Returns the servent for the given service name and protocol (e.g. "http", "tcp").

getservbyport(port, proto): Reverse lookup — maps a port number to a service name.

getservent() / setservent(stayopen) / endservent(): Sequential scan of /etc/services.

Address conversion

These are pure in-process utilities; they perform no network I/O.

inet_addr(cp): Converts a dotted-decimal string (e.g. "192.168.1.1") to a 32-bit network-byte-order address. Returns INADDR_NONE (0xFFFFFFFF) on error.

inet_ntoa(in): Converts a 32-bit address to a dotted-decimal string. Returns a pointer to a static buffer; not thread-safe.

inet_makeaddr(net, lna): Constructs an in_addr from a network number and local address.

inet_netof(in): Extracts the network number from an address.

inet_lnaof(in): Extracts the local part (host number) from an address.

inet_network(cp): Converts a network address string to host byte order.

DNS Resolver

The resolver functions send queries directly to the DNS server specified in resolv.crt (or resolv.conf). They are used by gethostbyname internally and can also be called directly by applications that need raw DNS access.

res_init(): Reads the resolver configuration file and initializes the global _res structure. Called automatically the first time any resolver function is used; applications may call it explicitly to force a configuration reload.

res_query(dname, class, type, answer, anslen): Sends a DNS query for dname (e.g. a PTR or MX lookup) and fills answer with the raw DNS response.

res_querydomain(name, domain, class, type, answer, anslen): Like res_query but appends domain to name before querying. Used to implement domain search-path logic.

res_search(dname, class, type, answer, anslen): Applies the search list from resolv.crt and calls res_querydomain for each domain until a match is found.

res_mkquery(op, dname, class, type, data, datalen, newrr, buf, buflen): Encodes a DNS query into a wire-format buffer without sending it. Used when building DNS packets by hand or testing.

res_send(msg, msglen, answer, anslen): Sends a pre-built DNS query buffer to the configured name server and returns the response. Low-level companion to res_mkquery.

DNS packet utilities

Used when parsing raw DNS response packets (e.g. after a res_query call):

dn_expand(msg, eomorig, comp_dn, exp_dn, length): Decompresses a DNS domain name from a response packet into a printable string.

dn_comp(exp_dn, comp_dn, length, dnptrs, lastdnptr): Compresses a domain name for use in a DNS query packet.

dn_find(exp_dn, msg, dnptrs, lastdnptr): Searches the compression table for an existing entry matching the given name.

dn_skipname(comp_dn, eom): Advances a pointer past a compressed domain name field in a packet without expanding it.

Error handling

h_errno: Thread-unsafe global holding the last name resolution error code. Values: HOST_NOT_FOUND, TRY_AGAIN, NO_RECOVERY, NO_DATA / NO_ADDRESS. Defined in netdb.h.

tcp_h_errno_ / TCP_H_ERRNO: The exported symbol that backs h_errno in TCP32DLL.DLL. Applications should access it only through the h_errno macro in netdb.h.

Byte-swap utilities

These are in-process utilities for converting between host byte order and network byte order. On OS/2 (little-endian x86), the conversion swaps the bytes; on a big-endian host they compile to nothing.

htons(x) / ntohs(x): 16-bit host-to-network and network-to-host conversion. Typically implemented as macros in utils.h; the library also exports _getshort / _putshort / LSWAP as underlying helpers.

htonl(x) / ntohl(x): 32-bit host-to-network and network-to-host conversion. Backed by _getlong / _putlong / BSWAP.

Reentrant functions

These thread-safe variants take an extra caller-supplied buffer and avoid the static storage used by the standard calls. Required for multithreaded servers.

gethostbyname_r(name, result, buffer, buflen, herrno): Thread-safe gethostbyname. Fills result (a caller-supplied hostent) and ancillary strings into buffer.

gethostbyaddr_r(addr, len, type, result, buffer, buflen, herrno): Thread-safe gethostbyaddr.

getservbyname_r(name, proto, result, buffer, buflen): Thread-safe getservbyname.

In addition, TCP32DLL.LIB exports capitalized R-prefixed variants (Rgethostbyname, Raccept, Rbind, Rconnect, Rlisten, Rgetsockname) which are the OS/2 IBM-convention reentrant wrappers. Application code should use the _r forms declared in netdb.h.

Remote execution

rexec(ahost, inport, user, passwd, cmd, fd2p): Connects to the rexecd daemon on a remote host, authenticates with a plaintext password, and executes a shell command. Returns a socket descriptor for the command's stdout/stdin. Deprecated in modern environments; use SSH instead.

Time

gettimeofday(tp, tzp): BSD-compatible time call. Returns the current time as a timeval (seconds + microseconds since epoch). OS/2 does not support the timezone parameter (tzp should be NULL).

settimeofday(tp, tzp): Sets the system clock. Requires elevated privileges.

SO32DLL.LIB — BSD Socket API

The core socket functions are in the companion library SO32DLL.LIB (SO32DLL.DLL). These are the standard BSD 4.3 socket calls:

Socket lifecycle

socket(domain, type, protocol): Creates a new socket. domain is AF_INET (IPv4); type is SOCK_STREAM (TCP) or SOCK_DGRAM (UDP). Returns a socket descriptor or −1.

soclose(s): Closes a socket and releases all resources. On OS/2, use soclose() rather than the standard C close(); sockets are not file descriptors.

shutdown(s, how): Partially or fully closes a connected socket (how: 0 = no more recv, 1 = no more send, 2 = both).

soabort(s): Aborts a socket connection with a TCP RST, without the graceful four-way close. Used to discard a hung connection immediately.

so_cancel(s): Cancels a pending blocking socket operation on the given descriptor (for multithreaded applications).

sock_init(): Initializes the TCP/IP socket library. Must be called once per process before any other socket function. (On OS/2, unlike UNIX, this call is required.)

Server-side

bind(s, name, namelen): Associates a socket with a local address and port.

listen(s, backlog): Marks a socket as passive (server) and sets the maximum pending connection queue length.

accept(s, addr, addrlen): Blocks until an incoming connection arrives, then returns a new socket for that connection. The original socket remains open for further accept calls.

Client-side

connect(s, name, namelen): Initiates a connection to a remote address (TCP) or sets the default destination (UDP).

Addressing

getsockname(s, name, namelen): Returns the local address and port assigned to a socket.

getpeername(s, name, namelen): Returns the remote address of a connected socket.

Sending and receiving

send(s, buf, len, flags) / recv(s, buf, len, flags): Send and receive data on a connected socket. flags may include MSG_PEEK, MSG_OOB, MSG_DONTWAIT.

sendto(s, buf, len, flags, to, tolen) / recvfrom(s, buf, len, flags, from, fromlen): Datagram variants that specify the destination/source address on each call (UDP).

sendmsg(s, msg, flags) / recvmsg(s, msg, flags): Scatter/gather send and receive using msghdr structures.

readv(s, iov, iovcnt) / writev(s, iov, iovcnt): BSD scatter/gather I/O using iovec arrays.

Socket options

getsockopt(s, level, optname, optval, optlen) / setsockopt(s, level, optname, optval, optlen): Query and set socket options. Common options: SO_REUSEADDR, SO_KEEPALIVE, SO_LINGER, SO_RCVBUF, SO_SNDBUF, TCP_NODELAY (disables Nagle algorithm).

Multiplexed I/O

select(nfds, readfds, writefds, exceptfds, timeout): Monitors up to FD_SETSIZE sockets for readability, writability, or error. OS/2 socket descriptors are not file descriptors and cannot be mixed with file handles in the same select call.

bsdselect(nfds, readfds, writefds, exceptfds, timeout): BSD-compatible variant of select; same semantics.

Control

ioctl(s, cmd, arg): Socket-level I/O control: set non-blocking mode (FIONBIO), query bytes available (FIONREAD), set/get async I/O (FIOASYNC).

Error handling

sock_errno(): Returns the last socket error code for the calling thread. Analogous to errno but thread-safe. Error codes are defined in nerrno.h (e.g. SOCENOTSOCK, SOCEWOULDBLOCK, SOCECONNREFUSED).

psock_errno(msg): Prints a socket error message to stderr in the style of perror().

Miscellaneous

gethostid(): Returns the primary IP address of the local host as a 32-bit integer.

getinetversion(buf): Returns the IBM TCP/IP version string.

addsockettolist(s) / removesocketfromlist(s) / getsocketfromlist(index): Internal socket list management, used by the IBM TCP/IP implementation. Not normally called by applications.

Usage

A TCP/IP application must link both TCP32DLL.LIB and SO32DLL.LIB in addition to OS2386.LIB:

IBM VisualAge C++ / ILINK

icc -O2 -Gm -c myapp.c
ilink /PM:VIO myapp.obj os2386.lib tcp32dll.lib so32dll.lib

OpenWatcom (wlink)

wcl386 -bt=os2 -mf -c myapp.c
wlink system os2v2 file myapp.obj library os2386.lib library tcp32dll.lib library so32dll.lib

EMX/GCC

gcc -Zomf -c myapp.c
gcc -Zomf -o myapp.exe myapp.o os2386.lib tcp32dll.lib so32dll.lib

Note: EMX/GCC uses __cdecl by default. The TCP/IP headers select the MSC ordinal variants automatically when compiled under GCC. No additional -D flag is needed if the IBM TCP/IP headers are included normally.

Include files

The primary headers (from the IBM TCP/IP SDK include\ directory, typically C:\MPTN\INCLUDE\ or the Toolkit h\ directory):

Header	Contents
`types.h`	BSD type aliases (`u_char`, `u_short`, `u_long`, `u_int`)
`sys\socket.h`	`sockaddr`, `sockaddr_in`, socket constants, `AF_`, `SOCK_`, `SOL_`, `SO_`
`netinet\in.h`	`in_addr`, `IPPROTO_*`, `INADDR_ANY`, `INADDR_NONE`
`arpa\inet.h`	`inet_addr`, `inet_ntoa` prototypes
`netdb.h`	`hostent`, `servent`, `protoent`, `netent`, lookup function prototypes, `h_errno`
`resolv.h`	`_res` state structure, `res_` and `dn_` prototypes
`utils.h`	`htons`, `htonl`, `ntohs`, `ntohl` macros; `sock_errno`, `psock_errno`
`nerrno.h`	Socket error codes: `SOCEWOULDBLOCK`, `SOCENOTSOCK`, `SOCECONNREFUSED`, etc.
`sys\ioctl.h`	`FIONBIO`, `FIONREAD`, `FIOASYNC`

Minimal TCP client example

#include <stdio.h>
#include <string.h>
#include <types.h>
#include <sys\socket.h>
#include <netinet\in.h>
#include <netdb.h>
#include <utils.h>
#include <nerrno.h>

int main(void)
{
    struct hostent *hp;
    struct sockaddr_in addr;
    int s;
    char buf[256];

    sock_init();   /* Required on OS/2 */

    hp = gethostbyname("www.example.com");
    if (!hp) { psock_errno("gethostbyname"); return 1; }

    memset(&addr, 0, sizeof(addr));
    addr.sin_family      = AF_INET;
    addr.sin_port        = htons(80);
    addr.sin_addr.s_addr = *(u_long *)hp->h_addr;

    s = socket(AF_INET, SOCK_STREAM, 0);
    if (s < 0) { psock_errno("socket"); return 1; }

    if (connect(s, (struct sockaddr *)&addr, sizeof(addr)) < 0) {
        psock_errno("connect"); soclose(s); return 1;
    }

    send(s, "GET / HTTP/1.0\r\n\r\n", 18, 0);
    recv(s, buf, sizeof(buf)-1, 0);
    soclose(s);
    return 0;
}

Version History

Version	IBM TCP/IP release	Date	Notes
1.0	IBM TCP/IP for OS/2 1.0	~1991	Initial 16-bit release. Socket API provided by separate 16-bit libraries.
2.0	IBM TCP/IP for OS/2 2.0	~1993	First 32-bit release. TCP32DLL.DLL and SO32DLL.DLL split established. BSD 4.3 socket interface.
3.0	IBM TCP/IP for OS/2 3.0 (Warp 3 integrated)	1994	Integrated into OS/2 Warp 3. Added reentrant `_r` variants, `bsdselect`.
4.1	IBM TCP/IP for OS/2 4.1 (Warp 4)	1996	Added `getservbyname_r`, `gethostbyname_r`, `gethostbyaddr_r` thread-safe forms. `sock_errno()` made per-thread.
4.21 / 4.3	IBM TCP/IP for OS/2 4.21 / OS/2 Warp 4.52	2000–2001	Final IBM release. File sizes: TCP32DLL.LIB 15,872 bytes, SO32DLL.LIB 9,728 bytes (both dated 2000-10-16).

Relationship to Other Libraries

Library	Purpose
SO32DLL.LIB	The socket half: `socket`, `accept`, `connect`, `send`, `recv`, `select`, etc. Always link alongside TCP32DLL.LIB.
OS2386.LIB	Core 32-bit OS/2 CP and PM APIs. Required for all OS/2 32-bit applications.
PMWSOCK.LIB	PM-integrated socket helper for asynchronous socket notifications via PM messages (`WinAsyncSelect` equivalent). For GUI TCP/IP apps only.

Calling Convention Variants

TCP32DLL.LIB — Name Resolution and Utilities

Host lookups

Network lookups

Protocol lookups

Service lookups

Address conversion

DNS Resolver

DNS packet utilities

Error handling

Byte-swap utilities

Reentrant functions

Remote execution

Time

SO32DLL.LIB — BSD Socket API

Socket lifecycle

Server-side

Client-side

Addressing

Sending and receiving

Socket options

Multiplexed I/O

Control

Error handling

Miscellaneous

Usage

IBM VisualAge C++ / ILINK

OpenWatcom (wlink)

EMX/GCC

Include files

Minimal TCP client example

Version History

Relationship to Other Libraries

See Also