DIGITAL TCP/IP Services for OpenVMS
System Services and C Socket Programming


Previous Contents Index

Example 4-11 IO$_READVBLK Function --- INET device (C Programming)

#module read_io 
/* 
**++ 
**      
** This example does read from INET device 
** 
**-- 
*/ 
 
 
/* 
**  INCLUDE FILES 
*/ 
 
#include <descrip.h> 
#include <tcpip$inetdef.h>     /* INET symbol definitions */ 
#include <iodef.h> 
 
struct sockaddr {            /* Structure definition for socket adrs */ 
        short inet_family ; 
        short inet_port ; 
        char adrs[4] ; 
        char blkb[8] ; 
       } ; 
 
struct itlst { 
        int lgth ; 
        struct sockaddr *hst ; 
         } ;                      
main() 
 
{ 
     int status ;            /* For return status */ 
     short channel           /* INET channel */ 
     short sck_parm[2] ;     /* Socket creation parameter */ 
     int iosb [2] ;          /* I/O status block           */ 
     struct sockaddr local_host ; /* Socket adrs definition for lhst */ 
     struct itlst lhst_adrs ; 
     char buf[128] ; 
     int buflen = 128 ; 
     
/* Descriptor for Inet device name */ 
 
     struct dsc$descriptor dev = 
         { 3, DSC$K_CLASS_S, DSC$K_DTYPE_T, "TCPIP$DEVICE:"} ;     
 
/* Initialize the parameters */ 
 
     sck_parm[0] = INET$C_UDP ;     /* UDP/IP protocol */ 
     sck_parm[1] = INET_PROTYP$C_DGRAM ; /* Datagram type of socket */ 
 
/* Itlst for local IP address */ 
 
     lhst_adrs.lgth = sizeof(local_host); 
     lhst_adrs.hst = &local_host ; 
/* 
** Assign a channel to INET device 
*/ 
          
        status = SYS$ASSIGN( &dev, 
                             &channel, 
                             0, 
                             0) ; 
      if ((status & 1) == 0) { 
         printf("Failed to assign channel to INET device \n") ; 
         return(status) ; 
          } 
/* Initialize socket address for local host */ 
 
       local_host.inet_family = INET$C_AF_INET ;/* INET family */ 
       local_host.inet_port = 0 ;             /* Port number */ 
       local_host.adrs[0] = 128 ;             /* Network/subnetwork*/ 
       local_host.adrs[1] = 45 ;              /*  number */ 
       local_host.adrs[2] = 45 ; 
       local_host.adrs[3] = 216 ;               /* Host number */ 
       local_host.blkb[0] = 0 ; 
       local_host.blkb[1] = 0 ; 
       local_host.blkb[2] = 0 ; 
       local_host.blkb[3] = 0 ; 
       local_host.blkb[4] = 0 ; 
       local_host.blkb[5] = 0 ; 
       local_host.blkb[6] = 0 ; 
       local_host.blkb[7] = 0 ; 
/* 
** Create and bind the device socket to local host 
*/ 
 
     status = SYS$QIOW( 31,          /* Event flag */ 
                        channel,     /* Channel number */ 
                        IO$_SETMODE, /* I/O function */ 
                        iosb,        /* I/O status block */ 
                        0, 
                        0, 
                        &sck_parm, /* P1 Socket creation parameter */ 
                        0, 
                        &lhst_adrs, /* P3 Socket bind parameter */ 
                        0,0,0) ; 
     if ((status & 1) == 0) { 
         printf("Failed to create and bind the device socket \n") ; 
         return(status) ; 
       } 
/* 
** Perform the QIO read operation 
*/ 
 
     status = SYS$QIOW( 0,           /* Event flag */ 
                        channel,    /* Channel number */ 
                        IO$_READVBLK,/* I/O function */ 
                        iosb,        /* I/O status block */ 
                        0, 
                        0, 
                        buf,         /* P1 buffer */          
                        buflen,      /* P2 buffer length */ 
                        0,0,0,0 ) ; 
     if ((status & 1) == 0) { 
         printf("Failed to read from inet device \n") ; 
         return(status) ; 
     } 
/* 
** Deassign the INET dev channel 
*/ 
        SYS$DASSGN (channel); 
 
        return(status) ; 
 
} 
 


