The hostent structure, defined in the NETDB.H header file, holds a host name, a list of aliases associated with the network, and the network's number as specified in an internet address from the hosts database.

The hostent structure definition is as follows:

struct hostent { char *h_name; /* official name of host */ char **h_aliases; /* alias list */ int h_addrtype; /* host address type */ int h_length; /* length of address */ char **h_addr_list; /* list of addresses from name server */ }; #define h_addr h_addr_list[0] /* address, for backward compatibility */

The hostent structure members are as follows:

• h_name is a pointer to a null-terminated character string that is the official (canonical) name of the host.
• h_aliases is a pointer to an array of pointers to alias names for the host.
• h_addrtype is the type of host address being returned (AF_INET).
• h_length is the length, in bytes, of the address. (For IPv4, this value is 4 bytes.)
• h_addr_list is a pointer to an array of pointers to the network addresses for the host. Each host address is represented by a series of bytes in network order. The list is terminated with a null pointer value.
• h_addr is the first address in the h_addr_list .

The in_addr structure, defined in the IN.H header file, holds an internet address. The address format can be any of the supported internet address notation formats.

The in_addr structure definition is as follows:

struct in_addr { union { struct { u_char s_b1,s_b2,s_b3,s_b4; } S_un_b; struct { u_short s_w1,s_w2; } S_un_w; u_long S_addr; } S_un; #define s_addr S_un.S_addr /* can be used for most tcp & ip code */ #define s_host S_un.S_un_b.s_b2 /* host on imp */ #define s_net S_un.S_un_b.s_b1 /* network */ #define s_imp S_un.S_un_w.s_w2 /* imp */ #define s_impno S_un.S_un_b.s_b4 /* imp # */ #define s_lh S_un.S_un_b.s_b3 /* logical host */ };

3.2.3 iovec Structure

The iovec structure holds one scatter-and-gather buffer. Multiple scatter-and-gather buffer descriptors are stored as an array of iovec elements.

The iovec structure definition is defined in the SOCKET.H header file.

The iovec structure definition is as follows:

struct iovec { char *iov_base; int iov_len; }

The iovec structure members are as follows:

• iov_base is a pointer to a buffer.
• iov_len contains the size of the buffer to which iov_base points.

The linger structure, defined in the SOCKET.H header file, specifies the setting or resetting of the socket option for the time interval that the socket lingers for data. The linger structure is supported only by STREAM-type sockets.

The linger structure definition is as follows:

struct linger { int l_onoff; /* option on/off */ int l_linger; /* linger time */ };

The linger structure members are as follows:

• l_onoff =1 sets linger ; l_onoff =0 resets linger .
• l_linger is the number of seconds to linger. (The default is 120 seconds, or 2 minutes.)

The msghdr structure specifies the buffer parameter for the recvmsg and sendmsg I/O functions. The structure allows you to specify an array of scatter and gather buffers. The recvmsg function scatters the data to several user receive buffers, and the sendmsg function gathers data from several user transmit buffers before being transmitted.

The SOCKET.H header file defines the following structures for BSD Versions 4.3 and 4.4:

• msghdr structure (BSD Version 4.4)
• omsghdr structure (BSD Version 4.3)

The msghdr structure definition for use with BSD Version 4.4 is as follows:

struct msghdr { void *msg_name; /* protocol address */ int msg_namelen; /* size of address */ struct iovec *msg_iov; /* scatter/gather array */ int msg_iovlen; /* number of elements in msg_iov */ void *msg_control; /* ancillary data; must be aligned for a cmsghdr structure */ int msg_controllen; /* length of ancillary data buffer */ int msg_flags; /* flags on received message */ };

The msghdr structure members are as follows:

• msg_name is the address of the destination socket if the socket is not connected. If no address is required, you can set this field to null.
• msg_namelen is the length of the msg_name field.
• msg_iov is an array of I/O buffer pointers of the iovec structure form. See Section 3.2.3 for a description of the iovec structure.
• msg_iovlen is the number of buffers in the msg_iov array.
• msg_control specifies the location of the optional ancillary data or control information.
• msg_controllen is the size of the ancillary data in the msg_control buffer.
• mgs_flags , used only with the recvmsg function, is the value used by the kernel to drive its receive processing.

The omsghdr structure definition for use with BSD Version 4.3 is as follows:

struct omsghdr { char *msg_name; /* protocol address */ int msg_namelen; /* size of address */ struct iovec *msg_iov; /* scatter/gather array */ int msg_iovlen; /* number of elements in msg_iov */ char *msg_accrights; /* access rights sent/received */ int msg_accrightslen; /* length of access rights buffer */ };

The omsghdr structure members are as follows:

• msg_name is the address of the destination socket if the socket is not connected. If no address is required, you can set this field to null.
• msg_namelen is the length of the msg_name field.
• msg_iov is an array of I/O buffer pointers of the iovec structure form. See Section 3.2.3 for a description of the iovec structure.
• msg_iovlen is the number of buffers in the msg_iov array.
• msg_accrights points to a buffer containing access rights sent with the message.
• msg_accrightslen is the length of the msg_accrights buffer.

The netent structure, defined in the NETDB.H header file, holds a network name, a list of aliases associated with the network, and the network's number specified as an internet address from the network database.

The netent structure definition is as follows:

struct netent { char *n_name; /* official name of net */ char **n_aliases; /* alias list */ int n_addrtype; /* net address type */ long n_net; /* net number */ };

The netent structure members are as follows:

• n_name is the official network name.
• n_aliases is a null-terminated list of pointers to alternate names for the network.
• n_addrtype is the type of the network number returned (AF_INET).
• n_net is the network number returned in host byte order.

The sockaddr structure, defined in the SOCKET.H header file, holds a general address family.

The SOCKET.H header file defines the following structures for BSD Versions 4.3 and 4.4:

• sockaddr structure (BSD Version 4.4)
• osockaddr structure (BSD Version 4.3)

The sockaddr structure definition for use with BSD Version 4.4 is as follows:

struct sockaddr { u_char sa_len; /* total length */ u_char sa_family; /* address family */ char sa_data[14]; /* up to 14 bytes of direct address */ };

The sockaddr structure members are as follows:

• sa_len is the length of the structure.
• sa_family is the address family or domain in which the socket was created.
• sa_data is the data string of up to 14 bytes of direct address.

The osockaddr structure definition for use with BSD Version 4.3 is as follows:

struct osockaddr { u_short sa_family; /* address family */ char sa_data[14]; /* up to 14 bytes of direct address */ };

The osockaddr structure members are as follows:

• sa_family is the address family or domain in which the socket was created.
• sa_data is the data string of up to 14 bytes of direct address.

The sockaddr_in structure, defined in the IN.H header file, specifies an internet address family.

The sockaddr_in structure definition is as follows:

struct sockaddr_in { short sin_family; /* address family */ u_short sin_port; /* port number */ struct in_addr sin_addr; /* internet address */ char sin_zero[8]; /* 8-byte field of all zeroes */ };

The sockaddr_in structure members are as follows:

• sin_family is the address family (AF_INET).
• sin_port is the port number in network order.
• sin_addr is the internet address in network order.
• sin_zero is an 8-byte field containing all zeros.

The timeval structure, defined in the SOCKET.H header file, specifies time intervals. The timeval structure definition is as follows:

struct timeval { long tv_sec; long tv_usec; };

The timeval structure members are as follows:

• tv_sec specifies the number of seconds to wait.
• tv_usec specifies the number of microseconds to wait.

You can include header files on a OpenVMS system using any one of the following preprocessor directive statements:

#include types #include <types.h> #include <sys/types.h>

The #include types form of the #include preprocessor directive is possible on OpenVMS systems because all header files are located in a text library in the SYS$LIBRARY directory. On Compaq Tru64 UNIX systems, you must specify header files (and subdirectories that locate a header file) within angle brackets (< >) or double quotes (" ") .

For example, to include the header file TYPES.H, use the following form of the #include directive:

#include <sys/types.h>

3.4 Calling a Socket Function from an AST State

Calls to various Sockets API functions return information within a static area. The OpenVMS environment allows an asynchronous system trap (AST) routine 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()

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

3.6 Event Flags

Socket functions can use event flags during their operation. To assign event flags, use the library function LIB$GET_EF. Event flags are released when the function no longer needs them.

3.7 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 function 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.

Table 3-3 lists the possible errno values.

Table 3-3 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 foreign 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.
	A bad 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.