6. INETDRIVER Services

Introduction

This chapter describes the internet device driver (INETDRIVER) services.

The INETDRIVER services provide an asynchronous I/O implementation of the UNIX socket calls within the OpenVMS Queue I/O Request (SYS$QIO and SYS$QIOW) system services. These system services allow for efficient socket operations in that Asynchronous System Trap (AST) routines can be associated with I/O requests.

The INETDRIVER services provide the Stanford Research Institute (SRI) QIO interface. The interface is an international de facto standard that provides a one-to-one mapping between the UNIX socket functions and the OpenVMS SYS$QIO system services.

INETDRIVER interfaces directly with the TCP, UDP, and IP (for raw functions) protocols in the transport layers. It does not replace the TCPDRIVER or UDPDRIVER services but provides another way to communicate with them.

For details, see the TCPDRIVER Services and UDPDRIVER Services chapters.

INETDRIVER supports QIOs to:

· Create a stream, datagram, or raw socket

· Bind a socket to a local port or address

· Set a socket to listen mode

· Accept a connection

· Create a connection

· Send and receive data

· Perform other socket and control functions

Note: The TCPware INETDRIVER supports stream, datagram, and raw sockets, but only for the AF_INET address family.

Sequence of Operations

The INETDRIVER sequences of operations are divided into client operations and server operations. Each have distinct steps, as outlined in the following sections.

Client Operations

The INETDRIVER client operations for a stream socket connection are as follows:

1. Assign an INET channel to the INET0: device using the SYS$ASSIGN system service. This creates a new INET device unit and assigns a channel to it.

2. Create a stream socket using the SYS$QIO[W] system service with the IO$_SOCKET function.

3. If you want to assign a particular address to an unnamed socket, use the SYS$QIO[W] IO$_BIND function. This is optional and not necessary under most circumstances.

4. Connect to a peer on the server using the SYS$QIO[W] IO$_CONNECT function. Specify the server's internet address as a "well-known" port number.

5. Exchange data with the peer using the SYS$QIO[W] IO$_SEND and SYS$QIO[W] IO$_RECEIVE functions.

6. After the data exchange is complete, deassign the channel using the SYS$DASSGN system service.

The below figure shows the client operation steps.

Server Operations

The INETDRIVER server operations for a simple, single-thread stream socket connection are as follows:

1. Assign an INET listen channel to the INET0: device using the SYS$ASSIGN system service. This creates a new INET device unit and assigns a channel to it.

2. Create a stream socket using the SYS$QIO[W] IO$_SOCKET function.

3. Bind the socket to the server's "well-known" port number using the SYS$QIO[W] IO$_BIND function.

4. Enable listens and set up the listen queue length using the SYS$QIO[W] IO$_LISTEN function.

5. Assign an INET accept channel to the INET0: device using the SYS$ASSIGN system service again.

6. Accept incoming connect requests using the SYS$QIO[W] IO$_ACCEPT function on the accept channel, specifying the listen channel as a parameter. Then wait for the client to connect.

7. Exchange data with the client on the accept channel using the SYS$QIO[W] IO$_SEND and SYS$QIO[W] IO$_RECEIVE functions.

8. After the data exchange is complete, deassign the accept channel using the SYS$DASSGN system service. This closes the connection.

Repeat steps 5 through 8 to process additional server connections. The below figure shows the server operations steps.

Multicasting

INETDRIVER Services includes the following setsockopt() and getsockopt() definitions at the IPPROTO_IP level for multicasting support:

#define   IP_MULTICAST_IF     2
#define   IP_MULTICAST_TTL    3
#define   IP_MULTICAST_LOOP   4
#define   IP_ADD_MEMBERSHIP   5
#define   IP_DROP_MEMBERSHIP 6

The IP_ADD_MEMBERSHIP and IP_DROP_MEMBERSHIP requests use the following structure:

struct ip_mreq {
struct in_addr imr_multiaddr; /* Multicast address of group */
struct in_addr imr_intrface; /* local IP address of interface */
};

Other Operations

In addition to the routines associated with the sequence of operations above, INETDRIVER also includes other operations that:

· Set socket options (IO$_SETSOCKOPT)

· Get socket options (IO$_GETSOCKOPT)

· Shut down sockets (IO$_SHUTDOWN)

· Get socket names (IO$_GETSOCKNAME)

· Change the INET device characteristics (IO$_SETCHAR)

