HP TCP/IP Services for OpenVMS

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

Contents

Index

Appendix C
Data Types

As part of the OpenVMS common language environment, the TCP/IP system services data types provide compatibility between procedure calls that support many different high-level languages. Specifically, the OpenVMS data types apply to Alpha, I64, and VAX architectures as the mechanism for passing argument data between procedures. This appendix describes the context and structure of the TCP/IP system services data types and identifies the associated declarations to each of the specific high-level language implementations.

C.1 OpenVMS Data Types

In Chapter 6, the OpenVMS usage entry in the TCP/IP Services documentation format for system services indicates the OpenVMS data type of the argument. Most data types can be considered conceptual types; that is, their meaning is unique in the context of the OpenVMS operating system. The OpenVMS data type access_mode is one example. The storage representation of this OpenVMS type is an unsigned byte, and the conceptual content of this unsigned byte is the fact that it designates a hardware access mode and therefore has only four valid values: 0, kernel mode; 1, executive mode; 2, supervisor mode; and 3, user mode. However, some OpenVMS data types are not conceptual types; that is, they specify a storage representation but carry no other semantic content in the OpenVMS context. For example, the data type byte_signed is not a conceptual type.

Note

The OpenVMS usage entry is not a traditional data type such as the OpenVMS standard data types---byte, word, longword, and so on. It is significant only within the OpenVMS operating system environment and is intended solely to expedite data declarations within application programs.

To use the OpenVMS usage entry, perform the following steps:

Find the data type in Table C-1 and read its definition.
Find the same OpenVMS data type in the C and C++ language implementation table (Table C-2) and its corresponding source language type declaration.
Use this code as your type declaration in your application program. Note that, in some instances, you might have to modify the declaration.
For all other OpenVMS data types, refer to the HP OpenVMS Programming Concepts, Volume 2 manual.

Table C-1 lists and describes OpenVMS data type declarations for the OpenVMS usage entry of system services unique to TCP/IP Services.

Table C-1 TCP/IP Services Usage Data Type Entries
Data Type Definition

buffer_list Structure that consists of one or more descriptors defining the length and starting address of user buffers. On Alpha and I64 systems, each descriptor can be a 32- or 64-bit fixed-length descriptor. On VAX systems, each descriptor is a 32-bit fixed-length descriptor. For more information concerning descriptors, see the OpenVMS Calling Standard.

input_parameter_list Structure that consists of one or more item_list_2 or ioctl_comm structures.
Each item_list_2 structure describes an individual parameter that can be set by a service. Such parameters include socket or protocol options as identified by the item's type field.
Each ioctl_comm structure describes an IOCTL command; its encoded request code and address of its associated argument.

ioctl_comm Quadword structure that describes an IOCTL command's encoded request code and address of its associated argument. It contains two longword fields, as depicted in the following diagram:

The first field is a longword containing the IOCTL encoded request code specifying the type of I/O control operation to be performed.
The second field is a longword containing the address of a variable or a data structure targeted by this IOCTL command.

item_list_2 Quadword structure that describes the size, data type, and starting address of a user-supplied data item. It contains three fields, as depicted in the following diagram:

The first field is a word containing the length (in bytes) of the user-supplied data item being described.
The second field is a word containing a symbolic code specifying the data type of the user-supplied data item.
The third field is a longword containing the starting address of the user-supplied data item.

item_list_2 descriptor An item_list_2 structure, used as an argument descriptor and containing structural information about the argument's type and the address of a data item. This data item is associated with the argument.
The format of this descriptor is unique to TCP/IP Services and supplements argument descriptors defined in the OpenVMS Calling Standard.

item_list_3 A 12-byte structure that describes the size, data type, and address of a buffer in which a service writes information. It contains four fields, as depicted in the following diagram:

The first field is a word containing the length (in bytes) of the buffer in which a service writes information. The length of the buffer needed depends on the data type specified in the type field. If the value of buffer length is too small, the service truncates the data.
The second field is a word containing a symbolic code and specifies the type of information that a service is to return.
The third field is a longword containing the address of the buffer in which a service writes the information.
The fourth field is a longword containing the address of a longword in which a service writes the length in bytes of the information it actually returned.

