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

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

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

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

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

**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 ⁴ Not used Not used Not used

IO$_ACCESS|
IO$M_ACCEPT Not used Not used Remote socket name ⁵ Channel number ² Not used Not used

IO$_ACPCONTROL Subfunction code ³ Input parameter ³ Buffer length ² Buffer ³ 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 ¹ Not used Not used

IO$_READVBLK Buffer ² Buffer size ¹ Remote socket name ⁵ Flags ¹ Not used Output buffer list ³

IO$_READVBLK|
IO$M_INTERRUPT Buffer ² Buffer size ¹ Not used Not used Not used Not used

IO$_WRITEVBLK Buffer ² Buffer size ¹ Remote socket name ⁴ Flags ¹ Input buffer list ³ Not used

IO$_WRITEVBLK|
IO$M_INTERRUPT Buffer ² Buffer size ¹ Not used Not used Not used Not used

IO$_SETMODE Socket char ² Not used Local socket name ⁴ Backlog limit ¹ Input parameter list ⁴ Not used

IO$_SENSEMODE Not used Not used Local socket name ⁵ Remote socket name ⁵ Not used Output parameter list ⁴

**Table 5-5 $QIO Function-Dependent Arguments**
$QIO	p1	p2	p3	p4	p5	p6
IO$_ACCESS	Not used	Not used	Remote socket name ⁴	Not used	Not used	Not used
IO$_ACCESS\| IO$M_ACCEPT	Not used	Not used	Remote socket name ⁵	Channel number ²	Not used	Not used
IO$_ACPCONTROL	Subfunction code ³	Input parameter ³	Buffer length ²	Buffer ³	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 ¹	Not used	Not used
IO$_READVBLK	Buffer ²	Buffer size ¹	Remote socket name ⁵	Flags ¹	Not used	Output buffer list ³
IO$_READVBLK\| IO$M_INTERRUPT	Buffer ²	Buffer size ¹	Not used	Not used	Not used	Not used
IO$_WRITEVBLK	Buffer ²	Buffer size ¹	Remote socket name ⁴	Flags ¹	Input buffer list ³	Not used
IO$_WRITEVBLK\| IO$M_INTERRUPT	Buffer ²	Buffer size ¹	Not used	Not used	Not used	Not used
IO$_SETMODE	Socket char ²	Not used	Local socket name ⁴	Backlog limit ¹	Input parameter list ⁴	Not used
IO$_SENSEMODE	Not used	Not used	Local socket name ⁵	Remote socket name ⁵	Not used	Output parameter list ⁴

¹By value.
²By reference.
³By descriptor.
⁴By item_list_2 descriptor.
⁵By item_list_3 descriptor.

Contents

Index

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.

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.

Compaq TCP/IP Services for OpenVMSSockets API and System Services Programming

socket()

Format

Arguments

af

type

protocol

Description

Return Values

Errors

write()

Format

Arguments

d

buffer

nbytes

Description

Return Values

Errors

Chapter 5Using the $QIO System Service

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

Chapter 5
Using the $QIO System Service