· Get the address of the remote end for a socket (IO$_GETPEERNAME)

· Change socket characteristics (IO$_IOCTL)

· Deliver an AST to the process if out-of-band data arrives (IO$_SETMODE | IO$_ATTNAST)

INETDRIVER Socket Library

The Socket Library routines described in the Socket Library chapter make use of the TCPDRIVER and UDPDRIVER programming interface. An alternate set of socket routines is available that makes use of the INETDRIVER programming interface and allows a mix of socket routines and INETDRIVER QIO calls. This alternate set of socket routines is presently only available in the TCPWARE:SOCKLIB.OLB socket library (the routines are not part of the TCPWARE_SOCKLIB_SHR.EXE shareable run-time library). The following routines are available:

inet_socket	inet_socket_recv	inet_sendto	inet_socket_ioctl
inet_bind	inet_recv	inet_shutdown	inet_getsockname
inet_connect	inet_recvfrom	inet_socket_close	inet_getpeername
inet_listen	inet_socket_write	inet_setsockopt	inet_socket_perror
inet_accept	inet_socket_send	inet_getsockopt	inet_tcpware_server
inet_socket_read	inet_send

The socket number (descriptor) used by these routines is the VMS I/O channel of the INETDRIVER device being used. This allows for the mixing of these routines and direct QIOs to the driver.

INETDRIVER System Service Call Format

The format for the INETDRIVER SYS$QIO system service call is as follows:

status = SYS$QIO[W](u_long efn, u_int chan, u_long func, unsigned quadword *iosb, void *astadr, u_long astprm, p1, p2, p3, p4, p5, p6)

The TCPWARE_INCLUDE:INETIODEF.H file provides definitions for the QIO function codes.

Note: The E-prefix status codes (such as ECONNRESET) listed under the STATUS headings are returned in the I/O status block (iosb) and are not the UNIX errno values. As described in the I/O Status Block Fields section under the iosb argument, the values returned for these codes are the UNIX errno values multiplied by 8 and logically ORed with 0x8000.

Note: The vertical bar ( | ) used in some of the functions described in this chapter is the C bitwise inclusive OR operator.

INETDRIVER System Service Call Arguments

You invoke UDPDRIVER system service calls with the standard OpenVMS QIO mechanism.

See the appropriate OpenVMS documentation (for example, the Introduction to VMS System Services volume) for details on the QIO mechanism.

The following sections describe each system call argument.

efn

(Optional) Number of the event flag to be set when the I/O operation completes.

chan

I/O channel assigned to the INET device to which the request is directed.

func

Device-specific function codes and modifiers for each operation.

iosb

I/O status block that receives the final completion status of the I/O operation, structured as in the below figure.

The below table describes the status block fields in more detail.

Field Name	Description
Transfer Byte Count	Number of bytes of data transferred in the I/O operation.
Status Code	SS$ status code or special error status code. If the low bit (0) of the OpenVMS error code is clear, the network has returned an error. If the most significant bit of this word is set (mask of 0x8000), the status code is the UNIX errno code multiplied by 8 and logically ORed with 0x8000.
Function-Specific	Varies for each device and function code.

astadr

Asynchronous system trap (AST) routine to be executed when the I/O is completed.

astprm

AST parameter to be passed to the AST routine.

p1…p6

Function-specific parameters, as described for each function.

INETDRIVER System Service Call Function Codes

System service call function codes specify what action the QIO performs.

IO$_ACCEPT

Waits for a connection to a listening socket and associates a OpenVMS channel to the socket for that new connection. The connection's socket has the same properties as the listening socket.

If no pending connections exist on the queue and the socket is not marked as nonblocking, IO$_ACCEPT blocks the caller until a connection is made to the listening socket. If the socket is marked as nonblocking and no pending connections exist on the queue, IO$_ACCEPT returns an EWOULDBLOCK error.

Multiple IO$_ACCEPT requests are supported on a single channel.

See IO$_ACCEPT_WAIT for an alternative to IO$_ACCEPT.

Format

status = SYS$QIO(efn, new-inet-chan, IO$_ACCEPT, iosb, astadr, astprm, address, addrlen, inet-chan, 0, 0, 0);

Arguments

chan = u_int new-inet-chan

OpenVMS channel to a newly created INET: device. This channel should be created by using SYS$ASSIGN to assign a new channel to INET0: prior to issuing the IO$_ACCEPT function. The accepted connection uses this channel.

