HP OpenVMS systems documentation

Calls to various Sockets API functions return information in a static area. The OpenVMS environment allows an asynchronous system trap (AST) function to interrupt a Sockets API function during its execution. In addition, the ASTs of more privileged modes can interrupt ASTs of less privileged modes. Therefore, be careful when calling a Sockets API function from an AST state while a similar Sockets API function is being called from either a non-AST state or a less-privileged access mode. You can use the SYS$SETAST system service to enable and disable the reception of AST requests.

The Sockets API functions that use a static area are:

• gethostbyaddr()
• gethostbyname()
• getnetbyaddr()
• getnetbyname()
• getservbyname()
• getservbyport()
• getprotobyname()
• getprotobynumber()

The following functions accept both 32-bit and 64-bit addresses:

• send()
• recv()
• sendto()
• sendmsg()
• recvfrom()
• recvmsg()

To accept 64-bit addresses, the program must have the _INITIAL_POINTER_SIZE compiler option set to 64.

The sendmsg() and recvmsg() functions accept a pointer to the msghdr structure, which can be specified for either 32-bit or 64-bit addresses, as described in Section 3.2.8.

3.9 Standard I/O Functions

You cannot use standard I/O functions with the Sockets API. Specifically, the fdopen() function does not support sockets.

3.10 Guidelines for Compiling and Linking IPv6 Applications

To compile an IPv6 application that includes a file specification preceded by "path/" , you need to set up the environment as described in this section.

For example, if the application includes the following:

#include <path/file.h>

Set up the environment using the following commands:

$ DEFINE DECC$SYSTEM_INCLUDE TCPIP$EXAMPLES: $ DEFINE ARPA TCPIP$EXAMPLES: $ DEFINE NET TCPIP$EXAMPLES: $ DEFINE NETINET TCPIP$EXAMPLES: $ DEFINE SYS TCPIP$EXAMPLES:

If you are using any of the advanced APIs, you should:

• Add /INCLUDE_DIRECTORY=TCPIP$EXAMPLES: to the COMPILE command line. This allows the compiler to use the updated header files that exist in the TCPIP$EXAMPLES directory. Otherwise, the compiler will use the header files from the OpenVMS C Run-Time Library.
• Add TCPIP$LIBRARY:TCPIP$LIB/LIBRARY to the LINK command line. This allows the linker to resolve references to functions from TCPIP$LIB.OLB provided by TCP/IP Services.

See Section E.6 for examples of the COMPILE and LINK command lines.

3.11 Compatibility with the OpenVMS C Run-Time Library

To maintain compatibility with the HP C Run-Time Library for OpenVMS Version 4.0, use the predefined macro _DECC_V4_SOURCE, as shown in the format of the socket functions listed in Chapter 4. For more information about using macros, refer to the HP C Run-Time Library Reference Manual for OpenVMS Systems.

3.12 Error Checking: errno Values

Most Sockets API functions return a value that indicates whether the function was successful or unsuccessful. A return value of zero (0) indicates success, and a value of --1 indicates the function was unsuccessful.

If the function is not successful, it stores an additional value in the external variable errno . The value stored in errno is valid only when the function is not successful. The error codes are defined in the ERRNO.H header file.

All return codes and error values are of type integer unless otherwise noted.

The errno values can be translated to a message similar to those found on UNIX systems by using the perror() function. The perror() function writes a message on the standard error stream that describes the current setting of the external variable errno . The error message includes a character string containing the name of the function that caused the error followed by a colon (:), a blank space, the system message string, and a newline character.

3.12.1 errno values

Table 3-11 lists the possible errno values.

Table 3-11 errno Values

Error	Description
EADDRINUSE	Address already in use.
	Each address can be used only once.
EADDRNOTAVAIL	Cannot assign requested address.
	Normally, these values result from an attempt to create a socket with an address not on this machine.
EAFNOSUPPORT	Address family not supported by protocol family.
	An address incompatible with the requested protocol was used.
EALREADY	Operation already in progress.
	An operation was attempted on a nonblocking object that already had an operation in progress.
ECONNABORTED	Software caused connection abort.
	Indicates that the software caused a connection abort because there is no space on the socket's queue and the socket cannot receive further connections.
	A connection abort occurred internal to your host machine.
ECONNREFUSED	Connection refused.
	No connection could be made because the target machine actively refused it. This usually results from trying to connect to a service that is inactive on a remote host.
ECONNRESET	Connection reset by peer.
	A connection was forcibly closed by a peer. This usually results from the peer executing a shutdown() call.
EDESTADDRREQ	Destination address required.
	A required address was omitted from an operation on a socket.
EHOSTDOWN	Host is down.
	A socket operation failed because the destination host was down.
EHOSTUNREACH	No route to host.
	A socket operation to an unreachable host was attempted.
