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

Previous | Contents | Index

# socket()

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

## Format

> #include <types.h>

> #include <socket.h>

> int socket ( int af, int type, int protocol );

## Arguments

> ### af

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

> ### type

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

> ### protocol

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

## Description

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

> Related Functions

> See also `accept()` , `bind()` , `connect()` , `listen()` , `read()` , `recv()` , `recvfrom()` , `recvmsg()` , `select()` , `send()` , `sendmsg()` , `sendto()` , `shutdown()` , and `write()` .

> Related Functions

> See also `getsockname()` and `getsockopt()` .

## Return Values

> x | A file descriptor that refers to the socket descriptor.
> -1 | Error; `errno` is set to indicate the error.

## Errors

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

# write()

> Writes bytes from a buffer to a file or socket.

> The $QIO equivalent is the IO$_WRITEVBLK function.

## Format

> #include <unixio.h>

> int write ( int d, void *buffer, int nbytes );

## Arguments

> ### d

> A descriptor that refers to a socket or file.

> ### buffer

> The address of a buffer from which the output data is to be taken.

> ### nbytes

> The maximum number of bytes involved in the write operation.

## Description

> This function attempts to write a buffer of data to a socket or file.

> Related Functions

> See also `socket()` .

## Return Values

> x | The number of bytes written to the socket or file.
> -1 | Error; `errno` is set to indicate the error.

## Errors

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

# Chapter 5
Using the $QIO System Service

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:

- Queue I/O Request ($QIO) --- Completes asynchronously. It returns to the caller immediately after queuing the I/O request, without waiting for the I/O operation to complete.
- Queue I/O Request and Wait ($QIOW) --- Completes synchronously. It returns to the caller after the I/O operation completes.

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.

Table 5-1 $QIO Arguments
Argument | Description
--- | ---
astadr | AST (asynchronous system trap) service routine
astprm | AST parameter to be passed
chan | I/O channel
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-2 Network Symbol Definition Files
File Name | Language
--- | ---
TCPIP$INETDEF.H | Compaq C
TCPIP$INETDEF.FOR | VAX Fortran
TCPIP$INETDEF.PAS | VAX PASCAL
TCPIP$INETDEF.MAR | MACRO-32
TCPIP$INETDEF.PLI | VAX PL/1
TCPIP$INETDEF.R32 | BLISS-32
TCPIP$INETDEF.ADA | VAX Ada
TCPIP$INETDEF.BAS | VAX BASIC

# 5.3 $QIO Functions

Table 5-3 lists the $QIO function codes commonly used in a network application.

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

Table 5-3 $QIO Function Codes
Function | Description
--- | ---
$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.
$QIO(IO$_SENSECHAR) $QIO(IO$_SENSEMODE) | Obtains socket information.

# 5.4 $QIO Arguments

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

## 5.4.1 $QIO Function-Independent Arguments

Table 5-4 describes the $QIO function-independent arguments.

Table 5-4 $QIO Function-Independent Arguments
Argument | Description
--- | ---
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.
func | 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.)

## 5.4.2 I/O Status Block

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.

Table 5-5 $QIO Function-Dependent Arguments
$QIO | p1 | p2 | p3 | p4 | p5 | p6
--- | --- | --- | --- | --- | --- | ---
IO$_ACCESS | Not used | Not used | Remote socket name 4 | Not used | Not used | Not used
IO$_ACCESS| IO$M_ACCEPT | 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
IO$_DEACCESS| IO$M_SHUTDOWN | 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
IO$_READVBLK| IO$M_INTERRUPT | 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
IO$_WRITEVBLK| IO$M_INTERRUPT | 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

1By value.
2By reference.
3By descriptor.
4By item_list_2 descriptor.
5By item_list_3 descriptor.

Previous | Next | Contents | Index