p1 = struct *address

Optional pointer to a structure that receives the peer's address for the connection following completion of the IO$_ACCEPT function. The structure is defined as follows:

Struct

{
unsigned long Length;
struct sockaddr_in Address;
}

p2 = u_int addrlen

Length (in bytes) of the buffer to which the address argument points. The value must be at least 20 bytes.

p3 = u_int inet-chan

OpenVMS channel for the INET: device on which the IO$_LISTEN was performed. After accepting the connection, this device remains available to accept additional connections.

Status

EALREADY	Operation is already in progress or the socket is in use (e.g. an IO$_ACCEPT is active on the channel).
ECONNABORTED	Listening channel was shut down or aborted.
EINVAL	Operation is not valid (for a nonstream socket), or an invalid inet-chan or addrlen argument was specified.
ENETDOWN	Network was shut down.
ENOTSOCK	No socket exists on the listening channel.
EOPNOTSUPP	Socket is not of type SOCK_STREAM.
EWOULDBLOCK	Connection is marked as nonblocking and no connection is waiting to be accepted.
SS$_IVCHAN	Invalid listening channel number was specified.
SS$_THIRDPARTY	Network is being shut down.

IO$_ACCEPT_WAIT

Waits for an incoming connection on a listening socket without accepting the connection. When the IO$_ACCEPT_WAIT is complete, a connection is available for accepting; IO$_ACCEPT is then used to accept it.

Multiple IO$_ACCEPT_WAIT requests are supported on a single channel.

IO$_ACCEPT_WAIT is useful to avoid holding an additional INET channel while waiting to service a connection.

Format

status = SYS$QIO(efn,inet-chan, IO$_ACCEPT_WAIT, iosb, astadr, astprm, 0, 0, 0, 0, 0, 0);

Argument

chan = u_int inet-chan

OpenVMS channel to the INET: device on which the IO$_LISTEN was performed.

Status

ECONNABORTED	Listening channel was shut down or aborted.
EINVAL	Operation is not valid (for a nonstream socket), or an invalid inet-chan or addrlen argument was specified.
ENETDOWN	Network was shut down.
ENOTSOCK	No socket exists on the listening channel.
EOPNOTSUPP	Socket is not of type SOCK_STREAM.
EWOULDBLOCK	Connection is marked as nonblocking and no connection can be accepted.
SS$_THIRDPARTY	Network is being shut down.

IO$_BIND

Assigns an address to an unbound socket. When a socket is created with IO$_SOCKET, it has no assigned address. IO$_BIND requests that the address be assigned to the socket.

Normally used by servers to bind to their "well-known" port number before issuing the IO$_LISTEN function. Clients typically do not use this function, since IO$_CONNECT normally will assign an unused port number.

Note: To bind to port numbers 1 through 1023, a process must be running under a privileged UIC, or with the SYSPRV or BYPASS privilege.

Format

status = SYS$QIO(efn, inet-chan, IO$_BIND, iosb, astadr, astprm, name, namelen,0, 0, 0, 0);

Arguments

chan = u_int inet-chan

OpenVMS channel to the INET: device on which the IO$_SOCKET was performed.

p1 = struct sockaddr_in *name

Address to which the socket should be bound.

p2 = u_long namelen

Length of the name argument (in bytes).

Status

EACCES	Specified address is not available from the local machine.
EADDRNOTAVAIL	Requested address is protected; the user has no permission to have access to it.
EADDRINUSE	Specified address is already in use.
EINVAL	Operation is not valid (for a nonstream socket).
ENETDOWN	Network was shut down.
SS$_THIRDPARTY	Network is being shut down.

IO$_CONNECT

For stream sockets, attempts a connection to a peer socket. For datagram sockets, permanently specifies the peer to which the datagrams are to be sent or from which they are to be received.

Format

status = SYS$QIO(efn, inet-chan, IO$_CONNECT,iosb, astadr, astprm,name, namelen,0, 0, 0, 0);

Arguments

chan = u_int inet-chan

Channel to the socket.

p1 = struct sockaddr_in *name

Address of the peer to which the socket should be bound.

p2 = u_long namelen

Length of the name argument (in bytes).

Status