item_list_3 descriptor An item_list_3 structure, used as an argument descriptor and containing structural information about the argument's type and the address of a buffer used to return service information. This buffer is associated with the argument.
The format of this descriptor is unique to TCP/IP Services and supplements argument descriptors defined in the OpenVMS Calling Standard.

output_parameter_list Structure that consists of one or more item_list_3 or ioctl_comm structures.
Each item_list_3 structure describes an individual parameter that can be returned by a service. Such parameters include socket or protocol options as identified by the item's type field.
Each ioctl_comm structure describes an IOCTL command, its encoded request code, and the address of its associated argument.

socket_name Internet domain socket address structure that consists of an Internet address and a port number. The layouts of socket address structures of BSD Version 4.3 and BSD Version 4.4 are different.
BSD Version 4.3 specifies a 16-byte IPv4 socket address structure. It contains four fields, as depicted in the following diagram:

The first field is a word identifying a socket address structure as belonging to the internet domain (always a value of 2).
The second field is a word containing a 16-bit port number (stored in network byte order) used to demultiplex transport-level messages.
The third field is a longword containing a 32-bit IPv4 internet address (stored in network byte order).
The fourth field is a quadword. It is unused but must be initialized to all zeros.
BSD Version 4.4 specifies a 16-byte IPv4 socket address structure. It contains five fields, as depicted in the following diagram:

The first field is a byte containing the size of this socket address structure (always a value of 16).
The second field is a byte identifying a socket address structure as belonging to the internet domain (always a value of 2).
The third field is a word containing a 16-bit port number (stored in network byte order) used to demultiplex transport-level messages.
The fourth field is a longword containing a 32-bit IPv4 internet address (stored in network byte order).
The fifth field is a quadword. It is unused but must be initialized to all zeros.
BSD Version 4.4 also specifies a 28-byte IPv6 socket address structure. It contains six fields, as depicted in the following diagram:

The first field is a byte containing the size of this socket address structure (always a value of 28).
The second field is a byte identifying a socket address structure as belonging to the IPv6 internet domain (always a value of 28).
The third field is a word containing the 16-bit port number (stored in network byte order) used to demultiplex transport-level messages.
The fourth field is a longword containing priority and flow label information (stored in network byte order).
The fifth field is an octaword (16 bytes) containing a 128-bit IPv6 Internet address (stored in network byte order).
The sixth field is a longword containing the scope id (stored in network byte order).

subfunction_code Longword structure specifying the exact operation an IO$_ACPCONTROL function is to perform. This structure has three fields, as depicted in the following diagram:

The first field is a byte specifying the network ACP operation.
The second field is a byte specifying the network ACP suboperation.
The third field is word that is unused but must be initialized to all zeros (MBZ).

socket_characteristics Longword structure specifying the address family, socket type, and protocol of a new socket. This structure has three fields, as depicted in the following diagram:

The first field is a word specifying the protocol to be used with the socket.
The second field is a byte specifying the socket type.
The third field is a byte specifying the address family.