EINPROGRESS	Operation now in progress.
	An operation that takes a long time to complete, such as connect() , was attempted on a nonblocking object.
EISCONN	Socket is already connected.
	A connect() request was made on a socket that was already connected, or a sendto() or sendmsg() request on a connected socket specified a destination other than the connected party.
	A path name lookup involved more than eight symbolic links.
EMSGSIZE	Message too long.
	A message sent on a socket was larger than the internal message buffer.
ENETDOWN	Network is down.
	A socket operation encountered a dead network.
ENETRESET	Network dropped connection on reset.
	The host you were connected to failed and rebooted.
ENETUNREACH	Network is unreachable.
	A socket operation to an unreachable network was attempted.
ENOBUFS	No buffer space available.
	An operation on a socket or pipe was not performed because the system lacked sufficient buffer space.
ENOPROTOOPT	Protocol not available.
	An invalid option was specified in a getsockopt() or setsockopt() call.
ENOTSOCK	Socket operation on a nonsocket.
ENTOTCONN	Socket is not connected.
	Request to send or receive data was not allowed because the socket is not connected.
EOPNOTSUPP	Operation not supported.
	For example, trying to accept a connection on a datagram socket.
EPFNOSUPPORT	Protocol family not supported.
	The protocol family was not configured into the system or no implementation for it exists.
EPROTONOSUPPORT	Protocol not supported.
	The protocol was not configured into the system or no implementation for it exists.
EPROTOTYPE	Protocol wrong type for socket.
	A protocol was specified that does not support the semantics of the socket type requested. For example you cannot use the ARPA Internet UDP protocol with type SOCK_STREAM .
ESHUTDOWN	Cannot send after socket shutdown.
	A request to send data was not allowed because the socket had already been shut down with a previous shutdown() call.
ESOCKTNOSUPPORT	Socket type not supported.
	Support for the socket type was not configured into the system or no implementation for it exists.
ETIMEDOUT	Connection timed out.
	A connect() request failed because the connected party did not respond properly after a period of time. (The timeout period is dependent on the communication protocol.)
EVMSERR	OpenVMS error code is nontranslatable.

3.12.2 Relationship Between errno and h_errno

A function failure sets either h_errno or errno , depending on which is appropriate for the failing condition.

The following example shows how to handle errors from the gethostbyname() function.

#include <errno.h> #include <stdio.h> #include <netdb.h> main() { static char hostname[256]; struct hostent *hostentptr; errno = 0; h_errno = 0; if ((hostentptr = gethostbyname("hndy")) == NULL) { printf("unknown host name errno is: %d h_errno is: %d\n", errno, h_errn (1) perror("p_gethostbyname"); herror("h_gethostbyname"); } errno = 0; h_errno = 0; if ((hostentptr = gethostbyname(0)) == NULL) { printf("illegal host name errno is: %d h_errno is: %d\n", errno, h_errn (2) perror("p_gethostbyname"); herror("h_gethostbyname"); } }

This example handles two types of errors from the gethostbyname() function.

1. The host name parameter hndy does not represent a known host. In this case, gethostbyname() sets h_errno to HOST_NOT_FOUND, but does not set errno .
   The call to perror in this example would output:

   p_gethostbyname: Error 0

   
   The call to herror in this example would print a message describing the failure:

   h_gethostbyname: Unknown

2. The host name parameter is 0 (zero), an invalid argument. In this case, gethostbyname() sets errno to EINVAL, but does not set h_errno .
   A call to perror would print a message describing the failure:

   p_gethostbyname: Invalid

   
   A call to herror would print:

   h_gethostbyname: Error 0

This chapter describes the Sockets API functions.

4.1 Summary of Socket Functions

This chapter describes the Sockets API functions that are listed in Table 4-1.

Table 4-1 Sockets API Functions