EADDRNOTAVAIL	Requested address is protected; the user has no permission to have access to it.
EADDRINUSE	Specified address is already in use.
EALREADY	Operation is already in progress.
ECONNABORTED	Operation was aborted.
ECONNREFUSED	Connection was refused by the peer.
EHOSTUNREACH	Host was unreachable.
EINVAL	Socket has already been used for a connection, or the namelen argument is invalid.
EISCONN	Socket is already connected.
ENETDOWN	Network has been shut down.
ENETUNREACH	Destination network is unreachable.
EOPNOTSUPP	Operation is not supported (e.g., a connect on a listening socket).
ETIMEDOUT	Connection timed out.
EWOULDBLOCK	Socket is marked as nonblocking; connection attempt is in progress.
SS$_THIRDPARTY	Network is being shut down.

IO$_GETPEERNAME

Returns the address of the peer connected to the specified socket.

Format

status = SYS$QIO(efn,inet-chan, IO$_GETPEERNAME, iosb, astadr, astprm, address, addrlen,0, 0, 0, 0);

Arguments

chan = u_int inet-chan

Channel to the socket.

p1 = struct sockaddr_in *address

Receives the peer's address.

p2 = u_long *addrlen

On entry, contains the byte length of the space pointed to by address. On return, it contains the byte length of the data returned.

Status

EINVAL	Invalid addrlen was specified.
ENETDOWN	Network has been shut down.
ENOTCONN	Socket is not connected.
SS$_THIRDPARTY	Network is being shut down.

IO$_GETSOCKNAME

Returns the local address of a socket.

Format

status = SYS$QIO(efn,inet-chan, IO$_GETSOCKNAME,iosb, astadr, astprm, address, addrlen,0, 0, 0, 0);

Arguments

chan = u_int inet-chan

Channel to the socket.

p1 = struct sockaddr_in *address

Receives the local or multicast address.

p2 = u_long *addrlen

On entry, contains the byte length of the space pointed to by address. On return, it contains the byte length of the data returned.

Status

EINVAL	addrlen argument is invalid.
ENETDOWN	Network was shut down.
SS$_THIRDPARTY	Network is being shut down.

IO$_GETSOCKOPT

Retrieves the value of options associated with a socket.

The TCPWARE_INCLUDE:SOCKET.H file contains definitions for the socket-level options. The IPPROTO_IP level options defined in the TCPWARE_INCLUDE:IN.H file are not compatible with INETDRIVER.

Format

status = SYS$QIO(efn,inet-chan, IO$_GETSOCKOPT,iosb, astadr, astprm, level, optname, optval, optlen, 0, 0);

Arguments

chan = u_int inet-chan

Channel to the socket.

p1 = u_long level

SOL_SOCKET to change socket options, or IPPROTO_IP to change IP options (which requires system UIC, SYSPRV, or BYPASS privilege).

p2 = u_long optname

TCPware ignores this option where indicated. However, you should include it if you created other routines that set this option to that you do not get an error message.

p3 = byte *optval

Pointer to a buffer that is to receive the current value of the option. The format of this buffer is dependent on the option requested. Options other than SO_LINGER return a longword value. For those options that are enabled or disabled, 0 is returned if disabled, 1 is returned if enabled.

SO_LINGER uses the following structure for the linger value:

structlinger

{
intl_onoff ;/* option on/off */
intl_linger ;/* linger time */
};

p4 = u_long *optlen

On entry, contains the byte length of the space pointed to by optval. On return, contains the byte length of the option returned.

Status

EINVAL	level specified is invalid.
ENOPROTOOPT	Option is unknown.
ENETDOWN	Network was shut down.
SS$_THIRDPARTY	Network is being shut down.

IO$_IOCTL

Manipulates socket characteristics. The TCPWARE_INCLUDE:IOCTL.H file contains definitions for the IO$_IOCTL request codes.

Note: This function does not support operations to set network interface information.

Format

status = SYS$QIO(efn,inet-chan, IO$_IOCTL, iosb, astadr, astprm, request, argp, 0, 0, 0, 0);

Arguments

chan = u_int inet-chan

Channel to the socket.

p1 = u_long request

IO$_IOCTL function to perform. The IO$_IOCTL functions are listed in the below table:

Value	Description
FIONBIO	Sets/clears nonblocking mode
FIONREAD	Returns bytes available for reading
SIOCADDRT	Adds a routing entry
SIOCATMARK	Returns whether the read point is at the out-of-band (TCP urgent) mark
SIOCDARP	Deletes an address resolution (ARP) entry
SIOCDELRT	Deletes a routing entry
SIOCGARP	Gets an address resolution (ARP) entry
SIOCGIFCONF	Returns list of network interfaces
SIOCGIFADDR	Returns the internet address for an interface
SIOCGIFBRDADDR	Returns the broadcast address for an interface
SIOCGIFDSTADDR	Returns the destination address for a point-to-point interface
SIOCGIFFLAGS	Returns the flags for an interface
SIOCGIFMETRIC	Returns the metric for an interface
SIOCGIFMTU	Returns the minimum transmission unit for an interface
SIOCGIFNETMASK	Returns the network mask for an interface
SIOCSARP	Adds an address resolution (ARP) entry

p2 = byte *argp

Pointer to a buffer whose format and function depends on the request specified.

Status

ENOPROTOOPT	request specified is invalid.
ENETDOWN	Network was shut down.
SS$_THIRDPARTY	Network is being shut down.

IO$_LISTEN

Places the stream in a listen state and specifies the maximum number of incoming connections that can be queued waiting to be accepted. This backlog must be specified before accepting a connection on a socket.

Applies to sockets of type SOCK_STREAM only.

Format

status = SYS$QIO(efn,inet-chan, IO$_LISTEN, iosb, astadr, astprm,backlog, 0, 0, 0, 0, 0);

Arguments

chan = u_int inet-chan

Channel to the socket.

p1 = u_long backlog

Maximum length of the queue of pending connections. If a connection request arrives when the queue is full, the request is ignored. The backlog queue is limited by the TCPware BACKLOG_LIMIT parameter. If the specified value is greater than BACKLOG_LIMIT, BACKLOG_LIMIT is used.

See the ADD SERVICE command description in Chapter 2, NETCU Commands, in the NETCU Command Reference for details on setting the BACKLOG_LIMIT parameter.

Status

EISCONN	Socket is already connected.
EOPNOTSUPP	Operation is not supported (such as when the connection on a listening socket).
ENETDOWN	Network was shut down.
SS$_THIRDPARTY	Network is being shut down.

IO$_RECEIVE

Receives data from a socket.

The length of the data received is returned in the second word of the I/O Status Block (iosb). A count of 0 indicates an end-of-file condition, or the connection was closed.

For SOCK_DGRAM and SOCK_RAW messages, if the message is too long to fit in the supplied buffer, excess bytes are discarded. For SOCK_STREAM data, no bytes are discarded, even though the amount of data processed on a request may be different than the amount sent.

If no data is available for the socket, the IO$_RECEIVE function waits for data to arrive, unless the socket is in nonblocking mode.

Format

status = SYS$QIO(efn,inet-chan, IO$_RECEIVE,iosb, astadr, astprm, buffer, size, flags, from, fromlen, 0);

Arguments

chan = u_int inet-chan

Channel to the socket.

p1 = byte *buffer

Address of the user's buffer.

p2 = u_long *size

Byte size of the user's buffer. The value should not be greater than 64000 bytes. The actual number of bytes read is returned in the iosb.

p3 = u_long flags

Control information that affects the IO$_RECEIVE function and is formed by logically OR-ing one or more of the following values:

#define MSG_OOB           0x1/*send out-of-band data*/
#define MSG_PEEK          0x2*peek at incoming message*/
#define MSG_NONBLOCKING   0x10/*override blocking state*/
#define MSG_TIME          0x100/*limit receive wait time*/

The MSG_OOB flag causes IO$_RECEIVE to read any out-of-band data arriving on the socket.

The MSG_PEEK flag causes IO$_RECEIVE to read the data present in the socket without removing the data. This allows the caller to view the data, but leave it in the socket for future IO$_RECEIVE functions.

The MSG_NONBLOCKING flag causes IO$_RECEIVE to be a nonblocking request. An EWOULDBLOCK status would be returned if the request cannot be completed immediately.

The MSG_TIME flag (for datagram sockets only) causes IO$_RECEIVE to complete within SO_RCVTIMEO seconds with the ETIMEDOUT status (if no message is received). Use the IO$_SETSOCKET function to set SO_RCVTIMEO.

p4 = struct *from

For SOCK_DGRAM and SOCK_RAW sockets, the optional from argument is a pointer to a structure that contains the address of the socket that sent the packet following completion of the IO$_RECEIVE function. The structure is defined as follows:

struct

{
unsigned short Length;
struct sockaddr_inAddress;
} ;

The from argument is ignored for SOCK_STREAM sockets.