**Table C-1 TCP/IP Services Usage Data Type Entries**
Data Type	Definition
`buffer_list`	Structure that consists of one or more descriptors defining the length and starting address of user buffers. On Alpha and I64 systems, each descriptor can be a 32- or 64-bit fixed-length descriptor. On VAX systems, each descriptor is a 32-bit fixed-length descriptor. For more information concerning descriptors, see the OpenVMS Calling Standard.
`input_parameter_list`	Structure that consists of one or more `item_list_2` or `ioctl_comm` structures. Each `item_list_2` structure describes an individual parameter that can be set by a service. Such parameters include socket or protocol options as identified by the item's type field. Each `ioctl_comm` structure describes an IOCTL command; its encoded request code and address of its associated argument.
`ioctl_comm`	Quadword structure that describes an IOCTL command's encoded request code and address of its associated argument. It contains two longword fields, as depicted in the following diagram: The first field is a longword containing the IOCTL encoded request code specifying the type of I/O control operation to be performed. The second field is a longword containing the address of a variable or a data structure targeted by this IOCTL command.
`item_list_2`	Quadword structure that describes the size, data type, and starting address of a user-supplied data item. It contains three fields, as depicted in the following diagram: The first field is a word containing the length (in bytes) of the user-supplied data item being described. The second field is a word containing a symbolic code specifying the data type of the user-supplied data item. The third field is a longword containing the starting address of the user-supplied data item.
`item_list_2 descriptor`	An `item_list_2` structure, used as an argument descriptor and containing structural information about the argument's type and the address of a data item. This data item is associated with the argument. The format of this descriptor is unique to TCP/IP Services and supplements argument descriptors defined in the OpenVMS Calling Standard.
`item_list_3`	A 12-byte structure that describes the size, data type, and address of a buffer in which a service writes information. It contains four fields, as depicted in the following diagram: The first field is a word containing the length (in bytes) of the buffer in which a service writes information. The length of the buffer needed depends on the data type specified in the type field. If the value of buffer length is too small, the service truncates the data. The second field is a word containing a symbolic code and specifies the type of information that a service is to return. The third field is a longword containing the address of the buffer in which a service writes the information. The fourth field is a longword containing the address of a longword in which a service writes the length in bytes of the information it actually returned.
`item_list_3 descriptor`	An `item_list_3` structure, used as an argument descriptor and containing structural information about the argument's type and the address of a buffer used to return service information. This buffer is associated with the argument. The format of this descriptor is unique to TCP/IP Services and supplements argument descriptors defined in the OpenVMS Calling Standard.
`output_parameter_list`	Structure that consists of one or more `item_list_3` or `ioctl_comm` structures. Each `item_list_3` structure describes an individual parameter that can be returned by a service. Such parameters include socket or protocol options as identified by the item's type field. Each `ioctl_comm` structure describes an IOCTL command, its encoded request code, and the address of its associated argument.
`socket_name`	Internet domain socket address structure that consists of an Internet address and a port number. The layouts of socket address structures of BSD Version 4.3 and BSD Version 4.4 are different. BSD Version 4.3 specifies a 16-byte IPv4 socket address structure. It contains four fields, as depicted in the following diagram: The first field is a word identifying a socket address structure as belonging to the internet domain (always a value of 2). The second field is a word containing a 16-bit port number (stored in network byte order) used to demultiplex transport-level messages. The third field is a longword containing a 32-bit IPv4 internet address (stored in network byte order). The fourth field is a quadword. It is unused but must be initialized to all zeros. BSD Version 4.4 specifies a 16-byte IPv4 socket address structure. It contains five fields, as depicted in the following diagram: The first field is a byte containing the size of this socket address structure (always a value of 16). The second field is a byte identifying a socket address structure as belonging to the internet domain (always a value of 2). The third field is a word containing a 16-bit port number (stored in network byte order) used to demultiplex transport-level messages. The fourth field is a longword containing a 32-bit IPv4 internet address (stored in network byte order). The fifth field is a quadword. It is unused but must be initialized to all zeros. BSD Version 4.4 also specifies a 28-byte IPv6 socket address structure. It contains six fields, as depicted in the following diagram: The first field is a byte containing the size of this socket address structure (always a value of 28). The second field is a byte identifying a socket address structure as belonging to the IPv6 internet domain (always a value of 28). The third field is a word containing the 16-bit port number (stored in network byte order) used to demultiplex transport-level messages. The fourth field is a longword containing priority and flow label information (stored in network byte order). The fifth field is an octaword (16 bytes) containing a 128-bit IPv6 Internet address (stored in network byte order). The sixth field is a longword containing the scope id (stored in network byte order).
`subfunction_code`	Longword structure specifying the exact operation an IO$_ACPCONTROL function is to perform. This structure has three fields, as depicted in the following diagram: The first field is a byte specifying the network ACP operation. The second field is a byte specifying the network ACP suboperation. The third field is word that is unused but must be initialized to all zeros (MBZ).
`socket_characteristics`	Longword structure specifying the address family, socket type, and protocol of a new socket. This structure has three fields, as depicted in the following diagram: The first field is a word specifying the protocol to be used with the socket. The second field is a byte specifying the socket type. The third field is a byte specifying the address family.

C.2 C and C++ Implementations