Function	Description
accept()	Accepts a connection on a passive socket.
bind()	Binds a name to a socket.
close()	Closes a connection and deletes a socket descriptor.
connect()	Initiates a connection on a socket.
decc$get_sdc()	Returns the socket device's OpenVMS I/O channel associated with a socket descriptor (for use with the HP C run-time library).
decc$socket_fd()	Returns the socket descriptor associated with a Socket Device Channel (SDC).
endhostent()	Closes the hosts database file.
endnetent()	Closes the network database file.
endprotent()	Resets the index for the protocols table.
endservent()	Closes the network services database file.
freeaddrinfo()	Returns addrinfo structures and dynamic storage to the system.
freehostent()	Deprecated function. Replace with freeaddrinfo() .
gai_strerror()	Describes an error value for the getaddrinfo() and getnameinfo() functions.
getaddrinfo()	Protocol-independent function for mapping names to addresses.
gethostaddr()	Returns the standard host address for the processor.
gethostbyaddr()	Searches the hosts database for a host record with a given IPv4 address.
gethostbyname()	Searches the hosts database for a host record with a given name or alias.
gethostent()	Retrieves an entry from the hosts database file.
gethostname()	Returns the fully qualified name of the local host.
getipnodebyaddr()	Deprecated function. Replace with getaddrinfo() .
getipnodebyname()	Deprecated function. Replace with getnameinfo() .
getnameinfo()	Protocol-independent function for mapping addresses to names.
getnetbyaddr()	Searches the network database for a network record with a given address.
getnetbyname()	Searches the network database for a network record with a given name or alias.
getnetent()	Gets a network file entry from the networks database file.
getservent()	Retrieves an entry from the services database file.
getpeername()	Returns the name of the connected peer.
getprotobyname()	Searches the protocols database until a matching protocol name is found or until end of file is encountered.
getprotobynumber()	Searches the protocols database until a matching protocol number is found or until end of file is encountered.
getprotoent()	Gets a protocol database entry from the network services database.
getservbyname()	Gets information on the named service from the network services database.
getservbyport()	Gets information on the named port from the network services database.
getsockname()	Returns the name associated with a socket.
getsockopt()	Returns the options set on a socket.
herror()	Writes a message to standard error explaining h_error .
hostalias()	Searches for host aliases associated with a name.
hsterror()	Returns an error message string.
htonl()	Converts longwords from host byte order to network byte order.
htons()	Converts short integers from host byte order to network byte order.
if_freenameindex()	Frees dynamic memory allocated by if_nameindex() to the array of interface names and indexes.
if_indextoname()	Maps an interface index to its corresponding name.
if_nameindex()	Returns an array of all interface names and indexes.
if_nametoindex()	Maps an interface name to its corresponding index.
inet6_opt_append()	Returns the length of an IPv6 extension header with a new option and appends the option.
inet6_opt_find()	Finds a specific option in an extension header.
inet6_opt_finish()	Returns the total length of an IPv6 extension header, including padding, and initializes the option.
inet6_opt_get_val()	Extracts data items from the data portion of an IPv6 option.
inet6_opt_init()	Returns the length of an IPv6 extension header with no options and initializes the header.
inet6_opt_next()	Parses received option extension headers.
inet6_opt_set_val()	Adds one component of the option content to the options header.
inet6_rth_add()	Adds an IPv6 address to the routing header under construction.
inet6_rth_getaddr()	Retrieves an address for an index from an IPv6 routing header.
inet6_rth_init()	Initializes an IPv6 routing header.
inet6_rth_reverse()	Reverses the order of addresses in an IPv6 routing header.
inet6_rth_segments()	Returns the number of segments (addresses) in an IPv6 routing header.
inet6_rth_space()	Returns the number of bytes required for an IPv6 routing header.
inet_addr()	Deprecated function. Replace with inet_aton() .
inet_aton()	Converts a string to an IP address stored in a structure. Replaces the inet_addr() function.
inet_lnaof()	Returns the local network address portion of an IP address.
inet_makeaddr()	Returns an IP address, given a network address and a local address on that network.
inet_netof()	Returns the IP network address portion of an IP address.
inet_network()	Converts a null-terminated text string representing an IP address into a network address in local host format.
inet_ntoa()	Converts an IP address into an ASCII (null-terminated) string.
inet_ntop()	Converts a numeric address into a text string suitable for presentation.
inet_pton()	Converts an address in its standard text presentation form into its numeric binary form, in network byte order.
ioctl()	Controls devices. Used for setting sockets for nonblocking I/O.
listen()	Converts an unconnected socket into a passive (listen) socket and indicates that the TCP/IP kernel should accept incoming requests directed to the socket.
ntohl()	Converts longwords from network byte order into host byte order.
ntohs()	Converts short integers from network byte order into host byte order.
poll()	Monitors conditions on multiple file descriptors.
read()	Reads bytes from a file or socket and places them into a user-defined buffer.
recv()	Receives bytes from a connected socket and places them into a user-defined buffer.
recvfrom()	Receives bytes for a socket from any source.
recvmsg()	Receives bytes on a socket and places them into scattered buffers.
select()	Allows the polling or checking of a group of sockets for I/O activity.
send()	Sends bytes through a socket to a connected peer.
sendmsg()	Sends gathered bytes through a socket to any other socket.
sendto()	Sends bytes through a socket to any other socket.
sethostent()	Opens the hosts database file.
setnetent()	Opens the networks database file.
setprotent()	Sets the state of the protocols table.
setservent()	Opens the services database file.
setsockopt()	Sets options on a socket.
shutdown()	Shuts down all or part of a bidirectional connection on a socket.
socket()	Creates an endpoint for communication by returning a socket descriptor.
socketpair()	Creates a pair of connected sockets.
write()	Writes bytes from a user-defined buffer to a file or socket.
vaxc$get_sdc()	Not supported. Replace with decc$get_sdc() .