HP OpenVMS Systems Documentation

HP TCP/IP Services for OpenVMS
Sockets API and System Services Programming

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.

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.