IO$_SENSEMODE/IO$_SENSECHAR

The Sense Mode (IO$_SENSEMODE) and Sense Characteristics (IO$_SENSECHAR) I/O functions return the characteristics of the internet pseudodevice.

The C Socket equivalent is the getsockopt() or ioctl() functions.


Arguments

p3


usage item_list_3
type longword (unsigned)
access read only
mechanism by descriptor

The p3 argument contains the address of an item_list_3 descriptor that specifies the buffer where the software returns the local socket name. The buffer contains the local socket address (family name, port number, and internet address). The parameter name for the descriptor is TCPIP$_C_SOCK_NAME, which is defined in the TCPIP$INETDEF symbol definition file.

The C Socket equivalent for this function is getsockname().

p4


usage item_list_3
type longword (unsigned)
access read only
mechanism by descriptor

The p4 argument contains the address of an item_list_3 descriptor that specifies the buffer from which to return the remote peer socket name. The buffer contains the remote socket address (family name, port number, and internet address).

The C Socket equivalent for this function is getpeername().

p6


usage item_list_2 or item_list_3
type longword (unsigned)
access read only
mechanism by descriptor

The p6 argument specifies the address of a descriptor that lists item_list_2 or item_list_3 descriptors. The following are the parameter types for the DIGITAL TCP/IP Services for OpenVMS item_list to which the p6 argument points:

The item_list descriptor points to an integer (with the length set to the size of the integer). The integer contains zero to clear an option and nonzero to set an option.

The TCPIP$C_SOCKOPT parameter specifies the communication socket options. The descriptor that defines the list of socket options points to a list of item_list_3 descriptors, which contains one descriptor for each option. Table 4-9 describes the options for the TCPIP$C_SOCKOPT parameter type.

Table 4-9 The p6 Socket Options
Socket Option Description
TCPIP$C_BROADCAST Permits the sending of broadcast messages. Takes an integer parameter and requires a system user identification code (UIC) or SYSPRV, BYPASS, or OPER privilege. Optional for connectionless datagram.
TCPIP$C_DONTROUTE Indicates that outgoing messages should bypass the standard routing facilities. Instead, the messages are directed to the appropriate network interface according to the network portion of the destination address.
TCPIP$C_ERROR Obtains the socket error status and clears the error on the socket.
TCPIP$C_FULL_DUPLEX_CLOSE When set before a close operation, both receive and transmit sides of the communications are closed.
TCPIP$C_KEEPALIVE Keeps connections active. Enables the periodic transmission of messages on a connected socket. If the connected socket fails to respond to the messages, the connection is broken.
TCPIP$C_LINGER Lingers on a close() function if data is present. Controls the action taken when unsent messages queue on a socket and a close() function is performed. Uses a linger structure parameter defined in <socket.h> to specify the state of the option and linger interval.

If TCPIP$C_LINGER is specified, the system blocks the process during the close() function until it can transmit the data or until the time expires. If the option is not specified and a close() function is issued, the system allows the process to continue as quickly as possible.

TCPIP$C_OOBINLINE Leaves the received out-of-band (OOB) data (data marked urgent) in line. Takes an integer parameter.
TCPIP$C_RCVBUF Sets the receive buffer size. Takes an integer parameter and requires a system UIC or SYSPRV, BYPASS, or OPER privilege.
TCPIP$C_RCVTIMEO For Compaq use only. Sets the timeout value for a recv() operation.
TCPIP$C_REUSEADDR Specifies that the rules used in validating addresses supplied by a bind() function should allow reuse of local addresses. Takes an integer value.
TCPIP$C_REUSEPORT Allows more than one process to receive UDP datagrams destined for the same port. The bind() call that binds a process to the port must be preceded by a setsockopt() call specifying this option.
TCPIP$C_SHARE Allows multiple processes to share the socket.
TCPIP$C_SNDBUF Sets the send buffer size. Takes an integer parameter and requires a system UIC or SYSPRV, BYPASS, or OPER privilege. Optional for a connectionless datagram.
TCPIP$C_SNDLOWAT Sets the low-water mark for a send() operation. Takes an integer parameter.
TCPIP$C_SNDTIMEO For Compaq use only. Sets the timeout value for a send() operation.
TCPIP$C_TYPE Obtains the socket type.
TCPIP$C_USELOOPBACK For Compaq use only. Valid for routing sockets. Determines if a sending socket receives a copy of its own message. Used when a set request on another socket type is ignored.