Table C-2 lists the OpenVMS data types and their corresponding C and C++ data type declarations.

Table C-2 C and C++ Implementations
OpenVMS Data Types C and C++ Implementations

buffer_list User defined ¹

input_parameter_list User defined ¹

ioctl_comm
struct ioctl_comm
{
int ioctl_req; /* ioctl request code */
void *ioctl_arg; /* ioctl argument */
}

item_list_2
struct item_list_2
{
unsigned short length; /* item length */
unsigned short type; /* item type */
void *address; /* item address */
}

item_list_2 descriptor
struct item_list_2
{
unsigned short length; /* argument length */
unsigned short type; /* argument type */
void *address; /* argument address */
}

item_list_3
struct item_list_3
{
unsigned short length; /* buffer length */
unsigned short type; /* buffer type */
void *address; /* buffer address */
unsigned int *retlen; /* buffer returned */
/* length address */
}

item_list_3 descriptor
struct item_list_3
{
unsigned short length; /* argument length */
unsigned short type; /* argument type */
void *address; /* argument address */
unsigned int *retlen; /* argument returned */
/* length address */
}

output_parameter_list User defined ¹

socket_name (IPv4)
include <in.h>
struct sockaddr_in

socket_name (IPv6)
include <in6.h>
struct sockaddr_in6

subfunction_code
struct acpfunc
{
unsigned char code; /* subfunction code */
unsigned char type; /* call code */
unsigned short reserved;/* reserved */
/* (must be zero) */
}

socket_characteristics
struct sockchar
{
unsigned short prot; /* protocol */
unsigned char type; /* type */
unsigned char af; /* address format */
}

**Table C-2 C and C++ Implementations**
OpenVMS Data Types	C and C++ Implementations
`buffer_list`	User defined ¹
`input_parameter_list`	User defined ¹
`ioctl_comm`	struct ioctl_comm { int ioctl_req; /* ioctl request code / void ioctl_arg; /* ioctl argument */ }
`item_list_2`	struct item_list_2 { unsigned short length; /* item length / unsigned short type; / item type / void address; /* item address */ }
`item_list_2 descriptor`	struct item_list_2 { unsigned short length; /* argument length / unsigned short type; / argument type / void address; /* argument address */ }
`item_list_3`	struct item_list_3 { unsigned short length; /* buffer length / unsigned short type; / buffer type / void address; /* buffer address / unsigned int retlen; /* buffer returned / / length address */ }
`item_list_3 descriptor`	struct item_list_3 { unsigned short length; /* argument length / unsigned short type; / argument type / void address; /* argument address / unsigned int retlen; /* argument returned / / length address */ }
`output_parameter_list`	User defined ¹
`socket_name` (IPv4)	include <in.h> struct sockaddr_in
`socket_name` (IPv6)	include <in6.h> struct sockaddr_in6
`subfunction_code`	struct acpfunc { unsigned char code; /* subfunction code / unsigned char type; / call code / unsigned short reserved;/ reserved / / (must be zero) */ }
`socket_characteristics`	struct sockchar { unsigned short prot; /* protocol / unsigned char type; / type / unsigned char af; / address format */ }

¹The declaration of a user-defined data structure depends on how the data will be used. Such data structures can be declared in a variety of ways, each of which is suitable only to specific applications.

Appendix D
Error Codes

This appendix contains a table of Sockets API error codes and their equivalent OpenVMS system service status codes (Table D-1).

Table D-1 Translation of Socket Error Codes to OpenVMS Status Codes
Sockets (C)
Error Code OpenVMS
System Service
Status Code Meaning

0 SS$_NORMAL Success

1 EPERM SS$_ABORT Not owner

2 ENOENT SS$_ABORT No such file or directory

3 ESRCH SS$_NOSUCHNODE No such process

4 EINTR SS$_ABORT Interrupted system call

5 EIO SS$_ABORT I/O error

6 ENXIO SS$_NOSUCHDEV No such device or address

7 E2BIG SS$_ABORT Argument list too long

8 ENOEXEC SS$_ABORT Execution format error

9 EBADF SS$_BADPARAM Bad file number

10 ECHILD SS$_ABORT No children

