# Compaq TCP/IP Services for OpenVMS
Sockets API and System Services Programming

Previous | Contents | Index

## 3.2.1 hostent Structure

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` .

## 3.2.2 in_addr Structure

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.

## 3.2.4 linger Structure

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.)

## 3.2.5 msghdr Structure

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)

### 3.2.5.1 BSD Version 4.4

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.

### 3.2.5.2 BSD Version 4.3

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.

## 3.2.6 netent Structure

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.

## 3.2.7 sockaddr Structure

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)

### 3.2.7.1 BSD Version 4.4

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.

### 3.2.7.2 BSD Version 4.3

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.

## 3.2.8 sockaddr_in Structure

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.

## 3.2.9 timeval Structure

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.

# 3.3 Header Files

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()`

Caution Because these Sockets API functions access files to retrieve information, you should not call these functions from either the KERNEL or the EXEC mode when the ASTs are disabled.

# 3.5 Standard I/O Functions

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.

Previous | Next | Contents | Index