p5 = u_int fromlen

For SOCK_DGRAM sockets, byte length (at least 18 bytes) of the buffer pointed to by the from argument. The fromlen argument is ignored for SOCK_STREAM sockets.

Status

ECONNRESET	Connection was reset by the peer.
EHOSTUNREACH	Host was unreachable.
EINVAL	from argument is invalid, or no out-of-band data was available.
ENETDOWN	Network was shut down.
ENOTCONN	Socket is not connected.
EOPNOTSUPP	Out-of-band request exists on a non-stream socket.
ETIMEDOUT	Connection timed out.
EWOULDBLOCK	Request would block.
SS$_CANCEL	Request was cancelled.
SS$_THIRDPARTY	Network is being shut down.

IO$_SEND

Sends stream data (for stream sockets), messages (for datagram sockets), or raw data to a socket.

IO$_SEND blocks if no buffer space is available at the socket to hold the data to be transmitted unless the socket was placed in nonblocking mode. For datagram sockets, if the message is too long to pass through the underlying protocol in a single unit, an EMSGSIZE status is returned, and the message is not transmitted.

Format

status = SYS$QIO(efn,inet-chan, IO$_SEND, iosb, astadr, astprm, buffer, size, flags, to, tolen, 0);

Arguments

chan = u_int inet-chan

Channel to the socket.

p1 = byte *buffer

Address of the user's buffer.

p2 = u_long size

Byte size of the user's buffer. The actual number of bytes sent is returned in the iosb. The value should not be greater than 64000 bytes.

p3 = u_long flags

Control information that affects the IO$_SEND function and is formed by logically ORing one or more of the following values:

#define MSG_OOB 0x1/*send out-of-band data*/
#define MSG_NONBLOCKING 0x10/*override blocking state*/

The MSG_OOB flag causes IO$_SEND to send out-of-band data on sockets that support this operation (e.g., SOCK_STREAM sockets).

The MSG_NONBLOCKING flag causes IO$_SEND to be a nonblocking request. An EWOULDBLOCK status would be returned if the request cannot be completed immediately. For stream sockets, some of the data may have been sent: the amount is returned in the second word of the iosb.

p4 = struct sockaddr_in *to

For datagram sockets, the optional to argument is a pointer to the address to which the packet should be transmitted. This argument is ignored for SOCK_STREAM sockets.

p5 = u_long tolen

For datagram sockets, the optional tolen argument contains the byte length of the address pointed to by the to argument. This argument is ignored for SOCK_STREAM sockets.

Status

ECONNRESET	Connection was reset by the peer.
EDESTADDRREQ	Destination address was not specified.
EHOSTUNREACH	Host was unreachable.
EINVAL	to argument is invalid, or no out-of-band data was available.
EISCONN	Socket is already connected.
EMSGSIZE	Datagram was too large.
ENETDOWN	Network was shut down.
ENETUNREACH	Destination network is unreachable.
ENOTCONN	Socket is not connected.
EOPNOTSUPP	Out-of-band request exists on a non-stream socket.
EPIPE	Connection was broken.
ETIMEDOUT	Connection timed out.
EWOULDBLOCK	Request would block.
SS$_THIRDPARTY	Network is being shut down.

IO$_SETCHAR

Sets special device characteristics for the INET device rather than for the socket attached to it. These operations are normally used by the TCPware master server (NETCP) process only. IO$_SETCHAR requires LOG_IO privileges.

Format

status = SYS$QIO(efn,inet-chan, IO$_SETCHAR, iosb, astadr, astprm, flags, 0, 0, 0, 0, 0);

Arguments

chan = u_int inet-chan

Channel to the socket.

p1 = u_long flags

Address of a longword bit mask of one or more of the values that appear in the below table. If IO$_SETCHAR is not called, all options are set to OFF.

Bit	Description
0	If set, makes the device permanent. If clear, makes the device temporary (default).
1	If set, makes the device shareable. If clear, makes the device nonshareable (default).
2	If set, allow the device to be handed off. (The device is not deleted when the last channel is deassigned, but is deleted the next time the last channel is deassigned.)

Status

SS$_NOPRIV

Argument requires LOG_IO privileges.

IO$_SETMODE | IO$M_ATTNAST

Enables an AST to be delivered to the process when out-of-band (TCP urgent) data is received on the socket. This function is similar to the UNIX SIGURG signal being delivered.