11 EAGAIN SS$_ABORT No more processes

12 ENOMEM SS$_INSFMEM Not enough core

13 EACCES SS$_ABORT Permission denied

14 EFAULT SS$_ACCVIO Bad address

15 ENOTBLK SS$_ABORT Block device required

16 EBUSY SS$_ABORT Mount device busy

17 EEXIST SS$_FILALRACC File exists

18 EXDEV SS$_ABORT Cross-device link

19 ENODEV SS$_ABORT No such device

20 ENOTDIR SS$_ABORT Not a directory

21 EISDIR SS$_ABORT Is a directory

22 EINVAL SS$_BADPARAM Invalid argument

23 ENFILE SS$_ABORT File table overflow

24 EMFILE SS$_ABORT Too many open files

25 ENOTTY SS$_ABORT Not a terminal

26 ETXTBSY SS$_ABORT Text file busy

27 EFBIG SS$_ABORT File too large

28 ENOSPC SS$_ABORT No space left on device

29 ESPIPE SS$_ABORT Illegal seek

30 EROFS SS$_ABORT Read-only file system

31 EMLINK SS$_ABORT Too many links

32 EPIPE SS$_LINKDISCON Broken pipe

33 EDOM SS$_BADPARAM Argument too large

34 ERANGE SS$_TOOMUCHDATA Result too large

35 EWOULDBLOCK SS$_SUSPENDED Operation would block

36 EINPROGRESS SS$_ABORT Operation now in progress

37 EALREADY SS$_ABORT Operation already in progress

38 ENOTSOCK SS$_NOTNETDEV Socket operation on nonsocket

39 EDESTADDRREQ SS$_NOSUCHNODE Destination address required

40 EMSGSIZE SS$_TOOMUCHDATA Message too long

41 EPROTOTYPE SS$_PROTOCOL Protocol wrong type for socket

42 ENOPROTOOPT SS$_PROTOCOL Protocol not available

43 EPROTONOSUPPORT SS$_PROTOCOL Protocol not supported

44 ESOCKTNOSUPPORT SS$_PROTOCOL Socket type not supported

45 EOPNOTSUPP SS$_ILLCNTRFUNC Operation not supported on socket

46 EPFNOSUPPORT SS$_PROTOCOL Protocol family not supported

47 EAFNOSUPPORT SS$_PROTOCOL Address family not supported

48 EADDRINUSE SS$_DUPLNAM Address already in use

49 EADDRNOTAVAIL SS$_IVADDR Requested address cannot be assigned

50 ENETDOWN SS$_UNREACHABLE Network is down

51 ENETUNREACH SS$_UNREACHABLE Network is unreachable

52 ENETRESET SS$_RESET Network dropped connection on reset

53 ECONNABORTED SS$_LINKABORT Software caused connection abort

54 ECONNRESET SS$_CONNECFAIL Connection reset by peer

55 ENOBUFS SS$_INSFMEM No buffer space available

56 EISCONN SS$_FILALRACC Socket is already connected

57 ENOTCONN SS$_NOLINKS Socket is not connected

58 ESHUTDOWN SS$_SHUT Cannot send after socket shutdown

59 ETOOMANYREFS SS$_ABORT Too many references, cannot splice

60 ETIMEDOUT SS$_TIMEOUT Connection timed out

61 ECONNREFUSED SS$_REJECT Connection refused

62 ELOOP SS$_ABORT Too many levels of symbolic links

63 ENAMETOOLONG SS$_ABORT File name too long

64 EHOSTDOWN SS$_SHUT Host is down

65 EHOSTUNREACH SS$_UNREACHABLE No route to host