Unsupported socket options are ignored.

Table 4-10 describes the TCP options for the TCPIP$C_TCPOPT parameter type.

Table 4-11 describes the options for the TCPIP$C_IPOPT parameter type.

Table 4-10 TCP Options
TCP Option Description
TCPIP$C_TCP_DROP_IDLE When the TCPIP$C_KEEPALIVE option is enabled, specifies the time interval after which a connection is dropped. Default: 2 hours. Takes an integer value in the range of 1 to n, where n is TCPIP$C_TCP_DROP_IDLE divided by PR_SLOWHZ.
TCPIP$C_TCP_KEEPCNT When the TCPIP$C_KEEPALIVE option is enabled, specifies the maximum number of keepalive probes to be sent. Default: 8. Takes an integer value, with a range of 1 to TCPIP$C_KEEPCNT.
TCPIP$C_TCP_KEEPINIT Specifies the number of seconds to wait before the connect attempt times out. Default: 75 seconds. For passive connections, the value is inherited from the listening socket. Takes an integer value in the range of 1 to n, where n is TCPIP$C_TCP_KEEPINIT divided by PR_SLOWHZ.
TCPIP$C_TCP_NODELAY Specifies that the send() operation will not be delayed to merge packets.
TCPIP$C_TCP_MAXSEG Sets the maximum transmission unit (MTU) of a TCP segment to a specified integer value from 1 to 65,535. Default: 576 bytes. Can only be set before a listen() or connect() operation on the socket. For passive connections, the value is obtained from the listening socket.

Note that TCP does not use an MTU value that is less than 32 or greater than the local network's MTU. Setting the option to zero results in the default behavior.

TCPIP$C_TCP_NODELACK When specified, disables the algorithm that gathers outstanding data that has not been acknowledged and sends it in a single packet when acknowledgement is received. Takes an integer value.

Under most circumstances, TCP sends data when it is presented. When outstanding data has not yet been acknowledged, TCP gathers small amounts of the data into a single packet and sends it when an acknowledgement is received. This functionality can cause significant delays for some clients (such as windowing systems that send a stream of events from the mouse that do not expect replies).

TCPIP$C_TCP_PROBE_IDLE When the TCPIP$C_KEEPALIVE option is enabled, specifies the time interval for the keepalive probe and for the connections establishing the timeout. Default: 75 seconds. Takes an integer value in the range of 1 to n, where n is TCPIP$C_TCP_PROBE_IDLE divided by PR_SLOWHZ.

Table 4-11 IP Options
IP Option Description
TCPIP$C_IP_ADD_MEMBERSHIP Adds the host to the membership of a multicast group.

A host must become a member of a multicast group before it can receive datagrams sent to the group. Membership is associated with a single interface; programs running on multihomed hosts may need to join the same group on more than one interface. Up to IP_MAX_MEMBERSHIPS (currently 20) memberships may be added on a single socket.

TCPIP$C_IP_DROP_MEMBERSHIP Removes the host from the membership of a multicast group.
TCPIP$C_IP_HDRINCL If specified, the IP header is not prepended to the outgoing packet.
TCPIP$C_IP_MULTICAST_IF For hosts with multiple interfaces. When specified, each multicast transmission is sent from the primary network interface. Overrides the default for subsequent transmissions from a given socket.
TCPIP$C_IP_MULTICAST_LOOP Disables loopback of local delivery.

If a multicast datagram is sent to a group of which the sending host is a member, a copy of the datagram is looped back by the IP layer for local delivery (default). To disable the loopback delivery, specify the value 0.

TCPIP$C_IP_MULTICAST_TTL Specifies the time-to-live (TTL) value for outgoing multicast datagrams. Takes an integer value between 0 and 255:
Value Action
0 Restricts distribution to applications running on the local host.
1 Forwards the multicast datagram to hosts on the local subnet.
1-255 With a multicast router attached to the sending host's network, forwards multicast datagrams beyond the local subnet.