This is a once-only AST. After the AST is delivered, you must explicitly re-enable it using this function if you want the AST to be delivered when future out-of-band data is received.

Format

status = SYS$QIO(efn,inet-chan, IO$_SETMODE | IO$M_ATTNAST,iosb, astadr, astprm, routine, parameter, acmode, 0, 0, 0);

Arguments

chan = u_int inet-chan

Channel to the socket.

p1 = void *routine

Address of the AST routine to call when out-of-band data arrives on the socket. To cancel AST delivery, specify routine as 0.

p2 = u_long parameter

Argument to call the AST routine.

p3 = u_long acmode

Access mode for the AST.

IO$_SETSOCKOPT

Manipulates options associated with a socket.

The TCPWARE_INCLUDE:SOCKET.H file contains definitions for the socket-level options. The IPPROTO_IP level options defined in the TCPWARE_INCLUDE:IN.H file are not compatible with INETDRIVER.

Format

status = SYS$QIO(efn, inet-chan, IO$_SETSOCKOPT,iosb, astadr, astprm, level, optname, optval, optlen, 0, 0);

Arguments

chan = u_int inet-chan

Channel to the socket.

p1 = u_long level

SOL_SOCKET to change socket options, IPPROTO_TCP to change TCP options, or IPPROTO_IP to change IP options (which requires a SYSTEM UIC, or the SYSPRV or BYPASS privilege).

p2 = u_long optname

Option to be manipulated. See the below tables.

Argument Values for SOL_SOCKET Level:

SOL_SOCKET Option	Description
SO_BROADCAST	Enables or disables broadcasting on the socket (ignored)
SO_DEBUG	Enables debugging in the protocol modules (ignored)
SO_DONTROUTE	Prevents routing applied to outgoing messages (ignored)
SO_ERROR	Returns current socket error (if any)
SO_KEEPALIVE	Keeps connections alive
SO_LINGER	Delay (in seconds) before closing a socket (ignored)
SO_OOBINLINE	Leaves received out-of-band data in line
SO_REUSEADDR	Allows local address reuse
SO_RCVBUF	Size of the internal receive buffer
SO_RCVLOWAT	(Ignored)
SO_RCVTIMEO	Receive timeout time (ignored for stream sockets)
SO_SNDBUF	Size of the internal send buffer
SO_SNDLOWAT	(Ignored)
SO_SNDTIMEO	Send timeout time (ignored for datagram sockets)
SO_TYPE	Type of socket (stream or datagram)
SO_USELOOPBACK	Bypasses hardware when possible (ignored)

Argument Values for IPPROTO_TCP Level:

IPPROTO_TCP Option	Description
TCP_KEEPALIVE	Determines how long an idle socket should remain open

Argument Values for IPPROTO_IP Level:

IPPROTO_IP Option	Description
IP_OPTIONS	Gets or sets IP options to be sent in subsequent datagrams
IP_MULTICAST_IF	Gets or sets the interface used for sending multicast datagrams
IP_MULTICAST_TTL	Gets or sets the IP time-to-live (TTL) to be sent in subsequent datagrams
IP_MULTICAST_LOOP	Gets or sets whether sent multicast datagrams should be looped back locally
IP_ADD_MEMBERSHIP	Adds a multicast group membership for an interface
IP_DROP_MEMBERSHIP	Drops a multicast group membership from an interface

p3 = byte *optval

Pointer to a buffer that contains the value to which the option is to be set. The format of this buffer is dependent on the option requested.

p4 = u_long optlen

Byte length of the optval buffer.

Status

EADDRNOTAVAIL	Address not available for use.
EADDRINUSE	Address already in use.
EINVAL	level specified is invalid.
ENETDOWN	Network was shut down.
ENOBUFS	Insufficient memory for requests.
ENOPROTOOPT	Option is unknown.
ETOOMANYREFS	Too many multicast memberships requested.
SS$_THIRDPARTY	Network is being shut down.

IO$_SHUTDOWN

Causes all or part of a full-duplex connection on a socket to be shut down. Can be used to signal an end-of-file to the peer without closing the socket itself, which would also prevent further data from being received.

Format

status = SYS$QIO(efn, inet-chan, IO$_SHUTDOWN, iosb, astadr, astprm, how, 0, 0, 0, 0, 0);

Arguments

chan = u_int inet-chan

Channel to the socket.

p1 = u_long how

Part of the full-duplex connection to shut down, as shown in the below table.