**Table D-1 Translation of Socket Error Codes to OpenVMS Status Codes**
Sockets (C) Error Code	OpenVMS System Service Status Code	Meaning
0	SS$_NORMAL	Success
1 EPERM	SS$_ABORT	Not owner
2 ENOENT	SS$_ABORT	No such file or directory
3 ESRCH	SS$_NOSUCHNODE	No such process
4 EINTR	SS$_ABORT	Interrupted system call
5 EIO	SS$_ABORT	I/O error
6 ENXIO	SS$_NOSUCHDEV	No such device or address
7 E2BIG	SS$_ABORT	Argument list too long
8 ENOEXEC	SS$_ABORT	Execution format error
9 EBADF	SS$_BADPARAM	Bad file number
10 ECHILD	SS$_ABORT	No children
11 EAGAIN	SS$_ABORT	No more processes
12 ENOMEM	SS$_INSFMEM	Not enough core
13 EACCES	SS$_ABORT	Permission denied
14 EFAULT	SS$_ACCVIO	Bad address
15 ENOTBLK	SS$_ABORT	Block device required
16 EBUSY	SS$_ABORT	Mount device busy
17 EEXIST	SS$_FILALRACC	File exists
18 EXDEV	SS$_ABORT	Cross-device link
19 ENODEV	SS$_ABORT	No such device
20 ENOTDIR	SS$_ABORT	Not a directory
21 EISDIR	SS$_ABORT	Is a directory
22 EINVAL	SS$_BADPARAM	Invalid argument
23 ENFILE	SS$_ABORT	File table overflow
24 EMFILE	SS$_ABORT	Too many open files
25 ENOTTY	SS$_ABORT	Not a terminal
26 ETXTBSY	SS$_ABORT	Text file busy
27 EFBIG	SS$_ABORT	File too large
28 ENOSPC	SS$_ABORT	No space left on device
29 ESPIPE	SS$_ABORT	Illegal seek
30 EROFS	SS$_ABORT	Read-only file system
31 EMLINK	SS$_ABORT	Too many links
32 EPIPE	SS$_LINKDISCON	Broken pipe
33 EDOM	SS$_BADPARAM	Argument too large
34 ERANGE	SS$_TOOMUCHDATA	Result too large
35 EWOULDBLOCK	SS$_SUSPENDED	Operation would block
36 EINPROGRESS	SS$_ABORT	Operation now in progress
37 EALREADY	SS$_ABORT	Operation already in progress
38 ENOTSOCK	SS$_NOTNETDEV	Socket operation on nonsocket
39 EDESTADDRREQ	SS$_NOSUCHNODE	Destination address required
40 EMSGSIZE	SS$_TOOMUCHDATA	Message too long
41 EPROTOTYPE	SS$_PROTOCOL	Protocol wrong type for socket
42 ENOPROTOOPT	SS$_PROTOCOL	Protocol not available
43 EPROTONOSUPPORT	SS$_PROTOCOL	Protocol not supported
44 ESOCKTNOSUPPORT	SS$_PROTOCOL	Socket type not supported
45 EOPNOTSUPP	SS$_ILLCNTRFUNC	Operation not supported on socket
46 EPFNOSUPPORT	SS$_PROTOCOL	Protocol family not supported
47 EAFNOSUPPORT	SS$_PROTOCOL	Address family not supported
48 EADDRINUSE	SS$_DUPLNAM	Address already in use
49 EADDRNOTAVAIL	SS$_IVADDR	Requested address cannot be assigned
50 ENETDOWN	SS$_UNREACHABLE	Network is down
51 ENETUNREACH	SS$_UNREACHABLE	Network is unreachable
52 ENETRESET	SS$_RESET	Network dropped connection on reset
53 ECONNABORTED	SS$_LINKABORT	Software caused connection abort
54 ECONNRESET	SS$_CONNECFAIL	Connection reset by peer
55 ENOBUFS	SS$_INSFMEM	No buffer space available
56 EISCONN	SS$_FILALRACC	Socket is already connected
57 ENOTCONN	SS$_NOLINKS	Socket is not connected
58 ESHUTDOWN	SS$_SHUT	Cannot send after socket shutdown
59 ETOOMANYREFS	SS$_ABORT	Too many references, cannot splice
60 ETIMEDOUT	SS$_TIMEOUT	Connection timed out
61 ECONNREFUSED	SS$_REJECT	Connection refused
62 ELOOP	SS$_ABORT	Too many levels of symbolic links
63 ENAMETOOLONG	SS$_ABORT	File name too long
64 EHOSTDOWN	SS$_SHUT	Host is down
65 EHOSTUNREACH	SS$_UNREACHABLE	No route to host