Multicast routers forward the datagram to known networks that have hosts belonging to the specified multicast group. The TTL value is decremented by each multicast router in the path. When the TTL value is decremented to 0, the datagram is no longer forwarded.

TCPIP$C_IP_OPTIONS Provides IP options to be transmitted in the IP header of each outgoing packet.
TCPIP$C_IP_RECVDSTADDR Enables a SOCK_DGRAM socket to receive the destination IP address for a UDP datagram.
TCPIP$C_IP_RECVOPTS Enables a SOCK_DGRAM socket to receive IP options.
TCPIP$C_IP_TTL Time to live (TTL) for a datagram.
TCPIP$C_IP_TOS Type of service (1-byte value).
The TCPIP$C_IOCTL parameter specifies the I/O control parameters. The parameters are specified through an item_list_2 descriptor that points to a list of longword entries. The first longword entry contains the IOCTL command. The second longword contains the address of a buffer structure descriptor. The IOCTL commands are listed in Table 4-12.

Table 4-12 IOCTL Commands
Parameter Structure IOCTL Command Description
Integer SIOCATMARK Determines if you are at the OOB character mark.
Integer FIONREAD Obtains the number of bytes that are queued in the socket receive queue.

You can use one $QIO system service call with the IO$_SENSEMODE modifier for multiple operations. For example, a $QIO system service could specify a list of socket options or a list of IOCTL commands, combined with a local socket name or peer socket name.

When the software detects an error, the iosb argument contains the error and parameter address or value that was at fault.

The DIGITAL TCP/IP Services for OpenVMS software sequentially processes parameters in this order: p3, p4, p6.

You can specify multiple lists of socket options or IOCTL commands. If you duplicate a parameter or IOCTL command in one or more lists, the value returned is the last option or IOCTL command read.


Condition Values Returned

SS$_ACCVIO Programming error. You attempted to access an invalid memory location or buffer.
SS$_BADPARAM Programming error. You specified a $QIO function with an invalid parameter that resulted from one of the following:
  1. You attempted to execute the IO$_SENSEMODE function without specifying a device socket. Instead, create a device socket by issuing a $QIO with the IO$_SETMODE function and the proper parameters.
  2. You made an error while specifying a socket option.
SS$_DEVINACT INET management error. The driver was not started. Execute a START COMMUNICATION command before issuing $QIO functions.
SS$_DEVNOTMOUNT INET management error. You improperly executed the INET startup procedure. The driver was loaded, but the INET_ACP was not activated. Execute the INET startup procedure again.
SS$_ILLCNTRFUNC Programming error. The operation is unsupported for one of the following reasons:
  1. You issued an invalid IO$_SENSEMODE function for the interface. The interface does not have an IOCTL routine.
  2. You issued a IO$_SENSEMODE function that requires a socket, but the device did not have one. Create a socket and then issue the function.
  3. An unsupported operation was performed on at least one of the following protocols: raw IP, datagram, or stream sockets.
SS$_INSFMEM INET management or programming error. Do one of the following:
  1. Set a higher quota for the dynamic buffer space.
  2. Shut down the internet and restart with larger static buffer space.
SS$_IVBUFLEN Programming error. You set a socket option buffer with an invalid size.
SS$_NOSUCHDEV Programming error or INET management error. An INET address is not in the Address Resolution Protocol (ARP) table. An attempt to show or delete an ARP table entry failed.
SS$_NOLINKS Programming error.
  1. Stream socket --- You did not connect the socket.
  2. Datagram or raw IP --- You did not specify an INET port and address with an IO$_ACCESS system service call.
  3. You used the IO$_SENSEMODE system service call to request the name of a peer socket without first issuing calls to connect the socket or establish the peer socket.
SS$_NOOPER Programming error. You attempted to get ARP information without having OPER privileges.
SS$_PROTOCOL Programming error. You attempted to set socket options on a closed socket.
SS$_SHUT The network is being shut down.
SS$_UNREACHABLE Programming error. Network is unreachable or the network address is invalid.
  1. You attempted to create a permanent ARP table with the network part of the INET address being zero.
  2. You attempted to create a route entry with the network part of the INET address being zero.


Previous Next Contents Index