Value	Description
0	Further receive operations are not allowed
1	Further send operations are not allowed
2	Further receive and send operations are not allowed

Status

EINVAL	how specified is invalid.
ENETDOWN	Network was shut down.
SS$_THIRDPARTY	Network is being shut down.

IO$_SOCKET

Creates the desired socket type. The three currently supported types are stream sockets (SOCK_STREAM), datagram sockets (SOCK_DGRAM), and raw sockets (SOCK_RAW).

Note: Before issuing the IO$_SOCKET function, an INET channel must first be assigned to the INET0: device, using SYS$ASSIGN.

Format

status = SYS$QIO(efn, inet-chan, IO$_SOCKET, iosb, astadr, astprm, AF_INET(2), type, protocol, 0, 0, 0);

Arguments

chan = u_int inet-chan

Channel to the socket.

p1 = u_long addressfam = AF_INET

Must be AF_INET.

p2 = u_long type

Semantics of communication using the created socket. The three currently supported types are: SOCK_STREAM (for a TCP socket), SOCK_DGRAM (for a UDP socket), and SOCK_RAW (for a raw socket).

p3 = u_long protocol

For TCP and UDP sockets, the protocol argument value must be 0. For raw sockets, a non-zero protocol can be specified.

Status

ENETDOWN	Network was shut down.
EPROTONOSUPPORT	Requested addressfam, type, or protocol is not supported.
SS$_THIRDPARTY	Network is being shut down.

SYS$ASSIGN

Assigns a channel to a device.

Format

status = SYS$ASSIGN(char *devnam, u_int inet-chan, [u_long acmode], [char *mbxnam]);

Arguments

devnam

Address of a character string descriptor pointing to the device name string.

inet-chan

Address of a word into which SYS$ASSIGN writes the channel number.

acmode

Optional access mode associated with the channel. The most privileged access mode used is that of the caller.

mbxnam

Optional logical mailbox associated with the device. (Not supported by INETDRIVER.)

Status

See the VMS System Services Reference Manual for a complete list of status messages.

SYS$CANCEL

Cancels any I/O that is pending on a socket.

The I/O will be completed with an iosb status of SS$CANCEL.

Outstanding I/O operations are automatically cancelled at image exit.

Format

status = SYS$CANCEL(u_int inet-chan);

Argument

inet-chan

Number of the channel to be cancelled.

Status

See the VMS System Services Reference Manual for a complete list of status messages.

SYS$DASSGN

Closes a socket.

When you deassign a channel, any outstanding I/O is completed with an iosb status of SS$CANCEL.

I/O channels are automatically deassigned at image exit.

Format

status = SYS$DASSGN(u_int inet-chan);

Argument

inet-chan

Number of the channel to be de-assigned.

Status

See the VMS System Services Reference Manual for a complete list of status messages.

Sample Programs

The following pair of sample programs, which show the use of stream sockets with SYS$QIO system service calls to the INETDRIVER, are included in the TCPWARE_COMMON:[TCPWARE.EXAMPLES] directory:

· INETDRIVER_CLIENT.C

· INETDRIVER_SERVER.C

They are functionally the same as the TCP_SOCKET_CLIENT.C and TCP_SOCKET_SERVER.C sample programs.

The client calling sequence is as follows:

1. Assign a channel for the connection ($ASSIGN)

2. Create a stream socket (IO$_SOCKET)

3. Connect to the server (IO$_CONNECT)

4. Exchange data (IO$_SEND, IO$_RECEIVE)

5. Close the connection ($DASSGN)

The server calling sequence is as follows:

1. Assign a channel to listen on ($ASSIGN)

2. Create a stream socket to listen on (IO$_SOCKET)

3. Bind the socket to an address (IO$_BIND)

4. Listen for incoming connections (IO$_LISTEN)

5. Assign a channel to accept on ($ASSIGN)

6. Accept the incoming connection (IO$_ACCEPT)

7. Exchange data (IO$_SEND, IO$_RECEIVE)

8. Close the connection ($DASSGN)

To build any one of these applications using DEC C, enter:

$ CC/DECC/PREFIX=ALL filename
$ LINK filename

To build any one of these applications using VAX C, enter:

$ CC/VAXC filename
$ LINK filename, TCPWARE:UCX$IPC/LIB, SYS$INPUT/OPTIONS -
_$ SYS$SHARE:VAXCRTL/SHARE