HP OpenVMS Systems Documentation
Compaq TCP/IP Services for OpenVMS
Creates an endpoint for communication by returning a special kind of file descriptor called a socket descriptor, which is associated with a TCP/IP Services socket device channel.
The $QIO equivalent is the IO$_SETMODE function.
int socket ( int af, int type, int protocol );
afThe address family used in later references to the socket. Addresses specified in subsequent operations using the socket are interpreted according to this family. Currently, only the AF_INET (internet) and TCPIP$C_AUXS addresses are supported.
For a network application server with the LISTEN flag enabled, you specify the TCPIP$C_AUXS address family to obtain the connected device socket created by the auxiliary server in response to incoming network traffic. For an example of this situation, refer to the example in Section E.1.3.
typeThe socket types are:
- SOCK_STREAM --- Provides sequenced, reliable, two-way, connection-based byte streams with an available out-of-band data transmission mechanism.
- SOCK_DGRAM --- Supports datagrams (connectionless, unreliable data transmission mechanism).
- SOCK_RAW --- Provides access to internal network interfaces. Available only to users with either a system UIC or the SYSPRV privilege.
protocolThe protocol to be used with the socket. Normally, only a single protocol exists to support a particular socket type using a given address format. However, if many protocols exist, a particular protocol must be specified with this argument. Use the protocol number that is specific to the communication domain in which communication takes place.
This function provides the primary mechanism for creating sockets. The type and protocol of the socket affect the way the socket behaves and how it can be used.
The operation of sockets is controlled by socket-level options, which are defined in the SOCKET.H header file and described in the setsockopt() function section of this chapter.
Use the setsockopt() and getsockopt() functions to set and get options. Options take an integer argument that should be nonzero if the option is to be enabled or zero if it is to be disabled. SO_LINGER uses a linger structure argument defined in <socket.h> .
See also accept() , bind() , connect() , listen() , read() , recv() , recvfrom() , recvmsg() , select() , send() , sendmsg() , sendto() , shutdown() , and write() .
See also getsockname() and getsockopt() .
x A file descriptor that refers to the socket descriptor. -1 Error; errno is set to indicate the error.
EACCES The process does not have sufficient privileges. EAFNOSUPPORT The specified address family is not supported in this version of the system. EMFILE The per-process descriptor table is full. ENETDOWN TCP/IP Services was not started. ENFILE No more file descriptors are available for the system. ENOBUFS The system has insufficient resources to complete the call. ENOMEM The system was unable to allocate kernel memory to increase the process descriptor table. EPERM The process is attempting to open a raw socket and does not have SYSTEM privilege. EPROTONOSUPPORT The socket in the specified address family is not supported. EPROTOTYPE The socket type is not supported by the protocol. ESOCKTNOSUPPORT The specified socket type is not supported in this address family.
Writes bytes from a buffer to a file or socket.
The $QIO equivalent is the IO$_WRITEVBLK function.
int write ( int d, void *buffer, int nbytes );
dA descriptor that refers to a socket or file.
bufferThe address of a buffer from which the output data is to be taken.
nbytesThe maximum number of bytes involved in the write operation.
This function attempts to write a buffer of data to a socket or file.
See also socket() .
x The number of bytes written to the socket or file. -1 Error; errno is set to indicate the error.
EPIPE The socket is shut down for writing or is connection oriented, and the peer is closed or shut down for reading. In the latter case, if the socket is of type SOCK_STREAM , the SIGPIPE signal is generated to the calling process. EWOULDBLOCK The NBIO (nonblocking) flag is set for the socket descriptor, and the process is delayed during the write operation. EINVAL The nbytes argument is a negative value. EAGAIN The O_NONBLOCK flag is set on this file, and the process is delayed in the write operation. EBADF The d argument does not specify a valid file descriptor that is open for writing. EINTR A write() or pwrite() function on a pipe is interrupted by a signal, and no bytes have been transferred through the pipe. EINVAL On of the following errors occurred:
- The STREAM or multiplexer referenced by d is linked (directly or indirectly) downstream from a multiplexer.
- The iov_count argument value was less than or equal to zero or greater than IOV_MAX .
- The sum of the iov_len values in the iov array overflows a ssize_t data type.
- The file position pointer associated with the d argument was a negative value.
- One of the iov_len values in the iov array was negative, or the sum overflowed a 32-bit integer.
EPERM An attempt was made to write to a socket of type SOCK_STREAM that is not connected to a peer socket. EPIPE An attempt was made to write to a pipe that has only one end open.
An attempt was made to write to a pipe or FIFO that is not opened for reading by any process. A SIGPIPE signal is sent to the process.
ERANGE An attempt was made to write to a STREAM socket where nbytes are outside the specified minimum and maximum range, and the minimum value is nonzero.
This chapter describes how to use the $QIO system service and its data structures with TCP/IP Services.
After you create a network pseudodevice (BG:) and assign a channel to
it, use the $QIO system service for I/O operations.
5.1 $QIO System Service Variations
The two variations of the $QIO system service are:
The only difference between the $QIO and $QIOW calling sequences is the
service name. The system service arguments are the same.
5.2 $QIO Format
The $QIO calling sequence has the following format:
SYS$QIO [efn], chan, func, [iosb], [astadr], [astprm], [p1], [p2], [p3], [p4], [p5], [p6]
Table 5-1 describes each argument.
|astadr||AST (asynchronous system trap) service routine|
|astprm||AST parameter to be passed|
|efn||Event flag number|
|func||Network pseudodevice function code and/or function modifier|
|iosb||I/O status block|
|p1, p2, p3, p4, p5, p6||Function-specific I/O request parameters|
5.2.1 Symbol Definition Files
Table 5-2 lists the symbol definition files for the $QIO arguments
p1 through p6. Use the standard
mechanism for the programming language you are using to include the
appropriate symbol definition files in your program.
Table 5-3 lists the $QIO function codes commonly used in a network application.
The IO$_SETMODE and IO$_SETCHAR function codes are identical. All references to the IO$_SETMODE function code, its arguments, options, function modifiers, and condition values returned also apply to the IO$_SETCHAR function code, which is not explicitly described in this manual.
The IO$_SENSEMODE and IO$_SENSECHAR function codes are identical. All references to the IO$_SENSEMODE function code, its arguments, options, function modifiers, and condition values returned also apply to the IO$_SENSECHAR function code, which is not explicitly described in this manual.
|$QIO(IO$_SETMODE) $QIO(IO$_SETCHAR)||Creates the socket by setting the internet domain, protocol (socket) type, and protocol of the socket.|
|Binds a name (local address and port) to the socket.|
|Defines a network pseudodevice as a listener on a TCP/IP server.|
|Specifies socket options.|
|$QIO(IO$_ACCESS)||Initiates a connection request from a client to a remote host using TCP.|
|Specifies the peer where you can send datagrams.|
|Accepts a connection request from a TCP/IP client when used with the IO$M_ACCEPT function modifier.|
|$QIO(IO$_WRITEVBLK)||Writes data (virtual block) from the local host to the remote host for stream sockets, datagrams, and raw IP.|
|$QIO(IO$_READVBLK)||Reads data (virtual block) from the remote host to the local host for stream sockets, datagrams, and raw IP.|
|$QIO(IO$_DEACCESS)||Disconnects the link established between two communication agents through an IO$_DEACCESS function.|
|Shuts down the communication link when used with the IO$M_SHUTDOWN function modifier. You can shut down the receive or transmit portion of the link, or both.|
|Obtains socket information.|
You pass two types of arguments with the $QIO system service:
function-independent arguments and function-dependent arguments. The
following sections provide information about $QIO system service
5.4.1 $QIO Function-Independent Arguments
Table 5-4 describes the $QIO function-independent arguments.
|astadr||Address of the asynchronous system trap (AST) routine to be executed when the I/O operation is completed.|
|astprm||A quadword (Alpha) or longword (VAX) containing the value to be passed to the AST routine.|
|chan||A longword value that contains the number of the I/O channel. The $QIO system service uses only the low-order word.|
|efn||A longword value of the event flag number that the $QIO system service sets when the I/O operation completes. The $QIO system service uses only the low-order byte.|
A longword value that specifies the network pseudodevice function code
and function modifiers that specify the operation to be performed.
Function modifiers affect the operation of a specified function code. In MACRO-32, you use the exclamation point (!) to logically OR the function code and its modifier. In Compaq C, you use the vertical bar (|). This manual uses the vertical bar (|) in text.
|iosb||The I/O status block that receives the final status message for the I/O operation. The iosb argument is the address of the quadword I/O status block. (For the format of the I/O status block, see Section 5.4.2.)|
The system returns the status of a $QIO operation in the I/O status block supplied as an argument to the $QIO call. In the case of a successful IO$_READVBLK or an IO$_WRITEVBLK operation, the second word of the I/O status block contains the number of bytes transferred during the operation (see Figure 5-1).
Figure 5-1 I/O Status Block for a Successful READ or WRITE Operation
With an unsuccessful IO$_READVBLK or an IO$_WRITEVBLK operation, in most cases, the system returns a Compaq Tru64 UNIX error code in the second word of the I/O status block.
The OpenVMS completion codes are defined in the SSDEF.H header file.
The Compaq Tru64 UNIX error codes are defined in the ERRNO.H header file
and in the TCPIP$INETDEF.H header file.
5.4.3 $QIO Function-Dependent Arguments
Arguments p1, p2, p3, p4, p5, and p6 to the $QIO system service are used to pass function-dependent arguments. Table 5-5 lists arguments p1 through p6 for the $QIO system service and indicates whether the parameter is passed by value, by reference, or by descriptor.
|IO$_ACCESS||Not used||Not used||Remote socket name 4||Not used||Not used||Not used|
|Not used||Not used||Remote socket name 5||Channel number 2||Not used||Not used|
|IO$_ACPCONTROL||Subfunction code 3||Input parameter 3||Buffer length 2||Buffer 3||Not used||Not used|
|IO$_DEACCESS||Not used||Not used||Not used||Not used||Not used||Not used|
|Not used||Not used||Not used||Shutdown flags 1||Not used||Not used|
|IO$_READVBLK||Buffer 2||Buffer size 1||Remote socket name 5||Flags 1||Not used||Output buffer list 3|
|Buffer 2||Buffer size 1||Not used||Not used||Not used||Not used|
|IO$_WRITEVBLK||Buffer 2||Buffer size 1||Remote socket name 4||Flags 1||Input buffer list 3||Not used|
|Buffer 2||Buffer size 1||Not used||Not used||Not used||Not used|
|IO$_SETMODE||Socket char 2||Not used||Local socket name 4||Backlog limit 1||Input parameter list 4||Not used|
|IO$_SENSEMODE||Not used||Not used||Local socket name 5||Remote socket name 5||Not used||Output parameter list 4|