This appendix describes the TCPware for OpenVMS Socket Library.
Note! This appendix is for use with versions of VMS earlier than 5.3. For later versions, use the VAX C or DEC C socket libraries described in Chapter 8, Socket Library.
The Socket Library is a collection of VAX C (on VAX machines) and DEC C (on Alpha and I64 machines) subroutines that closely emulates the UNIX socket functions. The Socket Library supports a subset of these functions, including stream and datagram sockets.
ALPHA and I64 When using DEC C, be sure to use the /stand=vaxc compiler option.
TCPware provides these subroutines so that UNIX C programs, which use the UNIX socket functions, can easily be migrated to the TCPware environment. Programs written in VAX C, DEC C, or other high level languages can call the Socket Library.
TCPware does not support all features of the UNIX socket functions. It provides only limited asynchronous support. Most differences are primarily due to the differences between the UNIX and OpenVMS operating systems.
When developing new applications, consider using a QIO programming interface. This interface is not difficult to use and provides full capabilities for event-driven programming.
For more information on the direct QIO programming interfaces, see Chapter 6, INETDRIVER Services, Chapter 3, TCPDRIVER Services, Chapter 4, UDPDRIVER Services, or Chapter 5, IPDRIVER Services.
The Socket Library and related VAX C header files are located in the TCPWARE_INCLUDE: directory.
The following VAX C header files are provided with the Socket Library:
|
IF.H |
Defines the interface data structures used with the socket_ioctl routine to obtain information about network interfaces. |
|
IF_ARP.H |
Defines the ARP (Address Resolution Protocol) data structures used with the socket_ioctl routine to set and get ARP entries. |
|
IN.H |
Defines the internet address structure (in_addr) and socket address structure (sockaddr_in). This file is required for almost all socket operations. |
|
INET.H |
Defines the inet subroutines. Use this file when you need to call them. |
ALPHA and I64 Use the INET.H file when calling the TCPware inet subroutines. If you do not, the program uses HP subroutines instead. See Subroutines Redefined in Header Files for Use on Alpha and I64 Systems for a list of subroutines that are redefined in this file.
|
IOCTL.H |
Defines the socket_ioctl subroutine. |
|
NAMESER.H |
Defines the constant needed for using the resolver routines for Domain Name Services (DNS) lookups. |
|
NETDB.H |
Defines the network database structures; in particular, the hostent, protoent, and servent structures. It also declares the subroutines. This file is required if using the gethostbyname, gethostbyaddr, getprotobyname, getprotobynumber, getservbyname, and getservbyport subroutines. |
ALPHA and I64 Use the NETDB.H file when calling the TCPware subroutines above. If you do not, the program uses HP subroutines instead. See Subroutines Redefined in Header Files for Use on Alpha and I64 Systems for a list of subroutines that are redefined in this file.
|
RESOLV.H |
Defines the options provided for the resolver routines for DNS lookups. |
|
ROUTE.H |
Defines the routing data structures used with the socket_ioctl routine to set and get routing table entries. |
|
SOCKERR.H |
Defines the socket error codes (these are usually defined in ERRNO.H). This file is required for all socket operations if you want to test for specific error status codes. |
|
SOCKET.H |
Defines the sockaddr structure and the SOCK_STREAM, SOCK_DGRAM, AF_INET, and various other symbols used when calling the Socket Library subroutines. This file is required for all socket operations. |
ALPHA and I64 Use the SOCKET.H file when calling the TCPware subroutines. If you do not, the program uses HP subroutines instead. See Subroutines Redefined in Header Files for Use on Alpha and I64 Systems for a list of subroutines that are redefined in this file.
|
SOCKETVAR.H |
Defines the socket structure used by the socket subroutines themselves. It is only needed if you want to get access to this internal structure for special purposes (such as reading the channel number). It is not recommended that you use the SOCKETVAR.H header file as it may be removed in a future TCPware release. Use the getsockopt subroutine, with SO_IOCHAN as optname, if you need the OpenVMS I/O channel a socket uses. |
|
TYPES.H |
Defines many UNIX C data type names. It is useful when adapting UNIX C programs to work under VAX C. The TYPES.H file also defines macros used in manipulating the socket descriptor sets used with select, such as FD_SET, FD_CLR, FD_ISSET, FD_ZERO, FD_SET, and FD_SETSIZE. |
ALPHA and I64 Use the TYPES.H file when calling certain TCPware subroutines. If you do not, the program uses HP subroutines instead. See Subroutines Redefined in Header Files for Use on Alpha and I64 Systems for a list of subroutines that are redefined in this file.
The INET.H, NETDB.H, SOCKET.H, and TYPES.H header files are included with TCPware. These header files contain the subroutine and function name re-definitions in Table A-1.
|
Table A-1 Subroutines Redefined in Header Files for Use on Alpha and I64 Systems |
|
|
This Subroutine/Function... |
Is Redefined As... |
|
File: SOCKET.H |
|
|
accept |
tcpware_accept |
|
bind |
tcpware_bind |
|
connect |
tcpware_connect |
|
getpeername |
tcpware_getpeername |
|
getsockname |
tcpware_getsockname |
|
getsockopt |
tcpware_getsockopt |
|
listen |
tcpware_listen |
|
recvfrom |
tcpware_recvfrom |
|
select |
tcpware_select |
|
sendto |
tcpware_sendto |
|
setsockopt |
tcpware_setsockopt |
|
socket |
tcpware_socket |
|
socket_close |
tcpware_socket_close |
|
socket_ioctl |
tcpware_socket_ioctl |
|
socket_read |
tcpware_socket_read |
|
socket_recv |
tcpware_socket_recv |
|
socket_send |
tcpware_socket_send |
|
socket_write |
tcpware_socket_write |
|
shutdown |
tcpware_shutdown |
|
getdomainname |
tcpware_getdomainname |
|
setdomainname |
tcpware_setdomainname |
|
gethostid |
tcpware_gethostid |
|
gethostaddr |
tcpware_gethostaddr |
|
gethostname |
tcpware_gethostname |
|
sethostname |
tcpware_sethostname |
|
pneterror |
tcpware_pneterror |
|
File: TYPES.H |
|
|
htonl |
tcpware_htonl |
|
htons |
tcpware_htons |
|
ntohl |
tcpware_ntohl |
|
ntohs |
tcpware_ntohs |
|
File: INET.H |
|
|
inet_addr |
tcpware_inet_addr |
|
inet_aton |
tcpware_inet_aton |
|
inet_lnaof |
tcpware_inet_lnaof |
|
inet_makeaddr |
tcpware_inet_makeaddr |
|
inet_ntoa |
tcpware_inet_ntoa |
|
inet_netof |
tcpware_inet_netof |
|
inet_network |
tcpware_inet_network |
|
File: NETDB.H |
|
|
gethostbyname |
tcpware_gethostbyname |
|
gethostbyaddr |
tcpware_gethostbyaddr |
|
getnetent |
tcpware_getnetent |
|
getnetbyaddr |
tcpware_getnetbyaddr |
|
getnetbyname |
tcpware_getnetbyname |
|
getprotobyname |
tcpware_getprotobyname |
|
getprotobynumber |
tcpware_getprotobynumber |
|
getprotoent |
tcpware_getprotoent |
|
getservbyname |
tcpware_getservbyname |
|
getservbyport |
tcpware_getservbyport |
To use the Socket Library from your applications, you must link to the Socket Library shareable image and the VAX C Run-Time Library (RTL). On Alpha and I64 systems, HP supplied RTLs link in automatically.
VAX For example, the following command on the VAX links a program called TEST with the Socket Library shareable image and the VAX C RTL:
$ LINK TEST,SYS$INPUT/OPTIONS
SYS$SHARE:TCPWARE_SOCKLIB_SHR/SHARE
SYS$SHARE:VAXCTRL/SHARE
Ctrl/Z
Although it is recommended that you use TCPWARE_SOCKLIB_SHR.EXE or TCPWARE_SOCKLIBG_SHR.EXE, you can link with TCPWARE:SOCKLIB.OLB instead.
The following command links the TEST program with SOCKLIB.OLB and the VAX C RTL:
$ LINK
TEST,TCPWARE:SOCKLIB/LIB,SYS$INPUT/OPTIONS
SYS$SHARE:VAXCRTL/SHARE
Ctrl/Z
For details on linking C programs, see the VAX C documentation.
ALPHA and I64 The command is:
$ LINK TEST,SYS$INPUT/OPTIONS
SYS$LIBRARY:TCPWARE_SOCKLIB_SHR/SHARE
Ctrl/Z
Although it is recommended that you use TCPWARE_SOCKLIB_SHR.EXE, TCPWARE_SOCKLIBD_SHR.EXE, or TCPWARE_SOCKLIBT_SHR.EXE, you can link with TCPWARE:SOCKLIB.OLB instead.
The following command links the TEST program with SOCKLIB.OLB and the DEC C RTL:
$ LINK TEST,TCPWARE:SOCKLIB/LIB
On Alpha and I64 systems, HP supplied RTL's link in automatically.
For details on linking C programs, see the HP C documentation.
Table A-2 lists the sample Socket Library based client and server programs TCPware provides in the SYS$COMMON:[TCPWARE.EXAMPLES]:.
|
Program |
Purpose |
|
DAYTIMED.C |
Server for the DAYTIME protocol |
|
DISCARD.C |
Client for the DISCARD protocol |
|
DISCARDD.C |
Server for the DISCARD protocol |
|
FINGER.C |
Client for the FINGER protocol |
|
FINGERD.C |
Server for the FINGER protocol |
|
WHOIS.C |
Client for the NAME protocol |
This section lists the subroutines provided in the Socket Library. These subroutines are divided into the following categories:
|
Socket operations |
Lookup operations |
|
Byte-order conversion operations |
Byte string operations |
|
Internet address conversion |
Server operation |
See the Socket Library Reference section for details on each one of the subroutines and functions associated with these categories.
The Socket Library contains the following socket operations:
|
accept |
pneterror |
socket_read |
|
bind |
select |
socket_recv |
|
connect |
setsockopt |
recvfrom |
|
getpeername |
shutdown |
socket_send |
|
getsockname |
socket |
socket_write |
|
getsockopt |
socket_close |
sendto |
|
listen |
socket_ioctl |
tcpware_server |
The Socket Library contains the following lookup operations:
|
getdomainname |
getnetbyaddr |
HNS_LOOKUPHOST |
|
gethostname |
getnetbyname |
HNS_LOOKUPIA |
|
gethostbyaddr |
getprotobyname |
resolver |
|
gethostbyname |
getprotobynumber |
setdomainname |
|
gethostid |
getservbyname/ getservbyport |
sethostname |
The Socket Library contains the following byte order conversion functions, defined in the TYPES.H and IN.H header files:
|
htonl |
htons |
ntohl |
ntohs |
The Socket Library contains the following byte string operations:
|
bcopy |
bcmp |
bzero |
The Socket Library contains the following internet address conversion subroutines:
|
inet_addr |
inet_makeaddr |
inet_network |
inet_aton |
|
inet_lnaof |
inet_netof |
inet_ntoa |
|
The Socket Library contains one server operation subroutine called tcpware_server.
TheSample Discard Protocol Programs section shows how to use tcpware_server.
The following sections contain information about the data structures included in various socket library subroutines. These structures include:
|
hostent |
protoent |
sockaddr_in |
netent |
servent |
The hostent structure represents the internet-host-name-to-address mappings in the subroutines gethostbyaddr and gethostbyname. The structure is defined as follows in the NETDB.H header file in the TCPWARE_INCLUDE: directory:
struct hostent {
char *h_name; /* official host name */
char **h_aliases; /* alias list */
int h_addrtype; /* host address type */
int h_length; /* address length */
char **h_addr_list; /* list of addresses (name server) */
#define h_addr haddr_list[0]; /* address (backward compatibility) */
};
The h_addr_list list of addresses is null-terminated and is required because some hosts can have many addresses, each having the same name. The h_addr definition provides backward compatibility and is the first address (in network byte order) in the list of addresses in the hostent structure.
The netent structure represents the network name/number mappings used with the subroutines getnetbyname and getnetbyaddr. The structure is defined as follows in the NETDB.H header file in the TCPWARE_INCLUDE: directory:
struct netent {
char *n_name; /* official name of net */
char **n_aliases; /* alias list */
int n_addrtype; /* net address type */
unsigned long n_net; /* network #, host byte order */
};
The protoent structure represents the protocol-name mappings used with the subroutines getprotobyname and getprotobynumber. The structure is defined as follows in the NETDB.H header file in the TCPWARE_INCLUDE: directory:
struct protoent {
char *p_name; /* official protocol name */
char **p_aliases; /* alias list */
int p_proto; /* protocol number */
};
The servent structure represents the service mappings used with the subroutines getservbyname and getservbynumber. The structure is defined as follows in the NETDB.H header file in the TCPWARE_INCLUDE: directory:
struct servent {
char *s_name; /* official service name */
char **s_aliases; /* alias list */
int s_port; /* port number, network byte order */
char *s_proto; /* protocol to use */
};
The sockaddr_in structure represents the socket address used with the subroutines bind, connect, getpeername, getsockname, getservbyname and getservbynumber. The structure is defined as follows in the IN.H header file in the TCPWARE_INCLUDE: directory:
struct sockaddr_in {
short sin_family; /* address family */
unsigned short sin_port; /* port number */
struct in_addr sin_addr; /* address */
char sin_zero[8];
};
struct in_addr {
unsigned long s_addr;
};
You can use most WIN/TCP applications with TCPware. You can do so if you use the existing WIN/TCP socket library and invoke the SETUP_TWG.COM command procedure provided with TCPware. This command procedure defines some logicals and sets up some files to emulate the Wollongong environment so that the WIN/TCP socket library can operate.
Using WIN/TCP applications with TCPware assumes that the applications were:
• Built with the Wollongong header files.
• Linked against the TWGLIB.OLB socket library or TWG_RTL.EXE run-time library.
Note that the Run-Time Library must be present on your system in SYS$SHARE if the application is linked against it.
When you install TCPware for OpenVMS, one of the files provided is the TCPWARE:SETUP_TWG.COM file. TCPware does not invoke this command procedure. Edit your system startup file to invoke this procedure.
If you use applications developed for Wollongong's WIN/TCP (or Pathways) under TCPware for OpenVMS, observe the following:
1 Start TCPware if it is not running.
2 Invoke the SETUP_TWG.COM procedure, for example, @TCPWARE:SETUP_TWG
This command procedure uses the definitions of several TCPware logicals.
3 Edit your system startup file to include the following line after TCPware is started if you want the command procedure to be permanent: $ @TCPWARE:SETUP_TWG
The SETUP_TWG.COM procedure:
• Defines the logical needed to use the WIN/TCP socket library under TCPware:
ARPANET_HOST_NAME
INET_DOMAIN_NAME
INET_NAMESERVER_LIST
TWG$TCP
• Creates the TWG$TCP:[NETDIST.ETC] directory it does not already exist.
• Copies the following TCPware files to the TWG$TCP:[NETDIST.ETC] directory:
HOSTS.
NETWORKS.
PROTOCOLS.
SERVICES.
Applications written for the WIN/TCP socket library that you recompile and then link with the TCPware Socket Library (object or RTL) will probably not work without modification. The WIN/TCP and TCPware socket libraries have differences, such as:
• TCPware uses TCPDRIVER and UDPDRIVER, not INETDRIVER. This means that any mix of SYS$QIO[W] calls with socket library calls will not work.
• The TCPware socket number is not the VMS I/O channel; it is the address of an internal data structure.
• Not all routines in the WIN/TCP library are available in the TCPware socket library. Also, not all routines in the TCPware socket library are available in the WIN/TCP library.
• Some routines use different names.
Fortunately, modifying the applications written for the WIN/TCP socket library so that they can link against TCPware's socket library usually does not require a lot of work. It can typically be done using conditional compilations.
This section describes each Socket Library subroutine and function in detail.
Waits for and accepts the next listening connection. Usually used by servers. Valid only for stream TCP sockets.
snew = accept(s, name, namelen)
int snew
Accepted connection's socket descriptor, or -1 for failure.
int s
Socket descriptor (as returned by socket). The listen subroutine must have been called on this socket.
struct sockaddr_in *name
Address of the sockaddr_in structure to receive peer's internet address and port number. (See the sockaddr_in subsection for the sockaddr_in structure definition.)
int *namelen
Address of the length of the sockaddr_in structure (passed to and returned by accept).
Allocates a new socket structure and performs a passive open on the socket with the port number from the listen socket.
Call the listen subroutine before calling accept.
Calls to the socket and bind subroutines are made to create the new socket.
IO$_SETMODE | IO$M_CTRL | IO$M_STARTUP | 0x0800 issued on the channel for the socket to wait for the next passive connection on the port.
listen
select
Returns -1 for failure. For a failure status, the errno variable contains the reason for the error as follows:
|
EADDRINUSE |
Port number is already in use. |
|
EBADF |
Socket structure is not valid. |
|
ECONNRESET |
Peer resets the connection. |
|
EINVAL |
namelen value is not valid or listen has not been called on socket s. |
|
EIO |
Unexpected system status returned during operation. |
|
EOPNOTSUPP |
Not a stream socket. |
|
ENETDOWN |
Network was shut down. |
|
ETIMEDOUT |
Connection timed-out. |
|
EWOULDBLOCK |
Socket was set to non-blocking mode and the operation would block. |
Also, accept may return any status that the socket and bind subroutines return.
The vaxc$errno variable contains the system service or I/O status code for EADDRINUSE, ECONNRESET, EIO, ENETDOWN, or ETIMEDOUT.
Compares two buffers to determine if they are identical.
status = bcmp(b1, b2, length)
char *b1, *b2
Address of the first and second strings.
int length
Number of bytes to compare.
Provides a byte string operation that compares two buffers of a specified length, returning zero if they are identical and non-zero if they are not. The function does not check for null bytes.
• Returns 0 if the byte strings are identical or if the length is zero
• Returns non-zero if the byte strings are not identical
Copies a specified number of bytes from one buffer to another.
(void) bcopy(b1, b2, length)
char *b1, *b2
Address of the source and destination strings. The two strings can overlap.
int length
Number of bytes to be copied.
Provides a byte string operation that copies a specified number of bytes from one buffer to another. Does not check for null bytes. Overlapping strings are handled correctly.
Binds the local internet address information to the socket.
status = bind(s, name, namelen)
int s
Socket descriptor (as returned by socket).
struct sockaddr_in *name
Address of the sockaddr_in structure containing the local internet address and local port number. (See the sockaddr_in subsection for the sockaddr_in structure definition.)
int namelen
Length of the sockaddr_in structure.
Binds the local address information to the socket. You must specify the local internet address (or INADDR_ANY[=0]) and local port number (or 0).
• IO$_SETMODE | IO$M_CTRL for a stream (TCP) socket
• IO$_SETMODE | IO$M_CTRL | IO$M_STARTUP for a datagram (UDP) socket
Returns 0 for success or -1 for failure. For a failure status, the errno variable contains the reason for the error as follows. The vaxc$errno variable is valid for EADDRINUSE, EADDRNOTAVAIL, EIO, or ENETDOWN.
|
EACCES |
Insufficient privilege. |
|
EADDRINUSE |
Port number is already in use. |
|
EADDRNOTAVAIL |
Local internet address is invalid. |
|
EBADF |
Socket structure is not valid. |
|
EINVAL |
Name structure is invalid, its length is wrong, or the socket is already in use. |
|
EIO |
Unexpected system status returned during operation. |
|
ENETDOWN |
Network was shut down. |
Places a specified length of zero bytes into a buffer.
(void) bzero(b, length)
char *b
Address of the string.
int length
Number of bytes to be zeroed.
Provides a byte string operation that places a specified length of zero bytes into a buffer.
Initiates an active connection to a server. It is usually used by the client-end of applications.
status = connect(s, server, serverlen)
int s
Socket descriptor (as returned by socket).
struct sockaddr_in *server
Address of the sockaddr_in structure containing the peer's internet address and port number. (See the sockaddr_in subsection for the sockaddr_in structure definition.)
int serverlen
Length of the sockaddr_in structure.
This subroutine opens an active connection for a stream (TCP) socket. For a datagram (UDP) socket, the port is configured as fully specified (meaning that only datagrams from the specified peer can be received). For a raw (IP) socket, the destination internet address is set.
A bind call is optional before a connect call.
• IO$_SENSEMODE | IO$M_CTRL|IO$M_STARTUP for a stream (TCP) socket
• IO$_SENSEMODE | IO$M_CTRL for a datagram (UDP) socket
The connect subroutine returns 0 for success or -1 for failure. For a failure status, the errno variable contains the reason for the error as follows:
|
EADDRINUSE |
Port number is already in use. |
|
EAFNOSUPPORT |
Address family specified in the server structure is not AF_INET. |
|
EBADF |
Socket structure is not valid. |
|
ECONNREFUSED |
Connection was refused by the peer. |
|
EINVAL |
Server structure is invalid, its length is wrong, or the socket is al ready in use. |
|
EIO |
Unexpected system status returned during operation. |
|
ENETDOWN |
Network was shut down. |
|
ENETUNREACH |
There is no routing information to reach the peer. |
|
ETIMEDOUT |
Connection timed out. |
The vaxc$errno variable is valid for EADDRINUSE, ECONNREFUSED, EIO, ENETDOWN, ENETUNREACH, or ETIMEDOUT.
Gets the local host's domain name or hostname.
len = getdomainname(name, namelen)
len = gethostname(name, namelen)
int len
Length of the domain name string (or 0 if none available).
char *name
Address of an ASCII (null-terminated) string in which to return the domain name, or that contains the domain name.
int namelen
Maximum length of character string name (passed to the subroutines).
The user process getdomainname or gethostname subroutine reads the system logical name TCPWARE_DOMAINNAME.
setdomainname
sethostname
• If no name is available, returns 0
• Otherwise, returns the length of the domain name string
Returns the host name or alias for an internet address.
he = gethostbyaddr(addr, len, type)
struct hostent *he
Address of the returned hostent structure, or 0 (NULL) if no match is found. (See the hostent subsection for the hostent structure definition.)
The returned structure is in a static area, so you must copy it to save it.
char *addr
Address of the host's four-byte internet address, in network byte order.
int len
Length of an internet address (must be 4).
int type
Address type (must be AF_INET = 2). AF_INET is defined in SOCKET.H.
Uses the DNS Name Server or cached-in-memory version of your local Hosts database to locate the host name or alias of the given internet address. A process reloads the Hosts database into memory every 10 minutes by default if modifications exist. The database is in the TCPWARE:HOSTS. file.
See the gethostbyname subroutine for more details on the Hosts database.
gethostbyname
Returns the internet address for a named host or alias.
he = gethostbyname(name)
struct hostent *he
Address of the returned hostent structure, or 0 (NULL) if no match is found. (See the hostent subsection for the hostent structure definition.)
The returned structure is in a static area, so you must copy it to save it.
char *name
Address of an ASCII (null-terminated) string containing the name or alias of the host. The string is not case-sensitive.
Uses the DNS Name Server or cached version of your local Hosts database to locate the internet address of the host name or alias entry. A process reloads the Hosts database into memory every 10 minutes by default if modifications exist. The database is in the TCPWARE:HOSTS. file.
The TCPWARE_SVCORDER logical name contains the list of services used in the order specified. The valid values for the logical are:
|
local |
Uses the HOSTS. file. |
|
bind |
Uses DNS (provided the TCPWARE_NAMESERVERS and TCPWARE_DOMAINNAME logicals are properly defined). |
You can also use the values "bind,local" (the default if the logical is not defined) and "local,bind" (which uses DNS if the Hosts database lookup fails).
If you do not use DNS and want to read from the HOSTS. files, edit it in the proper format. Each entry must be address hostname [aliases], where address is the host internet address, hostname the official host name, and aliases a list of alias names separated by spaces. Comments can appear prefixed by a #. If you want to read the HOSTS. file, use the sethostent, gethostent, and endhostent subroutines:
|
sethostent(int stayopen) |
opens (or rewinds) the database; if the stayopen value is non-zero, the database remains open |
|
struct hostent *gethostent() |
returns the next entry's hostent structure address, or zero if all entries were read |
|
endhostent() |
closes the database (unless stayopen is non-zero) |
gethostbyname returns every entry satisfying the search criteria. Therefore, avoid equating a host with a standard alias, defining a hostname by an existing alias, and equating more than one host with the same alias.
Returns the local host's internet address.
hostid = gethostid()
int hostid
Returned internet address for the local host in byte reversed order. (Returns -1 if no address is available.)
Returns one of the local internet addresses for a network interface.
gethostname
sethostname
Returns the netent structure for a network number.
ne = getnetbyaddr(net, type)
struct netent *ne
Address of the returned netent structure, or 0 (NULL) if no match is found. (See the netent subsection for the netent structure definition.)
The returned structure is in a static area, so you must copy it to save it.
long net
Network number, in host byte order (such as the value returned by inet_network).
int type
Address type (must be AF_INET = 2). AF_INET is defined in SOCKET.H.
Uses the cached-in-memory version of your local Networks database to locate the entry for the given network address. A process reloads the Networks database into memory every 10 minutes by default if modifications exist. The database is in the TCPWARE:NETWORKS. file.
See thegetnetbyname subroutine for more details on the Networks database.
getnetbyname
Returns the netent structure for a named network.
ne = getnetbyname(name)
struct netent *ne
Address of the returned netent structure, or 0 (NULL) if no match is found. (See the netent subsection for the netent structure definition.)
The returned structure is in a static area, so you must copy it to save it.
char *name
Address of an ASCII (null-terminated) string containing the name or alias of the network. The network name string is case-sensitive.
Uses the cached-in-memory version of your local Networks database to locate the entry for the given network name or alias. A process reloads the Networks database into memory every 10 minutes by default if modifications exist. The database is in the TCPWARE:NETWORKS. file.
If you want to read from the NETWORKS. files, edit it in the proper format. Each entry must be name number [aliases], where name is the official name for the network, number the network number, and aliases a list of alias names separated by spaces. Comments can appear in the file prefixed by a #. If you want to read the NETWORKS. file, use the setnetent, getnetent, and endnetent subroutines:
|
setnetent |
opens (or rewinds) the database; if the stayopen value is non-zero, the database remains open |
|
struct netent *getnetent |
returns the next entry's netent structure address, or zero if all entries were read |
|
endnetent() |
closes the database (unless stayopen is non-zero) |
Returns the peer's internet address and port number for a socket.
status= getpeername(s, name, namelen)
int s
Socket descriptor (as returned by socket). (See the sockaddr_in subsection for the sockaddr_in structure definition.)
struct sockaddr_in *name
Address of the sockaddr_in structure in which to return the peer's internet address and port number.
int *namelen
Address of the length of the sockaddr_in structure (passed to and returned by getpeername).
Returns the peer's internet address and port number stored in the socket structure. Note that this information is set by connect and accept.
Returns 0 for success and -1 for failure. For a failure status, the errno variable contains the reason for the error as follows:
|
EBADF |
Socket structure is not valid. |
|
EINVAL |
namelen value is incorrect. It must be sizeof(struct sockaddr_in). |
|
ENOTCONN |
Socket is not connected. |
Returns the protocol number for a named protocol or alias.
pe = getprotobyname(name)
struct protoent *pe
Address of the returned protoent structure, or 0 (NULL) if no match is found. (See the protoent subsection for the protoent structure definition.) The returned structure is in a static area, so you must copy it to save it.
char *name
Address of an ASCII (null-terminated) string containing the protocol name (such as TCP or UDP) or alias. The string is not case-sensitive.
Scans the TCPWARE:PROTOCOLS. file and returns the entry for the given protocol name or alias. A process checks the file for modifications by default every 10 minutes and then reloads it into memory if modifications exist.
You must format the PROTOCOLS. file properly for the subroutine to work. Format each entry as protocol port [aliases], where protocol is the protocol name, port the decimal port number, and aliases a list of alias names separated by spaces. Comments may appear in the file prefixed by a #.
The PROTOCOLS. file, as supplied, contains standard Internet protocols. Changes to this file may affect the operation of your application and TCPware as well. To avoid conflict, be sure when adding a name or an alias that it is not already in use.
To read the PROTOCOLS. file, use the setprotoent, getprotoent, and endprotoent subroutines:
|
setprotoent(int stayopen) |
opens (or rewinds) the database; if the stayopen value is non-zero, the database remains open |
|
struct protoent *getprotoent |
returns the next entry's protoent structure address, or zero if all entries were read |
|
endprotoent() |
closes the database (unless stayopen is non-zero) |
getprotobynumber
Returns the protocol name or alias for a protocol number.
pe = getprotobynumber(proto)
struct protoent *pe
Address of the returned protoent structure, or 0 (NULL) if no match found. (See the protoent subsection for the protoent structure definition.)
The returned structure is in a static area, so you must copy it to save it.
int proto
Protocol number of the desired protocol name or alias.
Scans the TCPWARE:PROTOCOLS. file and returns the entry for the given protocol name. A process checks the file for modifications by default every 10 minutes and then reloads it into memory if modifications exist.
You must format the PROTOCOLS. file properly for the subroutine to work. Format each entry as protocol port [aliases], where protocol is the protocol name, port the decimal port number, and aliases a list of alias names separated by spaces. Comments may appear in the file prefixed by a #.
The PROTOCOLS. file, as supplied, contains standard Internet protocols. Changes to this file may affect the operation of your application and TCPware as well. To avoid conflict, be sure when adding a name or an alias that it is not already in use. To read from the PROTOCOLS. file, use the setprotoent, getprotoent, and endprotoent subroutines:
|
setprotoent(int stayopen) |
opens (or rewinds) the database; if the stayopen value is non-zero, the database remains open |
|
struct protoent *getprotoent |
returns the next entry's protoent structure address or zero if all entries were read |
|
endprotoent() |
closes the database (unless stayopen is non-zero) |
getprotobyname
Returns the port number for a named service.
se = getservbyname(name, proto)
struct servent *se
Address of the returned servent structure, or 0 (NULL) if no match found. (See the servent subsection for the servent structure definition.) The returned structure is in a static area, so you must copy it to save it. Only the Internet services and protocols are understood.
char *name
Address of an ASCII (null-terminated) string containing the service name (such as FTP) or alias. The string is not case-sensitive.
char *proto
Address of an ASCII (null-terminated) string containing the protocol name (such as TCP or UDP) or alias. The string is not case-sensitive.
Uses the cached-in-memory version of your local Services database to locate the entry for the given service name. A process reloads the Services database into memory every 10 minutes by default if modifications exist. The database is in the TCPWARE:SERVICES. file. The database is reloaded into memory by default every 10 minutes.
If you want to read from the SERVICES. files, edit it in the proper format. Each entry must be service port/protocol [aliases], where: service is the service name, port the decimal port number followed after a slash (/) by protocol, the protocol (TCP or UDP), and aliases a list of alias names separated by spaces. Comments can appear in the file prefixed by a #. If you want to read the SERVICES. file, use the setservent, getservent, and endservent subroutines:
|
setservent(int stayopen) |
opens (or rewinds) the database; if the stayopen value is non-zero, the database remains open |
|
struct servent *getservent |
returns the next entry's servent structure address, or zero if all entries were read |
|
endservent() |
closes the database (unless stayopen is non-zero) |
getservbyport
Returns the service name or alias for a port number.
se = getservbyport(port, proto)
struct servent *se
Address of the returned servent structure, or 0 (NULL) if no match found. (See the servent subsection for the servent structure definition.)
The returned structure is in a static area, so you must copy it to save it. Only the Internet services and protocols are understood.
int port
Port number of the desired service name. Passed in byte reversed order (use the htons subroutine).
char *proto
Address of an ASCII (null-terminated) string containing the protocol name (such as TCP or UDP) or alias. The string is not case-sensitive.
Uses the cached-in-memory version of your local Services database to locate the entry for the given port number. A process reloads the Services database into memory every 10 minutes by default if modifications exist. The database is in the TCPWARE:SERVICES. file. The database is reloaded into memory by default every 10 minutes.
If you want to read from the SERVICES. files, edit it in the proper format. Each entry must be service port/protocol [aliases], where:service is the service name, port the decimal port number followed after a slash (/) by protocol, the protocol (TCP or UDP), and aliases a list of alias names separated by spaces. Comments can appear in the file prefixed by a #. If you want to read the SERVICES. file, use the setservent, getservent, and endservent subroutines:
|
setservent(int stayopen) |
opens (or rewinds) the database; if the stayopen value is non-zero, the database remains open |
|
struct servent *getservent |
returns the next entry's servent structure address, or zero if all entries were read |
|
endservent() |
closes the database (unless stayopen is non-zero) |
getservbyname
Returns the local internet address and port number for a socket.
status= getsockname(s, name, namelen)
int s
Socket descriptor (as returned by socket).
struct sockaddr_in *name
Address of the sockaddr_in structure in which to return the peer's internet address and port number.
(See the sockaddr_in subsection for the sockaddr_in structure definition.)
int *namelen
Address of the length of the sockaddr_in structure (passed to and returned by getsockname).
Returns the local internet address and port number stored in the socket structure. This information is set by bind.
Returns 0 for success and -1 for failure. For a failure status, the errno variable contains the reason for the error as follows:
|
EBADF |
Socket structure is not valid. |
|
EINVAL |
namelen value is incorrect. It must be a pointer to an integer whose value is the size of the sockaddr_in subroutine. |
Returns option information regarding a socket.
The SOCKET.H file contains definitions for the socket-level options. The IN.H file contains definitions for the IPPROTO_IP level options.
status= getsockopt(s, level, optname, optval, optlen)
int s
Socket descriptor (as returned by the socket).
int level
SOL_SOCKET to return socket options, or IPPROTO_IP to return IP options (which requires a SYSTEM UIC, or the SYSPRV or BYPASS privilege).
int optname
Option code to return.
See thesetsockopt description for the currently supported options.
char *optval
Address of the value for the option (if the option requires a value).
int *optlen
On input, length of the optval buffer. On return, amount of data returned to the optval buffer.
The specified socket option value is returned.
Returns 0 for success and -1 for failure. For a failure status, the errno variable contains the reason for the error as follows:
|
EBADF |
Invalid socket structure. |
|
EINVAL |
Invalid optname, optval, or optlen. |
Designed for use by FORTRAN programs to return the internet address for a host name.
C programmers should use the gethostbyname subroutine.
status = HNS_LOOKUPHOST(host-name, internet-address)
CHARACTER*(*) host-name
Address of the string descriptor for the host name (or an ASCII internet address).
INTEGER*4 internet-address
Address of an INTEGER*4 to which the internet address is returned in network byte order.
Calls the gethostbyname subroutine to obtain the internet address for the host.
Returns the following status codes:
|
SS$_NORMAL |
Success. Internet address for the host name has been returned. |
|
SS$_NOSUCHNODE |
No translation for the host name to an internet address could be found. |
Designed for use by FORTRAN programs to return the host name for an internet address.
C programmers should use the gethostbyaddr subroutine.
status = HNS_LOOKUPIA(host-name, internet-address)
CHARACTER*(*) host-name
Address of the string descriptor to which the host name is returned.
INTEGER*4 internet-address
Address of an INTEGER*4 containing the internet address for the host, in network byte order.
Calls the gethostbyaddr subroutine to obtain the host name for the internet address.
Returns the following status codes:
|
SS$_NORMAL |
Success. Host name has been returned. |
|
SS$_NOSUCHNODE |
No host name could be found for the internet address. |
Swaps the byte order of a four-byte integer from VAX byte order to network byte order.
Programmers can use this function to develop programs independent of the hardware architectures.
retval = htonl(val)
int retval
Byte-swapped integer corresponding to val.
int val
Four-byte integer to convert to network byte order.
Converts between 32-bit (long) host byte order and network byte order.
Requires the TYPES.H and IN.H header files.
Returns the byte-swapped integer that corresponds to val. For example, if val is 0xc029e401, the returned value is 0x01e429c0.
Swaps the byte order of a two-byte integer from VAX byte order to network byte order.
Programmers can use this function to develop programs independent of the hardware architectures.
retval = htons(val)
int retval
Byte-swapped integer corresponding to val.
int val
Two-byte integer to convert to network byte order.
Converts between 16-bit (short) host byte order and network byte order.
Requires the TYPES.H and IN.H header files.
Returns the byte-swapped integer that corresponds to val. For example, if val is 0x0017, the returned value is 0x1700.
The inet_ subroutines:
• Convert internet addresses from text to binary form and vice versa
• Build internet addresses when given a network number and local address
• Return the network or local portions of the internet address when given a complete address
The inet_ subroutines are defined in the INET.H header file.
int = inet_addr(cp)
net = inet_network(cp)
cp = inet_ntoa(in)
flg = inet_aton(cp, &in)
in = inet_makeaddr(net, lna)
lna = inet_lnaof(in)
net = inet_netof(in)
ALPHA and I64
The subroutine names are prefixed with tcpware_ to prevent name conflicts with the C language RTL.
struct in_addr in
Internet address in binary form in network byte order. This structure is defined as follows:
struct in_addr {
unsigned long s_addr;
};
char *cp
ASCII character string containing an internet address in standard a.b.c.d format. A program calling these subroutines can specify all ASCII numbers as decimal, octal, or hexadecimal (as specified in C language).
int flg
Flag that returns 1 if cp is a valid ASCII representation of an IP address, and 0 if it is not.
long net
Network number in VAX byte order.
int lna
Host address in VAX byte order.
|
inet_addr |
Converts an internet address from an ASCII string to binary form. Returns -1 if the address is invalid. Supports decimal, hexadecimal, and octal values for the internet address components using standard C notation (that is, the 0x prefix before hexadecimal values and a leading 0 before octal values). |
|
inet_network |
Converts an ASCII network number (a, a.b, or a.b.c) to a binary value in VAX byte order. Returns -1 if the address is invalid. For example, a network number of 192.9.200 would be returned as 0X00C009C8. |
|
inet_ntoa |
Converts an internet address in network order from a binary string to ASCII text format. Returns a pointer to the string in a.b.c.d format. |
|
inet_aton |
Checks an ASCII internet address for validity and converts it to a binary address. Returns 1 if valid, 0 if invalid. Replaces inet_addr since inet_addr cannot distinguish between a failure and a local address. |
|
inet_makeaddr |
Returns an internet address when given a network number and a local address. |
|
inet_lnaof |
Returns the host address portion of an internet address. The returned value is in VAX byte order. |
|
inet_netof |
Returns the network portion of an internet address. The returned value is in VAX byte order. |
You must use the INET.H header file to define these subroutines. The in_addr structure is defined in the IN.H header file.
The inet_addr and inet_network subroutines return -1 if the address is invalid. The program cannot distinguish between an error condition and the 255.255.255.255 internet address.
Returns the bit mask value corresponding to an IPSO authority name.
mask = ipso_getauthbyname (name)
unsigned long mask
Mask corresponding to the name provided, or 0 if no match if found.
char *name
Address of the ASCII string containing the name of the IPSO authority field. See Table A-3 for a list of valid IPSO protection authorities.
This subroutine uses the TCPWARE:IPSO_AUTHORITIES. file to match the name against a bit mask. The IPSO_AUTHORITIES. file must be properly formatted for the subroutine to work. See Example A-1 for sample contents of this file.
Requires the IPSO.H header file.
|
Table A-3 IPSO Protection Authorities |
||
|
Protection Authority |
Hexadecimal Value |
Point of Contact |
|
GENSER |
%X80 |
Designated Approving Authority per DOD 5200.28 |
|
SIOP-ESI |
%X40 |
DoD Joint Chiefs of Staff |
|
SCI |
%X20 |
Director of Central Intelligence |
|
NSA |
%X10 |
National Security Agency |
|
DOE |
%X08 |
Department of Energy |
!GENSER 0x80
!SIOP-ESI 0x40
!SCI 0x20
!NSA 0x10
!DOE 0x08
!
!SITE-SPECIFIC:
ALPHA 0x30 !SCI+NSA
BETA 0x50 !SIOP-ESI+NSA
GAMMA 0x18 !NSA+DOE
DELTA 0x58 !SIOP-ESI+NSA+DOE
Returns the IPSO authority name corresponding to a bit mask value.
char *name = ipso_getauthbynumber (mask)
char *name
Address of the ASCII string to contain the name of the IPSO authority field. See Sample IPSO_AUTHORITIES. File for a list of valid IPSO protection authorities.
unsigned long mask
Mask for the name.
This subroutine uses the TCPWARE:IPSO_AUTHORITIES. file to match the name against a bit mask. The IPSO_AUTHORITIES. file must be properly formatted for the subroutine to work. See Sample IPSO_AUTHORITIES. File for sample contents of this file.
Requires the IPSO.H header file.
Returns the bit mask value corresponding to an IPSO security level.
mask = ipso_getlevelbyname (name)
unsigned long mask
Mask corresponding to the name provided, or 0 if no match if found.
char *name
Address of the ASCII string containing the name of the IPSO security level. See IPSO Security Levels for a list of valid IPSO security levels.
This subroutine searches a list of the IPSO classifications for a name and returns the corresponding bit mask value. See Table A-4 for a list of valid IPSO security levels.
Requires the IPSO.H header file.
|
Table A-4 IPSO Security Levels |
|
|
Security Level |
Hexadecimal Value |
|
Top_Secret |
%X3D |
|
Secret |
%X5A |
|
Confidential |
%X96 |
|
Unclassified |
%XAB |
Returns the IPSO security level corresponding to a bit mask value.
char *name = ipso_getlevelbynumber (mask)
char *name
Address of the ASCII string to contain the name of the IPSO security level. See IPSO Security Levels for a list of valid IPSO security levels.
unsigned long mask
Mask for the name.
This subroutine searches a list of the IPSO classifications for a name and returns the corresponding bit mask value. See IPSO Security Levels for a list of valid IPSO security levels.
Requires the IPSO.H header file.
Makes it possible to listen for connections on a port number. It is only valid for stream sockets and is usually used by the server end of an application.
status = listen(s, backlog)
int s
Socket descriptor (as returned by the socket).
int backlog
Maximum number of outstanding connections that can be queued.
The value of backlog determines the value of the TCPDRIVER passive open access control parameter. If backlog is greater than 1, non-exclusive access is requested. The value of backlog must be between 1 and 16, inclusive. Call the accept subroutine to accept a connection.
The channel associated with the socket is deassigned by listen since the channel will not be used (only the local internet address, port number, and backlog values from the socket structure are used by accept).
accept
select
Returns 0 for success and -1 for failure. For a failure status, the errno variable contains the reason for the error as follows:
|
EACCES |
Insufficient privilege. |
|
EBADF |
Socket structure is not valid. |
|
EINVAL |
Value of backlog is not valid or the socket is already in use. |
|
EOPNOTSUPP |
Not a stream socket. |
Swaps the byte order of a four-byte integer from network byte order to VAX byte order.
Programmers can use this function to develop programs independent of the hardware architectures.
retval = ntohl(val)
int retval
Byte-swapped integer corresponding to val.
int val
Four-byte integer to convert to network byte order.
Converts between 32-bit (long) network byte order and host byte order.
Requires the TYPES.H and IN.H header files.
Returns the byte-swapped integer that corresponds to val. For example, if val is 0x01e429c0, the returned value is 0xc029e401.
Swaps the byte order of a two-byte integer from network byte order to VAX byte order.
Programmers can use this function to develop programs independent of the hardware architectures.
retval = ntohs(val)
int retval
Byte-swapped integer corresponding to val.
int val
Two-byte integer to convert to network byte order.
Converts between 16-bit (short) network byte order and host byte order.
Requires the TYPES.H and IN.H header files.
Returns the byte-swapped integer that corresponds to val. For example, if val is 0x1700, the returned value is 0x0017.
Displays the error message for the error status returned by a Socket Library subroutine.
This subroutine has the same inputs and format as perror; however, it will print the text for network errors (see SOCKERR.H).
status = pneterror(s)
char *s
Address of an ASCII (null-terminated) character string to be displayed before the error text.
Displays the error message for the error code in the errno variable.
Displays the error message for the error status returned by a Socket Library subroutine. If the error code is not a known network error code, the standard VAX C error subroutine is called.
Reads data from an unconnected or connected socket.
msglen = recvfrom(s, buffer, buflen, flags, from, fromlen)
int msglen
-1 for error, 0 for connection closed by peer and no more data available, >0 for the number of bytes of data read.
int s
Socket descriptor (as returned by socket).
char *buffer
Address of the buffer into which the data is to be received.
int buflen
Length of the buffer into which data is to be received.
int flags
Flag bits for operation. The supported flag bits are:
|
Flag Bit |
Description |
|
MSG_NONBLOCKING |
returns immediately if no data is available (EWOULDBLOCK is returned in errno if no data is available). |
|
MSG_PEEK |
lets you peek at the data without removing it from the data stream. |
|
MSG_TRUNCATE |
returns truncated datagrams (otherwise ENOMEM is returned if the datagram is larger than the buffer). This flag is only used by datagram (UDP) sockets. |
|
MSG_TIME |
limits the time to wait for a datagram to be received. The time limit for the receive is set using the setsockopt subroutine. This flag is only used by datagram (UDP) sockets. |
All other flags are ignored.
char *from
Address of the sockaddr_in structure (or 0) to be filled with peer's internet address and port number. (See the sockaddr_in subsection for the sockaddr_in structure definition.)
int *fromlen
Address of the length of the from argument.
• IO$_READVBLK on the socket's channel
• IO$M_NOW modifier if specifying MSG_NONBLOCKING
• IO$M_DATACHECK modifier if specifying MSG_PEEK (see flags)
select, if your application handles multiple connections simultaneously
Returns -1 for failure. For a failure status, the errno variable contains the reason for the error as follows:
|
EBADF |
Socket structure is not valid. |
|
ECONNRESET |
Connection is reset by the peer. |
|
EINVAL |
fromlen value is invalid (for recvfrom only). |
|
EIO |
Unexpected system status returned during operation. |
|
ENETDOWN |
Network was shut down. |
|
ENOMEM |
Buffer was too small for the datagram and MSG_TRUNCATE was not specified. Note that the truncated datagram is in the buffer. |
|
ENOTCONN |
Socket is not connected. |
|
ETIMEDOUT |
Connection timed-out or the request timed-out (if MSG_TIME set for a datagram socket). |
|
EWOULDBLOCK |
MSG_NONBLOCKING flag is set and no data is available. |
The vaxc$errno variable contains the system service or I/O status code for ECONNRESET, EIO, ENETDOWN, ETIMEDOUT, or EWOULDBLOCK.
The resolver subroutines create, send, and interpret packets to DNS servers. DNS is primarily a host name and address lookup service for the Internet, allowing client systems to obtain host names and addresses from DNS servers.
For more information on DNS, see Chapter 6, Domain Name Services, in the Management Guide.
The resolver subroutines:
• Initialize the routines
• Store a standard query message in a buffer
• Send a query to the DNS servers and return an answer
• Compress and expand the domain name
res_init()
res_mkquery(op, dn, class, type, data, datal, newrr, buf, bufl)
res_send(msg, msglen, answer, anslen)
dn_comp(exp-dn, comp-dn, length, dnptrs, lastdnptr)
dn_exp(msg, eomorig, comp-dn, exp-dn, length)
int op
Opcode. Usually QUERY, but can be any of the query types defined in the NAMESER.H header file.
char *dn
Pointer to the domain name. If dn consists of a single label and the RES_DEFNAMES flag is enabled (the default), dn is appended with the current domain name, which is defined by the TCPWARE_DOMAINNAME logical name.
int class
Address class, which is typically C_IN (for Internet).
int type
Query type, which is typically T_A for a host name lookup.
char *data
Pointer to the resource record data.
int datal
Length in bytes of the resource record data.
struct rrec *newrr
Address of the new resource record data structure for modify or append operations.
char buf
Buffer in which the routine places the standard query message data.
int bufl
Length in bytes of the buffer in which the routine places the standard query message data.
char *msg
Pointer to the beginning of the message.
int msglen
Length in bytes of the message.
char *answer
Pointer to the answer to the standard query.
int anslen
Length in bytes of the answer to the standard query.
char *exp_dn
Pointer to a buffer of the expanded domain name.
char *comp-dn
Buffer for the compressed domain name for the expand routine (dn_comp).
int length
Size in bytes of the array to which comp-dn points. In the case of dn_expand, length refers to the length in bytes of the resulting expansion buffer.
char **dnptrs
List of pointers to previously compressed names in the current message. The first pointer points to the beginning of the message and the list ends with NULL.
char **lastdnptr
Pointer to the end of the array to which dnptrs points. Also updates the list of pointers for labels inserted into the message by dn_comp as the name is compressed. If dnptrs is NULL, the names are not compressed; if lastdnptr is NULL, the list is not updated.
char *eomorig
Pointer to the first byte after the message.
|
res_init |
Initializes the routines by getting the default domain name and internet address of the initial host running the name server. The domain name is defined by the TCPWARE_DOMAINNAME logical. The name servers are defined by the TCPWARE_NAMESERVERS logical. |
|
res_mkquery |
Makes a standard query message and places it in buf. The routine returns the size of the query or -1 if the query is larger than bufl. |
|
res_send |
Sends a query to the DNS servers and returns an answer. The routine calls the res_init routine. The length of the message is returned or -1 if there were errors. |
|
dn_comp |
Compresses the domain name and stores it in a buffer (comp_dn). The size of the compressed name is returned, or -1 if there were errors. |
|
dn_expand |
Expands the compressed domain name (dn_comp) to a full domain name. Expanded names are converted to uppercase. The size of the compressed name is returned, or -1 if there was an error. |
The TYPES.H, IN.H, NAMESER.H, and RESOLV.H header files define the structures and constants needed by the resolver routines.
Global information used by the resolver routines is stored in the _res structure. Most of the values have reasonable defaults. The options are a simple bit mask and are OR-ed in to enable. The options are stored in _res.options and the mask values are defined in TCPWARE_INCLUDE:RESOLV.H. The options are as follows:
|
RES_INIT |
Initial name server address and default domain names are initialized. |
|
RES_DEBUG |
Print debugging messages. |
|
RES_AAONLY |
Accept authoritative messages only. |
|
RES_USEVC |
Use TCP connections (virtual circuits) instead of UDP connections for queries. |
|
RES_STAYOPEN |
Used with RES_USEVC to keep the TCP connection open. |
|
RES_RECURSE |
Set the recursion desired bit in queries (the default). The res_send routine does not do iterative queries and expects the BIND server to handle recursion. |
|
RES_DEFNAMES |
Append the default domain name to single-label queries (the default). |
Allows for synchronous I/O multiplexing.
nfound = select(nchan, readds, writeds, exceptds, timeout)
int nfound
Contains -1 for error, 0 for timeout, or the number of sockets ready for reading (>0).
int nchan
If not using the FD_SET, FD_CLR, FD_ZERO macros to build the list of descriptors (see below), nchan must be 0. If using FD_SET, FD_CLR, FD_ZERO, specify FD_SETSIZE for nchan.
int *readds
Address of the descriptor set for the sockets to be checked if ready for reading (if connected) or ready to be accepted (if listening).
The following macros are provided for manipulating the descriptor set:
|
FD_ZERO (&fdset) |
initializes the fdset descriptor set to the null set |
|
FD_SET (s, &fdset) |
includes the socket s in the set |
|
FD_CLR (s,&fdset) |
removes the socket s from the set |
|
FD_ISSET (s,&fdset) |
is non-zero if s is a member of the set |
Use the fd_set typedef to declare a descriptor set. The FD_SETSIZE symbol defines the maximum number of sockets that may be specified in a descriptor set. If not explicitly defined by the user before including the TYPES.H header file, a default value of 64 is used.
Note! It is recommended that you use FD_SET, FD_CLR, FD_ZERO, and FD_ISSET macros as they improve portability and support future revisions to the socket library. Code that directly builds the currently used zero-terminated array of integers (one socket descriptor per integer) should be modified to make use of these macros as soon as possible.
int *writeds
Ignored. For future use (to determine which sockets are ready for writing).
int *exceptds
Ignored. For future use (to determine which sockets have had exceptions).
struct {long tv_sec, tv_usec;} *timeout
Maximum time (in seconds and microseconds) to wait for one or more sockets to be ready.
Checks whether any socket in the readds list is ready to be read or accepted, have timed out, or were reset or closed by the peer. The number of sockets ready is returned in nfound.
If timeout is a nonzero pointer and the time values are 0, a poll is affected and select returns immediately. If timeout is a zero pointer, select returns only after at least one socket is ready. If one or more sockets are ready, the readds list is updated to reflect those sockets that are ready.
A socket may be ready for reading. However, this does not mean a read will complete immediately, because a push may not have been received and more bytes may have been requested than were actually received. We recommend that you do a non-blocking read on the socket.
See the socket_recv routine.
User-written AST routines can call the select_wake() subroutine to wake up a select. select will return 0 (the timeout status) in this case. Calling select_wake when no select is active will cause the next select to return 0 (the timeout status). The subroutine also allows for a sleep state (select(0,0,0,0,&time)) and an infinite wait state (select(0,0,0,0,0)).
Uses the following system resources:
• One buffered-I/O request for each socket (the BUFIO quota must be sufficient for the application)
• One event flag (allocated and freed using LIB$GET_EF and LIB$FREE_EF, respectively)
• One timer (if a timeout points to a nonzero value)
Also, you must enable ASTs if a timer is required.
Returns 0 in nfound for a timeout, -1 for a failure, or the number of sockets ready (>0). For a failure status, the errno variable contains the reason for the error as follows:
|
EBADF |
Invalid or duplicate socket is specified. |
|
EINVAL |
Socket list is not specified or the time out value is negative. |
|
EIO |
Unexpected system status returned during operation. |
|
ENOTCONN |
Socket is not in a valid state. Only connected or listening sockets may be specified in the readds list. |
The vaxc$errno variable contains the system service status code for EIO.
Sends data over an unconnected or connected socket.
cc = sendto(s, buffer, buflen, flags, to, tolen)
int cc
Number of bytes sent or -1 for failure.
int s
Socket descriptor (as returned by socket).
char *buffer
Address of the buffer which contains the data to be sent.
int buflen
Length of the buffer which contains the data to be sent.
int flags
Flag bits for operation. The supported flag bits are:
|
MSG_OOB |
to send urgent data (for stream sockets only). |
All other flags are ignored.
char *to
Address of sockaddr_in structure (defined in IN.H) containing peer's internet address and port number or 0 if none. (See the sockaddr_in subsection for the sockaddr_in structure definition.)
int tolen
Length of the to buffer.
An IO$_WRITEVBLK QIO function is issued on the socket's channel. The IO$M_URGENT modifier is used if MSG_OOB is specified (see flags).
If sendto is called on an unconnected stream (TCP) socket and you specify a to structure, an implicit connect is done before sending the data.
Returns -1 for failure. For a failure status, the errno variable contains the reason for the error as follows:
|
EAFNOSUPPORT |
Address family specified in the to argument of the socket_send/socket_write routine is not AF_INET. |
|
EBADF |
Socket structure is not valid. |
|
ECONNRESET |
Connection is reset by the peer. |
|
EINVAL |
tolen value is invalid (for sendto only). |
|
EIO |
Unexpected system status returned during operation. |
|
EMSGSIZE |
Buffer size is too large or invalid. |
|
ENETDOWN |
Network was shut down. |
|
ENOTCONN |
Socket is not connected and no to structure was provided to connect the socket. |
|
EPIPE |
Connection was closed or reset. |
|
ETIMEDOUT |
Connection timed out. |
The vaxc$errno variable contains the system service or I/O status code for ECONNRESET, EIO, EMSGSIZE, ENETDOWN, EPIPE, or ETIMEDOUT.
Sets the local host's domain name.
status= setdomainname(name, namelen)
status= sethostname(name, namelen)
int len
Length of the domain name string (or 0 if none available).
char *name
Address of an ASCII (null-terminated) string that contains the domain name.
int namelen
Length of the character string.
These routines require sufficient privileges to define a system logical name because they set the TCPWARE_DOMAINNAME system logical name.
getdomainname
gethostname
Returns 0 for success and -1 for failure. For a failure status, the errno variable contains the reason for the error as follows:
|
EPERM |
Returned if the call to SYS$CRELNM fails with the SS$_NOPRIV status. |
|
EVMSERR |
Returned if the call to SYS$CRELNM fails with any status other than SS$_NOPRIV. |
The vaxc$errno variable contains the status code returned by SYS$CRELNM.
Sets socket processing options.
The SOCKET.H file contains definitions for the socket-level options. The IN.H file contains definitions for the IPPROTO_IP level options.
status= setsockopt(s, level, optname, optval, optlen)
int s
Socket descriptor (as returned by socket).
int level
SOL_SOCKET to change socket options, or IPPROTO_IP to change IP options (which requires system UIC, SYSPRV, or BYPASS privilege).
int optname
Option code to change. See Table A-5 for the SOL_SOCKET option values and Table A-6 for the IPPROTO_IP option values.
char *optval
Address of the value for the option (if the option requires a value).
int optlen
Length of optval (if the option requires a value).
The specified socket option is changed.
Returns 0 for success and -1 for failure. For a failure status, the errno variable contains the reason for the error as follows:
|
EADDRNOTAVAIL |
Address not available for use. |
|
EADDRINUSE |
Address already in use. |
|
EBADF |
Socket structure is not valid. |
|
EINVAL |
Invalid optname is specified or the optlen or optval arguments are invalid. |
|
ENOBUFS |
Insufficient memory for requests. |
|
ETOOMANYREFS |
Too many multicast memberships requested. |
|
Table A-5 Optname Argument Values for SOL_SOCKET Level |
|
|
SOL_SOCKET Option |
Description |
|
SO_IOCHAN |
Obtains the socket's OpenVMS I/O channel number. optval is the address of a short to receive the I/O channel number. |
|
SO_RCVTIMEO |
Sets the timeout value for datagram (UDP) sockets when the MSG_TIME flag is used in socket_recv or recvfrom calls. The optval option is the address of a short containing the timeout time (in seconds); optlen = sizeof (short). The default value (set by socket) is 5 seconds. |
|
SO_REUSEADDR |
Enables shared access mode on the local port for datagram (UDP) sockets. The optval and optlen arguments are ignored. |
|
SO_SNDTIMEO |
Sets the timeout value for stream (TCP) sockets. The optval option is the address of a short containing the timeout time (in seconds); optlen = sizeof (short). The default value (set by socket) is 120 seconds. The minimum value is 20 seconds. |
|
Table A-6 Optname Argument Values for IPPROTO_IP Level |
|
|
IPPROTO_IP Option |
Description |
|
IP_OPTIONS (1) |
Gets or sets IP options to be sent in subsequent datagrams |
|
IP_TOS (3) |
Gets or sets the IP type of service (TOS) to sent in subsequent datagrams |
|
IP_TTL (4) |
Gets or sets the IP time-to-live (TTL) to sent in subsequent datagrams |
|
IP_MULTICAST_IF (16) |
Gets or sets the interface used for sending multicast datagrams |
|
IP_MULTICAST_TTL (17) |
Gets or sets the IP time-to-live (TTL) to sent in subsequent datagrams |
|
IP_MULTICAST_LOOP (18) |
Gets or sets whether sent multicast datagrams should be looped back locally |
|
IP_ADD_MEMBERSHIP (19) |
Adds a multicast group membership for an interface |
|
IP_DROP_MEMBERSHIP (20) |
Drops a multicast group membership from an interface |
Closes or aborts the connection for a socket.
status= shutdown(s, how)
int s
Socket descriptor (as returned by socket).
int how
0 to close the receive side (ignored for stream sockets), 1 to close the sending side (ignored for datagram sockets), and 2 to abort the connection.
The operation specified by the how argument is performed.
To close a connection fully, use the socket_close subroutine.
Note! Always call the socket_close subroutine to clean up a socket.
Depending on the value of the how argument, one of the following QIO functions is issued on the channel:
• IO$_SETMODE | IO$M_CTRL | IO$M_SHUTDOWN
• IO$_SETMODE | IO$M_CTRL | IO$M_SHUTDOWN | IO$M_ABORT
socket_close
Returns 0 for success and -1 for failure. For a failure status, the errno variable contains the reason for the error as follows:
|
EBADF |
Socket structure is not valid. |
|
EINVAL |
Socket is not in a valid state or the value for how is not valid. |
Creates a socket structure.
Must be called to allocate a socket structure before calling bind, connect, listen, accept, socket_send or sendto, socket_recv or recvfrom, shutdown, or socket_close.
s = socket(af, type, protocol)
int s
Socket descriptor or -1. This socket descriptor is the address of the socket structure maintained by the Socket Library subroutines. This socket structure is defined in SOCKETVAR.H.
int af
Address family (must be AF_INET = 2). AF_INET is defined in SOCKET.H.
int type
SOCK_STREAM (for TCP), SOCK_DGRAM (for UDP), or SOCK_RAW (for IP). These constants are defined in SOCKET.H.
int protocol
Must be 0 for SOCK_STREAM and SOCK_DGRAM. For SOCK_RAW, protocol is the IP protocol number.
A socket structure is allocated using LIB$GET_VM and added to the linked list of socket structures. The socket structure is initialized and a TCP, UDP, or IP channel is assigned.
The socket structure returned by socket is deallocated by calling the socket_close subroutine.
Returns -1 for failure. For a failure status, the errno variable contains the reason for the error as follows:
|
EAFNOSUPPORT |
Input parameter is invalid. |
|
ENETDOWN |
Call to SYS$ASSIGN failed. vaxc$errno contains the status code returned by SYS$ASSIGN. |
|
ENOBUFS |
Call to LIB$GET_VM failed. vaxc$errno contains the status code returned by LIB$GET_VM. |
Closes and deallocates a socket.
Note! Under UNIX, the standard close subroutine is used. The VAX C close subroutine cannot be used with sockets.
status= socket_close(s)
int s
Socket descriptor (as returned by socket).
This subroutine closes the connection and receives (and discards) any data not yet read. The channel for the socket is deassigned and the socket structure is then deallocated (using LIB$FREE_VM).
Returns 0 for success and -1 for failure. For a failure status, the errno variable contains the reason for the error as follows:
|
EBADF |
Socket structure is not valid. |
Performs several control functions on a socket.
The IOCTL.H file contains definitions for this subroutine.
status= socket_ioctl(s, request, argp)
int s
Socket descriptor (as returned by socket).
int request
Request code for the control function. Supported request codes are:
|
Supported Request Codes |
Description |
|
FIOASYNC |
Sets or clears asynchronous I/O. If argp=1, descriptor is set for asynchronous I/O. If 0, descriptor is cleared for asynchronous I/O. |
|
FIONREAD |
Returns the number of bytes available for reading on the socket to the longword specified by argp. |
|
SIOCATMARK |
Returns whether the stream socket is at the out-of-band mark. If at the out-of-band mark, 1 is returned to the longword specified by argp. Otherwise, 0 is returned. |
|
SIOCDARP |
Used to Delete, Get, or Set an ARP table entry. The argp argument points to an arpreq structure (see the IF_ARP.H file for the definition of this structure). |
|
SIOCGIFADDR |
Used to obtain information about a network The argp argument points to a ifreq structure (see the IF.H file for the definition of this structure). |
|
SIOCGIFCONF |
Used to obtain a list of the available network interfaces. The argp argument points to an ifconf structure (see the IF.H file for the definition of this structure). |
|
SIOCADDRT |
Used to Add or Delete a routing table entry. The argp argument points to an rtentry structure (see the ROUTE.H file for the definition of this structure). |
char *argp
Address of the buffer to receive the information or that contains information, depending on the request.
Returns 0 for success and -1 for failure. For a failure status, the errno variable contains the reason for the error as follows:
|
EBADF |
Socket structure is not valid. |
|
EINVAL |
Input request or buffer address is invalid. |
Read data from a connected socket.
Note that under UNIX, socket_read is called read and socket_recv is called recv.
msglen = socket_read(s, buffer, buflen)
msglen = socket_recv(s, buffer, buflen, flags)
int msglen
-1 for error, 0 for connection closed by peer and no more data available, >0 for the number of bytes of data read.
int s
Socket descriptor (as returned by socket).
char *buffer
Address of the buffer into which the data is to be received.
int buflen
Length of the buffer into which data is to be received.
int flags
Flag bits for operation. The supported flag bits are:
|
Flag Bit |
Description |
|
MSG_NONBLOCKING |
returns immediately if no data is available (EWOULDBLOCK is returned in errno if no data is available). |
|
MSG_PEEK |
lets you peek at the data without removing it from the data stream. |
|
MSG_TRUNCATE |
returns truncated datagrams (otherwise ENOMEM is returned if the datagram is larger than the buffer). This flag is only used by datagram (UDP) sockets. |
|
MSG_TIME |
limits the time to wait for a datagram to be received. The time limit for the receive is set using the setsockopt subroutine. This flag is only used by datagram (UDP) sockets. |
All other flags are ignored.
• IO$_READVBLK on the socket's channel
• IO$M_NOW modifier if specifying MSG_NONBLOCKING
• IO$M_DATACHECK modifier if specifying MSG_PEEK (see flags)
select, if your application handles multiple connections simultaneously
Returns -1 for failure. For a failure status, the errno variable contains the reason for the error as follows:
|
EBADF |
Socket structure is not valid. |
|
ECONNRESET |
Connection is reset by the peer. |
|
EIO |
Unexpected system status returned during operation. |
|
ENETDOWN |
Network was shut down. |
|
ENOMEM |
Buffer was too small for the datagram and MSG_TRUNCATE was not specified. Note that the truncated datagram is in the buffer. |
|
ENOTCONN |
Socket is not connected. |
|
ETIMEDOUT |
Connection timed-out or the request timed-out (if MSG_TIME set for a datagram socket). |
|
EWOULDBLOCK |
MSG_NONBLOCKING flag is set and no data is available. |
The vaxc$errno variable contains the system service or I/O status code for ECONNRESET, EIO, ENETDOWN, ETIMEDOUT, or EWOULDBLOCK.
Send data over a connected socket.
Note! Under UNIX, socket_send is called send and socket_write is called write.
cc = socket_send(s, buffer, buflen, flags)
cc = socket_write(s, buffer, buflen)
int cc
Number of bytes sent or -1 for failure.
int s
Socket descriptor (as returned by socket).
char *buffer
Address of the buffer which contains the data to be sent.
int buflen
Length of the buffer which contains the data to be sent.
int flags
Flag bits for operation. The supported flag bits are MSG_OOB to send urgent data (for stream sockets only). All other flags are ignored.
• IO$_WRITEVBLK is issued on the socket's channel
• IO$M_URGENT modifier is used if MSG_OOB is specified (see flags)
Returns -1 for failure. For a failure status, the errno variable contains the reason for the error as follows:
|
EAFNOSUPPORT |
Address family specified in the to argument of the sendto routine is not AF_INET. |
|
EBADF |
Socket structure is not valid. |
|
ECONNRESET |
Connection is reset by the peer. |
|
EIO |
Unexpected system status returned during operation. |
|
EMSGSIZE |
Buffer size is too large or invalid. |
|
ENETDOWN |
Network was shut down. |
|
ENOTCONN |
Socket is not connected and no to structure was provided to connect the socket. |
|
EPIPE |
Connection was closed or reset. |
|
ETIMEDOUT |
Connection timed out. |
The vaxc$errno variable contains the system service or I/O status code for ECONNRESET, EIO, EMSGSIZE, ENETDOWN, EPIPE, or ETIMEDOUT.
Returns the numeric TCPware line ID for the ASCII (null-terminated) string.
lineid =tcpware_atolineid(name)
unsigned long lineid
Numeric line ID of the character string or 0 if the character string is not a valid line ID. For a description of the line ID values, see the description of IO$_SENSEMODE | IO$M_CTRL in the IPDRIVER Services chapter in this guide.
char *name
Line ID character string. For a description of valid TCPware line IDs, see the description of START/IP in the NETCU Command Reference.
Returns the current timezone information.
status = tcpware_gettimezone(seconds, name)
int *seconds
Longword into which to return the offset, in seconds, from universal time.
char **name
Address to which to return the address of the time zone string.
tcpware_settimezone
A standard OpenVMS status code is returned to the caller.
Converts the numeric line ID (lineid) into an ASCII (null-terminated) string.
retval = tcpware_lineidtoa(lineid, name)
char *retval
Address of ASCII string corresponding to lineid (address of name string).
unsigned long lineid
Numeric line ID to be converted into string format.
char *name
Address of a character string in which tcpware_lineidtoareturns the line ID. This string should be at least 16 characters in length.
Gets the I/O channel number or creates a socket for a server connection (TCP or UDP) that was initiated by the master server (NETCP).
status = tcpware_server(option, argument)
int option
|
If option equals... |
The subroutine returns a... |
|
1 |
channel number in argument. |
|
2 |
socket descriptor in argument. |
int *argument
Address of an integer that receives a channel or socket number.
Server processes that are created by the master server (NETCP) call this subroutine. Provides the server process with the socket descriptor or OpenVMS I/O channel number that is associated with the connection. Obtains these values from NETCP through mailbox communication.
Returns 0 for success or -1 for failure. For a failure status, the errno variable describes the reason for the error as follows:
|
EINVAL |
Option argument is invalid. |
|
EIO |
Unexpected system status returned during operation. |
|
ENODEV |
NETCP did not create the server process. |
Sets the current time zone information.
Requires SYSNAM and OPER privileges.
status = tcpware_settimezone(seconds, name)
int seconds
Offset, in seconds, from universal time.
char *name
Address of the time zone string. Specify 0 if no time zone name.
This routine defines the TCPWARE_TIMEZONE system logical name. In addition, tcpware_settimezone also sets the IPDRIVER's universal time (UT) offset value.
The TCPWARE_TIMEZONE logical can have two equivalence strings:
|
4. +hhmmss |
hh are the hours Note! + is for east of the central meridian, - is for west. For example: +04:00:00 is four hours east of the central meridian at Greenwich. Another example: eastern standard time (EST) is five hours west of UT, so the offset is -0500. |
|
5. name |
an optional name for the time zone. For example: EDT for Eastern Daylight time. Can be one of the following: Universal Time—UT, UTC or GMT North American Time—EST, EDT, CST, CDT, MST, MDT, PST, PDT Military Time—Any single uppercase letter A through Z except J (this format is not recommended) Any other character sequence The name is not validated and may be used by applications to report the local time zone. |
These programs are in TCPWARE_COMMON:[TCPWARE.EXAMPLES]DISCARD.C and DISCARDD.C. The latter calls the tcpware_server subroutine to implement the Discard Protocol (DISCARDD). Under this protocol, the server listens for a connection on TCP port 9. Once the server establishes a connection, it throws away any data it receives. It does not send a response. This continues until the client closes the connection.
Example A-2 shows the NETCU command you can use to enable DISCARDD.
ADD SERVICE DISCARD TCP TCPWARE:DISCARDD-
/PROCESS_NAME=DISCARDD-
/NOACCOUNTING-
/NOAUTHORIZE-
/INPUT=NLA0:-
/OUTPUT=NLA0:-
/ERROR=NLA0:-
/UIC=[SYSTEM]-
/AST_LIMIT=10-
/BUFFER_LIMIT=10240-
/ENQUEUE_LIMIT=6-
/EXTENT=500-
/FILE_LIMIT=20-
/IO_BUFFERED=6-
/IO_DIRECT=6-
/MAXIMUM_WORKING_SET=300-
/PAGE_FILE=10000-
/PRIORITY=4-
/PRIVILEGES=(NOSAME,NETMBX,TMPMBX)-
/QUEUE_LIMIT=8-
/WORKING_SET=200-
/SUBPROCESS_LIMIT=0
Chapter 2 in the NETCU Command Reference explains how to use the ADD SERVICE command.
For an additional program using the tcpware_server subroutine, see the TCPWARE_COMMON:[TCPWARE.EXAMPLES]DAYTIMED.C file.