TCPIP Services, Programming Interfaces, Sockets API
*Conan The Librarian (sorry for the slow response - running on an old VAX)
|
VMS Help TCPIP Services, Programming Interfaces, Sockets API *Conan The Librarian (sorry for the slow response - running on an old VAX) |
|
This section describes functions that comprise the Sockets API
and that are supported by TCP/IP Services.
| 1 - accept() |
Accepts a connection on a passive socket.
The $QIO equivalent is the IO$_ACCESS function with the IO$M_
ACCEPT function modifier.
Format
#include <types.h>
#include <socket.h>
int accept ( int s, struct sockaddr *addr, int *addrlen );
1.1 - Arguments
s
A socket descriptor returned by socket(), subsequently bound to
an address with bind(), which is listening for connections after
a listen().
addr
A result parameter filled in with the address of the connecting
entity, as known to the Communications layer. The exact format of
the structure to which the address parameter points is determined
by the domain in which the communication is occurring. This
version of Compaq C supports only the internet domain (AF_INET).
addrlen
A value/result argument. It should initially contain the size of
the structure pointed to by addr. On return it will contain the
actual length, in bytes, of the sockaddr structure that has been
filled in by the Communications layer.
1.2 - Description
This function completes the first connection on the queue
of pending connections, creates a new socket with the same
properties as s, and allocates and returns a new descriptor
for the socket. If no pending connections are present on the
queue and the socket is not marked as nonblocking, accept()
blocks the caller until a connection request is present. If the
socket is marked nonblocking by using a setsockopt() call and no
pending connections are present on the queue, accept() returns
an error. You cannot use the accepted socket to accept subsequent
connections. The original socket s remains open (listening) for
other connection requests. This call is used with connection-
based socket types (SOCK_STREAM).
Related Functions
See also bind(), connect(), listen(), select(), and socket().
1.3 - Return Values
x A nonnegative integer that is a descriptor for
the accepted socket.
-1 Error; errno is set to indicate the error.
1.4 - Errors
EBADF The socket descriptor is invalid.
ECONNABORTED A connection has been aborted.
EFAULT The addr argument is not in a writable part of
the user address space.
EINTR The accept() function was interrupted by a
signal before a valid connection arrived.
EINVAL The socket is not accepting connections.
EMFILE There are too many open file descriptors.
ENFILE The maximum number of file descriptors in the
system is already open.
ENETDOWN TCP/IP Services was not started.
ENOBUFS The system has insufficient resources to
complete the call.
ENOMEM The system was unable to allocate kernel
memory.
ENOTSOCK The socket descriptor is invalid.
EOPNOTSUPP The reference socket is not of type SOCK_
STREAM.
EPROTO A protocol error occurred.
EWOULDBLOCK The socket is marked nonblocking, and no
connections are present to be accepted.
| 2 - bind() |
Binds a name to a socket.
The $QIO equivalent is the IO$_SETMODE function with the p3
argument.
Format
#include <types.h>
#include <socket.h>
int bind ( int s, struct sockaddr *name, int namelen );
2.1 - Arguments
s
A socket descriptor created with the socket() function.
name
Address of a structure used to assign a name to the socket in the
format specific to the family (AF_INET) socket address.
namelen
The size, in bytes, of the structure pointed to by name.
2.2 - Description
This function assigns a port number and IP address to an unnamed
socket. When a socket is created with the socket() function, it
exists in a name space (address family) but has no name assigned.
The bind() function requests that a name be assigned to the
socket.
Related Functions
See also connect(), getsockname(), listen(), and socket().
2.3 - Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
2.4 - Errors
EACCESS The requested address is protected, and the
current user has inadequate permission to
access it.
EADDRINUSE The specified internet address and ports are
already in use.
EADDRNOTAVAIL The specified address is not available from
the local machine.
EAFNOSUPPORT The specified address is invalid for the
address family of the specified socket.
EBADF The socket descriptor is invalid.
EDESTADDRREQ The address argument is a null pointer.
EFAULT The name argument is not a valid part of the
user address space.
EINVAL The socket is already bound to an address and
the protocol does not support binding to a new
address, the socket has been shut down, or the
length or the namelen argument is invalid for
the address family.
EISCONN The socket is already connected.
EISDIR The address argument is a null pointer.
ENOBUFS The system has insufficient resources to
complete the call.
ENOTSOCK The socket descriptor is invalid.
EOPNOTSUPP The socket type of the specified socket does
not support binding to an address.
| 3 - close() |
Closes a connection and deletes a socket descriptor.
The $QIO equivalent is the $DASSGN system service.
Format
#include <unixio.h>
int close ( s );
3.1 - Argument
s
A socket descriptor.
3.2 - Description
This function deletes a descriptor from the per-process object
(Compaq C structure) reference table. Associated TCP connections
close first.
If a call to the connect() function fails for a connection mode
socket, applications should use close() to deallocate the socket
and descriptor.
Related Functions
See also accept(), socket(), and write().
3.3 - Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
3.4 - Errors
EBADF The socket descriptor is invalid.
EINTR The close() function was interrupted by a
signal that was caught.
| 4 - connect() |
Initiates a connection on a socket.
The $QIO equivalent is the IO$_ACCESS function.
Format
#include <types.h>
#include <socket.h>
int connect ( int s, struct sockaddr *name, int namelen );
4.1 - Arguments
s
A socket descriptor created with socket().
name
The address of a structure that specifies the name of the remote
socket in the format specific to the address family (AF_INET).
namelen
The size, in bytes, of the structure pointed to by name.
4.2 - Description
If s is a socket descriptor of type SOCK_DGRAM, then this call
permanently specifies the peer where the data is sent. If s is of
type SOCK_STREAM, then this call attempts to make a connection to
the specified socket.
Each communications space interprets the name argument. This
argument specifies the socket that is connected to the socket
specified in s.
If the connect() function fails for a connection-mode socket,
applications should use the close() function to deallocate
the socket and descriptor. If attempting to reinitiate the
connection, applications should create a new socket.
Related Functions
See also accept(), select(), socket(), getsockname(), and
shutdown().
4.3 - Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
4.4 - Errors
EADDRINUSE Configuration problem. There are insufficient
ports available for the attempted connection.
The ipport_userreserved variable of the inet
subsystem should be increased.
EADDRNOTAVAIL The specified address is not available from
the local machine.
EAFNOSUPPORT The addresses in the specified address family
cannot be used with this socket.
EALREADY A connection request is already in progress
for the specified socket.
EBADF The socket descriptor is invalid.
ECONNREFUSED The attempt to connect was rejected.
EFAULT The name argument is not a valid part of the
user address space.
EHOSTUNREACH The specified host is not reachable.
EINPROGRESS O_NONBLOCK is set for the file descriptor
for the socket, and the connection cannot be
immediately established; the connection will
be established asynchronously.
EINTR The connect() function was interrupted by a
signal while waiting for the connection to be
established. Once established, the connection
may continue asynchronously.
EINVAL The value of the namelen argument is invalid
for the specified address family, or the sa_
family field in the socket address structure
is invalid for the protocol.
EISCONN The socket is already connected.
ELOOP Too many symbolic links were encountered in
translating the file specification in the
address.
ENETDOWN The local network connection is not
operational.
ENETUNREACH No route to the network or host is present.
ENOBUFS The system has insufficient resources to
complete the call.
ENOTSOCK The socket descriptor is invalid.
EOPNOTSUPP The socket is listening and cannot be
connected.
EPROTOTYPE The specified address has a different type
than the socket bound to the specified peer
address.
ETIMEDOUT The connection request timed out without
establishing a connection.
EWOULDBLOCK The socket is nonblocking, and the connection
cannot be completed immediately. It is
possible to use the select() function to
select the socket for writing.
| 5 - decc$get_sdc() |
Returns the socket device channel (SDC) associated with a socket
descriptor.
Format
#include <socket.h>
short int decc$get_sdc ( int s );
5.1 - Argument
s
A socket descriptor.
5.2 - Description
This function returns the SDC associated with a socket. Normally,
socket descriptors are used either as file descriptors or with
one of the functions that takes an explicit socket descriptor as
its argument. Sockets are implemented using TCP/IP socket device
channels. This function returns the SDC used by a given socket
descriptor so you can use the TCP/IP facilities directly by means
of various I/O system services ($QIO).
5.3 - Return Values
0 Indicates that s is not an open socket
descriptor.
x The SDC number.
| 6 - gethostbyaddr() |
Searches the hosts database sequentially from the beginning for a
host record with a given IPv4 address.
The $QIO equivalent is the IO$_ACPCONTROL function with the
INETACP_FUNC$C_GETHOSTBYADDR subfunction code.
Format
#include <netdb.h>
struct hostent *gethostbyaddr ( const void *addr, size_t len,
int type );
6.1 - Arguments
addr
A pointer to a series of bytes in network order specifying the
address of the host sought.
len
The number of bytes in the address pointed to by the addr
argument.
type
The type of address format being sought. Currently, only AF_INET
is supported.
6.2 - Description
This function finds the first host record in the hosts database
with the given address.
The gethostbyaddr() function uses a common static area for its
return values. This means that subsequent calls to this function
overwrite previously returned host entries. You must make a copy
of the host entry if you want to save it.
6.3 - Return Values
NULL Indicates an error; errno is set to one of the
following values.
x A pointer to an object having the hostent
structure.
6.4 - Errors
ENETDOWN TCP/IP Services was not started.
HOST_NOT_FOUND Host is unknown.
NO_DATA The server recognized the request and the
name, but no address is available for the
name. Another type of name server request may
be successful.
NO_RECOVERY An unexpected server failure occurred. This is
a nonrecoverable error.
TRY_AGAIN A transient error occurred, for example,
the server did not respond. A retry may be
successful.
| 7 - gethostbyname() |
Searches the hosts database sequentially from the beginning for a
host record with a given name or alias.
This function also invokes the BIND resolver to query the
appropriate name server if the information requested is not in
the hosts database.
The $QIO equivalent is the IO$_ACPCONTROL function with the
INETACP_FUNC$C_GETHOSTBYNAME subfunction code.
Format
#include <netdb.h>
struct hostent *gethostbyname ( char *name );
7.1 - Argument
name
A pointer to a null-terminated character string containing the
name or an alias of the host being sought.
7.2 - Description
This function finds the first host in the hosts database with the
given name or alias.
The gethostbyname() function uses a common static area for its
return values. This means that subsequent calls to this function
overwrite previously returned host entries. You must make a copy
of the host entry if you want to save it.
7.3 - Return Values
NULL Indicates an error.
x A pointer to an object having the hostent
structure.
7.4 - Errors
ENETDOWN TCP/IP Services was not started.
HOST_NOT_FOUND Host is unknown.
NO_DATA The server recognized the request and the
name, but no address is available for the
name. Another type of name server request may
be successful.
NO_RECOVERY An unexpected server failure occurred. This is
a nonrecoverable error.
TRY_AGAIN A transient error occurred, for example,
the server did not respond. A retry may be
successful.
| 8 - gethostname() |
Returns the fully qualified name of the local host.
Format
#include <types.h>
#include <socket.h>
int gethostname ( char *name, int namelen) ;
8.1 - Arguments
name
The address of a buffer where the name should be returned. The
returned name is null terminated unless sufficient space is not
provided.
namelen
The size of the buffer pointed to by name.
8.2 - Description
This function returns the translation of the logical names
TCPIP$INET_HOST and TCPIP$INET_DOMAIN when used with the TCP/IP
Services software.
8.3 - Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
8.4 - Errors
EFAULT The buffer described by name and namelen is
not a valid, writable part of the user address
space.
| 9 - getnetbyaddr() |
Searches the network database sequentially from the beginning for
a network record with a given address.
The $QIO equivalent is the IO$_ACPCONTROL function with the
INETACP_FUNC$C_GETNETBYADDR subfunction code.
Format
#include <netdb.h>
struct netent *getnetbyaddr ( long net, int type) ;
9.1 - Arguments
net
The network number, in host byte order, of the networks database
entry required.
type
The type of network being sought (AF_INET).
9.2 - Description
This function finds the first network record in the networks
database with the given address.
The getnetbyaddr() and getnetbyname() functions use a common
static area for their return values. Subsequent calls to any of
these functions overwrite any previously returned network entry.
You must make a copy of the network entry if you want to save it.
9.3 - Return Values
NULL Indicates end of file or an error.
x A pointer to an object having the netent
structure.
9.4 - Errors
EINVAL The net argument is invalid.
ESRCH The search failed.
| 10 - getnetbyname() |
Searches the networks database sequentially from the beginning
for a network record with a given name or alias.
The $QIO equivalent is the IO$_ACPCONTROL function with the
INETACP_FUNC$C_GETNETBYNAME subfunction code.
Format
#include <netdb.h>
struct netent *getnetbyname ( char *name );
10.1 - Argument
name
A pointer to a null-terminated character string containing either
the network name or an alias for the network name.
10.2 - Description
This function finds the first network record in the networks
database with the given name or alias.
The getnetbyaddr() and getnetbyname() functions use a common
static area for their return values. Subsequent calls to any of
these functions overwrite previously returned network entries.
You must make a copy of the network entry if you want to save it.
10.3 - Return Values
NULL Indicates end of file or an error.
x A pointer to an object having the netent
structure.
10.4 - Errors
EFAULT The buffer described by name is not a valid,
writable part of the user address space.
EINVAL The net or net_data argument is invalid.
ESRCH The search failed.
| 11 - getpeername() |
Returns the name of the connected peer.
The $QIO equivalent is the IO$_SENSEMODE function with the p4
argument.
Format
#include <types.h>
#include <socket.h>
int getpeername ( int s, struct sockaddr *name, int *namelen
);
11.1 - Arguments
s
A socket descriptor created using socket().
name
A pointer to a buffer where the peer name is to be returned.
namelen
An address of an integer that specifies the size of the name
buffer. On return, it is modified to reflect the actual length,
in bytes, of the name returned.
11.2 - Description
This function returns the name of the peer connected to the
specified socket descriptor.
Related Functions
See also bind(), socket(), and getsockname().
11.3 - Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
11.4 - Errors
EBADF The descriptor is invalid.
EFAULT The name argument is not a valid part of the
user address space.
EINVAL The socket has been shut down.
ENOBUFS The system has insufficient resources to
complete the call.
ENOTCONN The socket is not connected.
ENOTSOCK The socket descriptor is invalid.
EOPNOTSUPP The operation is not supported for the socket
protocol.
| 12 - getprotobyname() |
Searches the protocols database until a matching protocol name is
found or until end of file is encountered.
Format
#include <netdb.h>
struct protoent *getprotobyname ( char *name );
12.1 - Argument
name
A pointer to a string containing the desired protocol name.
12.2 - Description
This function returns a pointer to a protoent structure
containing data from the protocols database:
struct protoent {
char *p_name; /* official name of protocol */
char **p_aliases; /* alias list */
long p_proto; /* protocol number */
};
The members of this structure are:
p_name The official name of the protocol.
p_aliases A zero-terminated list of alternate names for
the protocol.
p_proto The protocol number.
All information is contained in a static area, so it must be
copied to be saved.
Related Functions
See also getprotoent() and getprotobynumber().
12.3 - Return Values
NULL Indicates end of file or an error; errno is
set to one of the following values.
x A pointer to a protoent structure.
| 13 - getprotobynumber() |
Searches the protocols database until a matching protocol number
is found or until end of file is encountered.
Format
#include <netdb.h>
struct protoent *getprotobynumber ( int *proto) ;
13.1 - Argument
proto
A pointer to a string containing the desired protocol number.
13.2 - Description
This function returns a pointer to a protoent structure
containing the data from the protocols database:
struct protoent {
char *p_name; /* official name of protocol */
char **p_aliases; /* alias list */
long p_proto; /* protocol number */
};
The members of this structure are:
p_name The official name of the protocol.
p_aliases A zero-terminated list of alternate names for
the protocol.
p_proto The protocol number.
All information is contained in a static area, so it must be
copied to be saved.
Related Functions
See also getprotoent() and getprotobyname().
13.3 - Return Values
NULL Indicates end of file or an error.
x A pointer to a protoent structure.
| 14 - getprotoent() |
Reads the next line from the protocols database.
Format
#include <netdb.h>
struct protoent *getprotoent();
14.1 - Description
This function returns a pointer to a protoent structure
containing the data from the protocols database:
struct protoent {
char *p_name; /* official name of protocol */
char **p_aliases; /* alias list */
long p_proto; /* protocol number */
};
The members of this structure are:
p_name The official name of the protocol.
p_aliases A zero-terminated list of alternate names for
the protocol.
p_proto The protocol number.
The getprotoent() function keeps a pointer in the database,
allowing successive calls to be used to search the entire file.
All information is contained in a static area, so it must be
copied to be saved.
Related Functions
See also getprotobyname() and getprotobynumber().
14.2 - Return Values
NULL Indicates an end of file or an error.
x A pointer to a protoent structure.
| 15 - getservbyname() |
Gets information on the named service from the network services
database.
Format
#include <netdb.h>
struct servent *getservbyname ( char *name, char *proto );
15.1 - Arguments
name
A pointer to a string containing the name of the service about
which information is required.
proto
A pointer to a string containing the name of the protocol (TCP or
UDP) for which to search.
15.2 - Description
This function searches sequentially from the beginning of the
file until a matching service name is found, or until end of file
is encountered. If a protocol name is also supplied, searches
must also match the protocol.
This function returns a pointer to a servent structure containing
the data from the network services database:
struct servent {
char *s_name; /* official name of service */
char **s_aliases; /* alias list */
long s_port; /* port service resides at */
char *s_proto; /* protocol to use */
};
The members of this structure are:
s_name The official name of the service.
s_aliases A zero-terminated list of alternate names for
the service.
s_port The port number at which the service resides.
Port numbers are returned in network byte
order.
s_proto The name of the protocol to use when
contacting the service.
All information is contained in a static area, so it must be
copied to be saved.
Related Functions
See also getservbyport().
15.3 - Return Values
NULL Indicates end of file or an error.
x A pointer to a servent structure.
| 16 - getservbyport() |
Gets information on the specified port from the network services
database.
Format
#include <netdb.h>
struct servent *getservbyport ( int port, char *proto );
16.1 - Arguments
port
The port number for which to search. This port number should be
specified in network byte order.
proto
A pointer to a string containing the name of the protocol (TCP or
UDP) for which to search.
16.2 - Description
This function searches sequentially from the beginning of the
file until a matching port is found, or until end of file is
encountered. If a protocol name is also supplied, searches must
also match the protocol.
This function returns a pointer to a servent structure containing
the broken-out fields of the requested line in the network
services database:
struct servent {
char *s_name; /* official name of service */
char **s_aliases; /* alias list */
long s_port; /* port service resides at */
char *s_proto; /* protocol to use */
};
The members of this structure are:
s_name The official name of the service.
s_aliases A zero-terminated list of alternate names for
the service.
s_port The port number at which the service resides.
Port numbers are returned in network byte
order.
s_proto The name of the protocol to use when
contacting the service.
All information is contained in a static area, so it must be
copied to be saved.
Related Functions
See also getservbyname().
16.3 - Return Values
NULL Indicates end of file or an error.
x A pointer to a servent structure.
| 17 - getsockname() |
Returns the name associated with a socket.
The $QIO equivalent is the IO$_SENSEMODE function with the p3
argument.
Format
#include <types.h>
#include <socket.h>
int getsockname ( int s, struct sockaddr *name, int *namelen
);
17.1 - Arguments
s
A socket descriptor created with socket() function and bound to
the socket name with the bind() function.
name
A pointer to the buffer in which getsockname() should return the
socket name.
namelen
A pointer to an integer containing the size of the buffer pointed
to by name. On return, the integer contains the actual size, in
bytes, of the name returned.
17.2 - Description
This function returns the current name for the specified socket
descriptor. The name is a format specific to the address family
(AF_INET) assigned to the socket.
The bind() function, not the getsockname() function, makes the
association of the name to the socket.
Related Functions
See also bind() and socket().
17.3 - Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
17.4 - Errors
EBADF The descriptor is invalid.
EFAULT The name argument is not a valid part of the
user address space.
ENOBUFS The system has insufficient resources to
complete the call.
ENOTSOCK The socket descriptor is invalid.
EOPNOTSUPP The operation is not supported for this
socket's protocol.
| 18 - getsockopt() |
Returns the options set on a socket.
The $QIO equivalent is the IO$_SENSEMODE function.
Format
#include <types.h>
#include <socket.h>
int getsockopt ( int s, int level, int optname, char *optval,
unsigned int *optlen );
18.1 - Arguments
s
A socket descriptor created by the socket() function.
level
The protocol level for which the socket options are desired. It
can have one of the following values:
SOL_SOCKET Get the options at the socket level.
p Any protocol number. Get the options for
protocol level specified by p. See the IN.H
header file for the various IPPROTO values.
optname
Interpreted by the protocol specified in the level. Options at
each protocol level are documented with the protocol.
For descriptions of the supported socket level options, see the
description of setsockopt() in this chapter.
optval
Points to a buffer in which the value of the specified option
should be placed by getsockopt().
optlen
Points to an integer containing the size of the buffer pointed
to by optval. On return, the integer is modified to contain the
actual size of the option value returned.
18.2 - Description
This function gets information on socket options. See the
appropriate protocol for information about available options
at each protocol level.
18.3 - Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
18.4 - Errors
EACCES The calling process does not have appropriate
permissions.
EBADF The socket descriptor is invalid.
EDOM The send and receive timeout values are too
large to fit in the timeout fields of the
socket structure.
EFAULT The address pointed to by the optval argument
is not in a valid (writable) part of the
process space, or the optlen argument is not
in a valid part of the process address space.
EINVAL The optval or optlen argument is invalid; or
the socket is shut down.
ENOBUFS The system has insufficient resources to
complete the call.
ENOTSOCK The socket descriptor is invalid.
ENOPROTOOPT The option is unknown or the protocol is
unsupported.
EOPNOTSUPP The operation is not supported by the socket
protocol.
ENOPROTOOPT The option is unknown.
ENOTSOCK The socket descriptor is invalid.
| 19 - htonl() |
Converts longwords from host byte order to network byte order.
Format
#include <in.h>
unsigned long int htonl ( unsigned long int hostlong );
19.1 - Argument
hostlong
A longword in host byte order (OpenVMS systems). All integers
on OpenVMS systems are in host byte order unless otherwise
specified.
19.2 - Description
This function converts 32-bit unsigned integers from host byte
order to network byte order.
Network byte order is the format in which data bytes are expected
to be transmitted through a network. All hosts on a network
should send data in network byte order. Not all hosts have an
internal data representation format that is identical to the
network byte order. The host byte order is the format in which
bytes are ordered internally on a specific host. The host byte
order on OpenVMS systems differs from the network byte order.
This function is most often used with internet addresses.
Network byte order places the byte with the most significant
bits at lower addresses, whereas OpenVMS systems place the most
significant bits at the highest address.
NOTE
The 64-bit return from OpenVMS Alpha systems has zero-
extended bits in the high 32 bits of R0.
19.3 - Return Value
x A longword in network byte order.
| 20 - htons() |
Converts short integers from host byte order to network byte
order.
Format
#include <in.h>
unsigned short int htons ( unsigned short int hostshort );
20.1 - Argument
hostshort
A short integer in host byte order (OpenVMS systems). All
short integers on OpenVMS systems are in host byte order unless
otherwise specified.
20.2 - Description
This function converts 16-bit unsigned integers from host byte
order to network byte order.
Network byte order is the format in which data bytes are expected
to be transmitted through a network. All hosts on a network
should send data in network byte order. Not all hosts have an
internal data representation format that is identical to the
network byte order. The host byte order is the format in which
bytes are ordered internally on a specific host. The host byte
order on OpenVMS systems differs from the network byte order.
This function is most often used with ports as returned by
getservent(). Network byte order places the byte with the most
significant bits at lower addresses, whereas OpenVMS systems
place the most significant bits at the highest address.
NOTE
The 64-bit return from OpenVMS Alpha systems has zero-
extended bits in the high 32 bits of R0.
20.3 - Return Value
x A short integer in network byte order.
Integers in network byte order cannot be used
for arithmetic computation on OpenVMS systems.
| 21 - inet_addr() |
Converts internet addresses in text form into numeric (binary)
internet addresses in dotted decimal format.
Format
#include <in.h>
#include <inet.h>
int inet_addr ( char *cp );
21.1 - Argument
cp
A pointer to a null-terminated character string containing an
internet address in the standard internet dotted-decimal format.
21.2 - Description
This function returns an internet address in network byte order
when given an ASCII (null-terminated) string that represents the
address in the internet standard dotted-decimal format as its
argument.
Internet addresses specified with the dotted-decimal format take
one of the following forms:
a.b.c.d
a.b.c
a.b
a
When four parts are specified, each is interpreted as a byte
of data and assigned, from left to right, to the 4 bytes of an
internet address. Note that when an internet address is viewed as
a 32-bit integer quantity on an OpenVMS system, the bytes appear
in binary as d.c.b.a. That is, OpenVMS bytes are ordered from
least significant to most significant.
When only one part is given, the value is stored directly in the
network address without any byte rearrangement.
All numbers supplied as parts in a dotted-decimal address can be
decimal, octal, or hexadecimal, as specified in the C language.
(That is, a leading 0x or 0X implies hexadecimal; a leading 0
implies octal; otherwise, the number is interpreted as decimal.)
NOTE
The 64-bit return from OpenVMS Alpha systems has zero-
extended bits in the high 32 bits of R0.
21.3 - Return Values
-1 Indicates that cp does not point to a proper
internet address.
x An internet address in network byte order.
| 22 - inet_lnaof() |
Returns the local network address portion of an internet address.
Format
#include <in.h>
#include <inet.h>
int inet_lnaof ( struct in_addr in );
22.1 - Argument
in
An internet address.
22.2 - Description
This function returns the local network address portion of a full
internet address.
NOTE
The 64-bit return from OpenVMS Alpha systems has zero-
extended bits in the high 32 bits of R0.
22.3 - Return Value
x The local network address portion of an
internet address, in host byte order.
| 23 - inet_makeaddr() |
Returns an internet address based on a particular local address
and a network.
Format
#include <in.h>
#include <inet.h>
struct in_addr inet_makeaddr ( int net, int lna );
23.1 - Arguments
net
An internet network address in host byte order.
lna
A local network address on network net in host byte order.
23.2 - Description
This function combines the net and lna arguments into a single
internet address.
NOTE
The 64-bit return from OpenVMS Alpha systems has zero-
extended bits in the high 32 bits of R0.
23.3 - Return Value
x An internet address in network byte order.
| 24 - inet_netof() |
Returns the internet network address portion of an internet
address.
Format
#include <in.h>
#include <inet.h>
int inet_netof ( struct in_addr in );
24.1 - Argument
in
An internet address.
24.2 - Description
This function returns the internet network address (NET) portion
of a full internet address.
NOTE
The 64-bit return from OpenVMS Alpha systems has zero-
extended bits in the high 32 bits of R0.
24.3 - Return Value
x The internet network portion of an internet
address, in host byte order.
| 25 - inet_network() |
Converts a null-terminated text string representing an internet
address into a network address in local host format.
Format
#include <in.h>
#include <inet.h>
int inet_network ( char *cp );
25.1 - Argument
cp
A pointer to an ASCII (null-terminated) character string
containing a network address in the dotted-decimal format.
25.2 - Description
This function returns an internet network address as local host
integer value when an ASCII string representing the address
in the internet standard dotted-decimal format is given as its
argument.
NOTE
The 64-bit return from OpenVMS Alpha systems has zero-
extended bits in the high 32 bits of R0.
25.3 - Return Values
-1 Indicates that cp does not point to a proper
internet network address.
x An internet network address, in local host
order.
| 26 - inet_ntoa() |
Converts an internet address into a text string representing the
address in the standard internet dotted-decimal format.
Format
#include <in.h>
#include <inet.h>
char *inet_ntoa ( struct in_addr in );
26.1 - Argument
in
An internet address in network byte order.
26.2 - Description
This function converts an internet address into an ASCII (null-
terminated) string that represents the address in standard
internet dotted-decimal format.
Because the string is returned in a static buffer that is
overwritten by subsequent calls to inet_ntoa(), you should copy
the string to a safe place.
26.3 - Return Value
x A pointer to a string containing the internet
address in dotted-decimal format.
| 27 - ioctl() |
Controls I/O requests to obtain network information.
Format
#include <ioctl.h>
int ioctl ( int s, int request, ... /* arg */ );
27.1 - Argument
s
Specifies the socket descriptor of the requested network device.
request
Specifies the type of ioctl command to be performed on the
device. The request types are grouped as follows:
o Socket operations
o File operations
o Interface operations
o ARP cache operations
o Routing table operations
Refer to <REFERENCE>(app_ioctl_commands) for a complete list of
IOCTL commands.
arg
Specifies arguments for this request. The type of arg is
dependent on the specific ioctl() request and device to which
the ioctl call is targeted.
27.2 - Description
The ioctl() function performs a variety of control functions
on devices. The functions performed are device-specific control
functions. The request and arg arguments are passed to the file
designated by fildes and then interpreted by the device driver.
The basic I/O functions are performed through the read() and
write() functions.
Encoded in an ioctl() request is whether the argument is an in
argument or an out argument, and the size of the arg argument
in bytes. The macros and definitions used to specify an ioctl()
request are located in the IOCTL.H header file.
27.3 - Return Values
-1 Error; errno is set to indicate the error.
27.4 - Errors
EBADF The fildes argument is not a valid open file
descriptor.
EINTR A signal was caught during the ioctl()
operation.
If an underlying device driver detects an error, errno might be
set to one of the following values:
EINVAL Either the request or the arg argument is not
valid.
ENOTTY Reserved for Compaq use. The fildes argument
is not associated with a character special
device, or the specified request does not
apply to the type of object that the fildes
argument references.
ENXIO The request and arg arguments are valid for
this device driver, but the service requested
cannot be performed on the particular
subdevice.
| 28 - listen() |
Converts an unconnected socket into a passive socket and
indicates that the kernel should accept incoming connection
requests directed to the socket.
Sets the maximum limit of outstanding connection requests for a
socket that is connection-oriented.
The $QIO equivalent is the IO$_SETMODE function.
Format
int listen ( int s, int backlog );
28.1 - Arguments
s
A socket descriptor of type SOCK_STREAM created using the
socket() function.
backlog
The maximum number of pending connections that can be queued
on the socket at any given time. The maximum number of pending
connections can be set using the sysconfig utility to set the
value of somaxconn. The default value for the maximum number of
pending connections is 1024.
28.2 - Description
This function creates a queue for pending connection requests
on socket s with a maximum size equal to the value of backlog.
Connections can then be accepted with the accept() function.
If a connection request arrives with the queue full (that is,
more connections pending than specified by the backlog argument),
the request is ignored so that TCP retries can succeed. If the
backlog has not cleared by the time TCP times out, the connect()
function fails with an errno indication of ETIMEDOUT.
Related Functions
See also accept(), connect(), and socket().
28.3 - Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
28.4 - Errors
EBADF The socket descriptor is invalid.
EDESTADDRREQ The socket is not bound to a local address,
and the protocol does not support listening on
an unbound socket.
EINVAL The socket is already connected, or the socket
is shut down.
ENOBUFS The system has insufficient resources to
complete the call.
ENOTSOCK The socket descriptor is invalid.
EOPNOTSUPP The referenced socket is not of a type that
supports the operation listen().
| 29 - ntohl() |
Converts longwords from network byte order to host byte order.
Format
#include <in.h>
unsigned long ntohl ( unsigned long netlong );
29.1 - Argument
netlong
A longword in network byte order. Integers in network byte order
cannot be used for arithmetic computation on OpenVMS systems.
29.2 - Description
This function converts 32-bit unsigned integers from network byte
order to host byte order.
The network byte order is the format in which data bytes are
expected to be transmitted through a network. All hosts on a
network should send data in network byte order. Not all hosts
have an internal data representation format that is identical
to the network byte order. The host byte order is the format
in which bytes are ordered internally on a specific host. The
host byte order on OpenVMS systems differs from the network byte
order.
This function is most often used with internet addresses.
Network byte order places the byte with the most significant
bits at lower addresses, whereas OpenVMS systems place the most
significant bits at the highest address.
29.3 - Return Value
x A longword in host byte order.
| 30 - ntohs() |
Converts short integers from network byte order to host byte
order.
Format
#include <in.h>
unsigned short ntohs ( unsigned short netshort );
30.1 - Argument
netshort
A short integer in network byte order. Integers in network
byte order cannot be used for arithmetic computation on OpenVMS
systems.
30.2 - Description
This function converts 16-bit unsigned integers from network byte
order to host byte order.
The network byte order is the format in which data bytes are
expected to be transmitted through a network. All hosts on a
network should send data in network byte order. Not all hosts
have an internal data representation format that is identical
to the network byte order. The host byte order is the format
in which bytes are ordered internally on a specific host. The
host byte order on OpenVMS systems differs from the network byte
order.
This function is most often used with internet ports as returned
by getservent(). Network byte order places the byte with the
most significant bits at lower addresses, whereas OpenVMS systems
place the most significant bits at the highest address.
30.3 - Return Value
x A short integer in host byte order (OpenVMS
systems).
| 31 - read() |
Reads bytes from a socket or file and places them in a user-
provided buffer.
The $QIO equivalent is the IO$_READVBLK function.
Format
#include <unixio.h>
int read ( int d, void *buffer, int nbytes );
31.1 - Arguments
d
A descriptor that must refer to a socket or file currently opened
for reading.
buffer
The address of a user-provided buffer in which the input data is
placed.
nbytes
The maximum number of bytes allowed in the read operation.
31.2 - Description
If the end of file is not reached, the read() function returns
nbytes. If the end of file occurs during the read() function, it
returns the number of bytes read.
Upon successful completion, read() returns the number of bytes
actually read and placed in the buffer.
Related Functions
See also socket().
31.3 - Return Values
x The number of bytes read and placed in the
buffer.
0 Peer has closed the connection.
-1 Error; errno is set to indicate the error.
31.4 - Errors
EBADF The socket descriptor is invalid.
ECONNRESET A connection was forcibly closed by a peer.
EFAULT The data was specified to be received into a
nonexistent or protected part of the process
address space.
EINTR A signal interrupted the recv() function
before any data was available.
EINVAL The MSG_OOB flag is set and no out-of-band
data is available.
ENOBUFS The system has insufficient resources to
complete the call.
ENOMEM The system did not have sufficient memory to
fulfill the request.
ENOTCONN A receive is attempted on a connection-
oriented socket that is not connected.
ENOTSOCK The socket descriptor is invalid.
EOPNOTSUPP The specified flags are not supported for this
socket type or protocol.
EWOULDBLOCK The socket is marked nonblocking, and no data
is waiting to be received.
| 32 - recv() |
Receives bytes from a connected socket and places them into a
user-provided buffer.
The $QIO equivalent is the IO$_READVBLK function.
Format
#include <types.h>
#include <socket.h>
int recv ( int s, char *buf, int len, int flags );
32.1 - Arguments
s
A socket descriptor created as the result of a call to accept()
or connect().
buf
A pointer to a user-provided buffer into which received data will
be placed.
len
The size of the buffer pointed to by buf.
flags
A bit mask that can contain one or more of the following
flags. The mask is built by using a logical OR operation on the
appropriate values.
Flag Description
MSG_OOB Allows you to receive out-of-band data.
If out-of-band data is available, it is read
first. If no out-of-band data is available,
the MSG_OOB flag is ignored.
Use the send(), sendmsg(), and sendto()
functions to send out-of-band data.
MSG_PEEK Allows you to examine data in the receive
buffer without removing it from the system's
buffers.
32.2 - Description
This function receives data from a connected socket. To receive
data on an unconnected socket, use the recvfrom() or recvmsg()
functions. The received data is placed in the buffer buf.
Data is sent by the socket's peer using the send, sendmsg(),
sendto(), or write() functions.
Use the select() function to determine when more data arrives.
If no data is available at the socket, the receive call waits for
data to arrive, unless the socket is nonblocking. If the socket
is nonblocking, a -1 is returned with the external variable errno
set to EWOULDBLOCK.
Related Functions
See also read(), send(), sendmsg(), sendto(), and socket().
32.3 - Return Values
x The number of bytes received and placed in
buf.
0 Peer has closed its send side of the
connection.
-1 Error; errno is set to indicate the error.
32.4 - Errors
EBADF The socket descriptor is invalid.
ECONNRESET A connection was forcibly closed by a peer.
EFAULT The data was specified to be received into a
nonexistent or protected part of the process
address space.
EINTR A signal interrupted the recv() function
before any data was available.
EINVAL The MSG_OOB flag is set and no out-of-band
data is available.
ENOBUFS The system has insufficient resources to
complete the call.
ENOMEM The system did not have sufficient memory to
fulfill the request.
ENOTCONN A receive is attempted on a connection-
oriented socket that is not connected.
ENOTSOCK The socket descriptor is invalid.
EOPNOTSUPP The specified flags are not supported for this
socket type or protocol.
EWOULDBLOCK The socket is marked nonblocking, and no data
is waiting to be received.
| 33 - recvfrom() |
Receives bytes for a socket from any source.
Format
#include <types.h>
#include <socket.h>
int recvfrom ( int s, char *buf, int len, int flags, struct
sockaddr *from, int *fromlen) ;
33.1 - Arguments
s
A socket descriptor created with the socket() function and
bound to a name using the bind() function or as a result of the
accept() function.
buf
A pointer to a buffer into which received data is placed.
len
The size of the buffer pointed to by buf.
flags
A bit mask that can contain one or more of the following
flags. The mask is built by using a logical OR operation on the
appropriate values.
Flag Description
MSG_OOB Allows you to receive out-of-band data. If
out-of-band data is available, it is read
first.
If no out-of-band data is available, the
MSG_OOB flag is ignored. To send out-of-band
data, use the send(), sendmsg(), and sendto()
functions.
MSG_PEEK Allows you to examine the data that is next in
line to be received without actually removing
it from the system's buffers.
from
A buffer that the recvfrom() function uses to place the address
of the sender who sent the data.
If from is non-null, the address is returned. If from is null,
the address is not returned.
fromlen
Points to an integer containing the size of the buffer pointed to
by from. On return, the integer is modified to contain the actual
length of the socket address structure returned.
33.2 - Description
This function allows a named, unconnected socket to receive
data. The data is placed in the buffer pointed to by buf, and
the address of the sender of the data is placed in the buffer
pointed to by from if from is non-null. The structure that from
points to is assumed to be as large as the sockaddr structure.
To receive bytes from any source, the socket does not need to be
connected.
You can use the select() function to determine if data is
available.
If no data is available at the socket, the recvfrom() call
waits for data to arrive, unless the socket is nonblocking. If
the socket is nonblocking, a -1 is returned with the external
variable errno set to EWOULDBLOCK.
Related Functions
See also read(), send(), sendmsg(), sendto(), and socket().
33.3 - Return Values
x The number of bytes of data received and
placed in buf.
0 Successful completion.
-1 Error; errno is set to indicate the error.
33.4 - Errors
EBADF The socket descriptor is invalid.
ECONNRESET A connection was forcibly closed by a peer.
EFAULT A valid message buffer was not specified.
Nonexistent or protected address space is
specified for the message buffer.
EINTR A signal interrupted the recvfrom() function
before any data was available.
EINVAL The MSG_OOB flag is set, and no out-of-band
data is available.
ENOBUFS The system has insufficient resources to
complete the call.
ENOMEM The system did not have sufficient memory to
fulfill the request.
ENOTCONN A receive is attempted on a connection-
oriented socket that is not connected.
ENOTSOCK The socket descriptor is invalid.
EOPNOTSUPP The specified flags are not supported for this
socket type.
ETIMEDOUT The connection timed out when trying to
establish a connection or when a transmission
timed out on an active connection.
EWOULDBLOCK The NBIO (nonblocking) flag is set for the
socket descriptor and the process delayed
during the write operation.
| 34 - recvmsg() |
Receives bytes on a socket and places them into scattered
buffers.
Format
#include <types.h>
#include <socket.h>
int recvmsg ( int s, struct msghdr msg, int flags ); (BSD
Version 4.4)
int recvmsg ( int s, struct omsghdr msg, int flags ); (BSD
Version 4.3)
34.1 - Arguments
s
A socket descriptor created with the socket() function.
msg
flags
A bit mask that can contain one or more of the following
flags. The mask is built by using a logical OR operation on the
appropriate values.
Flag Description
MSG_OOB Allows you to receive out-of-band data.
If out-of-band data is available, it is read
first. If no out-of-band data is available,
the MSG_OOB flag is ignored. Use send(),
sendmsg(), and sendto() functions to send
out-of-band data.
MSG_PEEK Allows you to peek at the data that is next in
line to be received without actually removing
it from the system's buffers.
34.2 - Description
You can use this function with any socket, whether or not it
is in a connected state. It receives data sent by a call to
sendmsg(), send(), or sendto(). The message is scattered into
several user buffers if such buffers are specified.
To receive data, the socket does not need to be connected to
another socket.
When the ioveciovcnt array specifies more than one buffer, the
input data is scattered into iovcnt buffers as specified by the
members of the iovec array:
iov0, iov1, ..., ioviovcnt
When a message is received, it is split among the buffers by
filling the first buffer in the list, then the second, and so on,
until either all of the buffers are full or there is no more data
to be placed in the buffers.
You can use the select() function to determine when more data
arrives.
Related Functions
See also read(), send(), and socket().
34.3 - Return Values
x The number of bytes returned in the msg_iov
buffers.
0 Successful completion.
-1 Error; errno is set to indicate the error.
34.4 - Errors
EBADF The socket descriptor is invalid.
ECONNRESET A connection was forcibly closed by a peer.
EFAULT The message argument is not in a readable or
writable part of user address space.
EINTR This function was interrupted by a signal
before any data was available.
EINVAL The MSG_OOB flag is set, and no out-of-band
data is available.
The value of the msg_iovlen member of the
Lmsghdr structure is less than or equal to
zero or is greater than IOV_MAX.
ENOBUFS The system has insufficient resources to
complete the call.
ENOMEM The system did not have sufficient memory to
fulfill the request.
ENOTCONN A receive is attempted on a connection-
oriented socket that is not connected.
ENOTSOCK The socket descriptor is invalid.
EOPNOTSUPP The specified flags are not supported for this
socket type.
EWOULDBLOCK The socket is marked nonblocking, and no data
is ready to be received.
| 35 - select() |
Allows you to poll or check a group of sockets for I/O activity.
This function indicates which sockets are ready to be read or
written, or which sockets have an exception pending.
Format
#include <time.h>
int select ( int nfds, int *readfds, int *writefds, int
*execptfds, struct timeval *timeout );
35.1 - Arguments
nfds
Specifies the number of open objects that may be ready for
reading or writing or that have exceptions pending. The nfds
argument is normally limited to FD_SETSIZE. Note that a single
process can have a maximum of 65535 simultaneous channels
(including sockets) on OpenVMS Alpha systems, and a maximum of
2047 on OpenVMS VAX systems.
readfds
A pointer to an array of bits, organized as integers, that should
be examined for read readiness. If bit n of the longword is set,
socket descriptor n is checked to see whether it is ready to be
read. All bits set in the bit mask must correspond to the file
descriptors of sockets. The select() function cannot be used on
normal files.
On return, the array to which readfds points contains a bit mask
of the sockets that are ready for reading. Only bits that were
set on entry to the select() function can be set on exit.
writefds
A pointer to an array of bits, organized as integers, that should
be examined for write readiness. If bit n of the longword is
set, socket descriptor n is checked to see whether it is ready
to be written to. All bits set in the bit mask must correspond to
socket descriptors.
On return, the array to which writefds points contains a bit mask
of the sockets that are ready for writing. Only bits that were
set on entry to the select() function are set on exit.
exceptfds
A pointer to an array of bits, organized as integers, that
is examined for exceptions. If bit n of the longword is set,
socket descriptor n is checked to see whether it has any pending
exceptions. All bits set in the bit mask must correspond to the
file descriptors of sockets.
On return, the array exceptfds pointer contains a bit mask of the
sockets that have exceptions pending. Only bits that were set on
entry to the select() function can be set on exit.
timeout
The length of time that the select() function should examine the
sockets before returning. If one of the sockets specified in the
readfds, writefds, and exceptfds bit masks is ready for I/O, the
select() function returns before the timeout period expires.
The timeout argument points to a timeval structure.
35.2 - Description
This function determines the I/O status of the sockets specified
in the various mask arguments. It returns when a socket is ready
to be read or written, when the timeout period expires, or when
exceptions occur. If timeout is a non-null pointer, it specifies
a maximum interval to wait for the selection to complete.
If the timeout argument is null, the select() function blocks
indefinitely until a selected event occurs. To effect a poll,
the value for timeout should be non-null, and should point to a
zero-value structure.
If a process is blocked on a select() function while waiting for
input for a socket and the sending process closes the socket,
then the select() function notes this as an event and unblocks
the process. The descriptors are always modified on return if the
select() function returns because of the timeout.
NOTE
When the socket option SO_OOBINLINE is set on the device
socket, the select() function on both read and exception
events returns the socket mask that is set on both the read
and the exception mask. Otherwise, only the exception mask
is set.
Related Functions
See also accept(), connect(), read(), recv(), recvfrom(),
recvmsg(), send(), sendmsg(), sendto(), and write().
35.3 - Return Values
n The number of sockets ready for I/O or pending
exceptions. This value matches the number
of returned bits that are set in all output
masks.
0 The select() function timed out before any
socket became ready for I/O.
-1 Error; errno is set to indicate the error.
35.4 - Errors
EBADF One or more of the I/O descriptor sets
specified an invalid file descriptor.
EINTR A signal was delivered before the time limit
specified by the timeout argument expired and
before any of the selected events occurred.
EINVAL The time limit specified by the timeout
argument is invalid.
The nfds argument is less than zero, or
greater than or equal to FD_SETSIZE.
EAGAIN Allocation of internal data structures failed.
A later call to the select() function may
complete successfully.
ENETDOWN TCP/IP Services was not started.
ENOTSOCK The socket descriptor is invalid.
| 36 - send() |
Sends bytes through a socket to its connected peer.
The $QIO equivalent is the IO$_WRITEVBLK function.
Format
#include <types.h>
#include <socket.h>
int send ( int s, char *msg, int len, int flags );
36.1 - Arguments
s
A socket descriptor created with the socket() function that was
connected to another socket using the accept() or connect()
function.
msg
A pointer to a buffer containing the data to be sent.
len
The length, in bytes, of the data pointed to by msg.
flags
Can be either 0 or MSG_OOB. If it is MSG_OOB, the data is sent
out of band. Data can be received before other pending data on
the receiving socket if the receiver also specifies MSG_OOB in
the flag argument of its recv() or recvfrom() call.
36.2 - Description
You can use this function only on connected sockets. To send
data on an unconnected socket, use the sendmsg() or sendto()
function. The send() function passes data along to its connected
peer, which can receive the data by using the recv() or read()
function.
If there is no space available to buffer the data being sent
on the receiving end of the connection, send() normally blocks
until buffer space becomes available. If the socket is defined as
nonblocking, however, send() fails with an errno indication of
EWOULDBLOCK. If the message is too large to be sent in one piece,
and the socket type requires that messages be sent atomically
(SOCK_DGRAM), send() fails with an errno indication of EMSGSIZE.
No indication of failure to deliver is implicit in a send(). All
errors (except EWOULDBLOCK) are detected locally. You can use the
select() function to determine when it is possible to send more
data.
Related Functions
See also read(), recv(), recvmsg(), recvfrom(), getsockopt(),
and socket().
36.3 - Return Values
n The number of bytes sent. This value normally
equals len.
-1 Error; errno is set to indicate the error.
36.4 - Errors
EBADF The socket descriptor is invalid.
ECONNRESET A connection was forcibly closed by a peer.
EDESTADDRREQ The socket is not connection-oriented, and no
peer address is set.
EFAULT The message argument is not in a readable or
writable part of the user address space.
EINTR A signal interrupted the send() before any
data was transmitted.
EMSGSIZE The message is too large to be sent all at
once, as the socket requires.
ENETDOWN The local network connection is not
operational.
ENETUNREACH The destination network is unreachable.
ENOBUFS The system has insufficient resources to
complete the call.
ENOTCONN The socket is not connected or has not had the
peer prespecified.
ENOTSOCK The socket descriptor is invalid.
EOPNOTSUPP The socket argument is associated with a
socket that does not support one or more of
the values set in flags.
EWOULDBLOCK The socket is marked nonblocking, and no space
is available for the send() function.
| 37 - sendmsg() |
Sends gathered bytes through a socket to any other socket.
Format
#include <types.h>
#include <socket.h>
int sendmsg ( int s, struct msghdr *msg, int flags ); (BSD
Version 4.4)
int sendmsg ( int s, struct omsghdr *msg, int flags ); (BSD
Version 4.3)
37.1 - Arguments
s
A socket descriptor created with the socket() function.
msg
A pointer to a msghdr structure containing the message to be
sent.
The msg_iov field of the msghdr structure is used as a series of
buffers from which data is read in order until msg_iovlen bytes
have been obtained.
flags
Can be either 0 or MSG_OOB. If it is equal to MSG_OOB, the data
is sent out of band. Data can be received before other pending
data on the receiving socket if the receiver specifies a flag of
MSG_OOB.
37.2 - Description
You can use this function on any socket to send data to any named
socket. The data in the msg_iov field of the msghdr structure
is sent to the socket whose address is specified in the msg_name
field of the structure. The receiving socket gets the data using
the read(), recv(), recvfrom(), or recvmsg() function. When the
iovec array specifies more than one buffer, the data is gathered
from all specified buffers before being sent.
If no space is available to buffer the data on the receiving end
of the connection, the sendmsg() function blocks until buffer
space becomes available. If the socket is defined as nonblocking,
the sendmsg() function fails with an errno indication of
EWOULDBLOCK. If the message is too large to be sent in one piece
and the socket type requires that messages be sent atomically
(SOCK_DGRAM), the sendmsg() fails with an errno indication of
EMSGSIZE.
If the address specified is an INADDR_BROADCAST address, the
SO_BROADCAST socket option must be set and the process must
have a system UIC, OPER, SYSPRV, or BYPASS privilege for the
I/O operation to succeed.
No indication of failure to deliver is implicit in the sendmsg()
function. All errors (except EWOULDBLOCK) are detected locally.
You can use the select() function to determine when it is
possible to send more data.
Related Functions
See also read(), recv(), recvfrom(), recvmsg(), socket(), and
getsockopt().
37.3 - Return Values
n The number of bytes sent.
-1 Error; errno is set to indicate the error.
37.4 - Errors
ENOTSOCK The socket descriptor is invalid.
EFAULT An invalid user space address is specified for
a argument.
EMSGSIZE The socket requires that messages be sent
atomically, but the size of the message to be
sent makes this impossible.
EWOULDBLOCK Blocks if the system does not have enough
space for buffering the user data.
| 38 - sendto() |
Sends bytes through a socket to any other socket.
The $QIO equivalent is the IO$_WRITEVBLK function.
Format
#include <types.h>
#include <socket.h>
int sendto ( int s, char *msg, int len, int flags, struct
sockaddr *to, int tolen );
38.1 - Arguments
s
A socket descriptor created with the socket() function.
msg
A pointer to a buffer containing the data to be sent.
len
The length of the data pointed to by the msg argument.
flags
Can be either 0 or MSG_OOB. If it is MSG_OOB, the data is sent
out of band. Data can be received before other pending data on
the receiving socket if the receiver specifies MSG_OOB in its
flag argument of its recv(), recvfrom() or recvmsg() call.
to
Points to the address structure of the socket to which the data
is to be sent.
tolen
The length of the address pointed to by the to argument.
38.2 - Description
This function can be used on sockets to send data to named
sockets. The data in the msg buffer is sent to the socket whose
address is specified in the to argument, and the address of
socket s is provided to the receiving socket. The receiving
socket gets the data using the read(), recv(), recvfrom(), or
recvmsg() function.
If there is no space available to buffer the data being sent
on the receiving end of the connection, the sendto() function
blocks until buffer space becomes available. If the socket is
defined as nonblocking, the sendto() function fails with an errno
indication of EWOULDBLOCK. If the message is too large to be sent
in one piece and the socket type requires that messages be sent
atomically (SOCK_DGRAM), the sendto() function fails with an
errno indication of EMSGSIZE.
No indication of failure to deliver is implicit in a sendto().
All errors (except EWOULDBLOCK) are detected locally. You can use
the select() function to determine when it is possible to send
more data.
If the address specified is a INADDR_BROADCAST address, then the
SO_BROADCAST socket option must have been set and the process
must have SYSPRV or BYPASS privilege for the I/O operation to
succeed.
Related Functions
See also read(), recv(), recvfrom(), recvmsg(), socket(), and
getsockopt().
38.3 - Return Values
n The number of bytes sent. This value normally
equals len.
-1 Error; errno is set to indicate the error.
38.4 - Errors
EAFNOSUPPORT Addresses in the specified address family
cannot be used with this socket.
EBADF The socket descriptor is invalid.
ECONNRESET A connection was forcibly closed by a peer.
EDESTADDRREQ You did not specify a destination address for
the connectionless socket and no peer address
is set.
EFAULT An invalid user space address is specified for
a argument.
EHOSTUNREACH The destination host is unreachable.
EINTR A signal interrupted sendto() before any data
was transmitted.
EINVAL The dest_len argument is not a valid size for
the specified address family.
EISCONN The connection-oriented socket for which a
destination address was specified is already
connected.
EMSGSIZE The message is too large to be sent all at
once, as the socket requires.
ENETDOWN The local network connection is not
operational.
ENETUNREACH The destination network is unreachable.
ENOBUFS The system has insufficient to complete the
call.
ENOMEM The system did not have sufficient memory to
fulfill the request.
ENOTCONN The socket is connection-oriented but is not
connected.
ENOTSOCK The socket descriptor is invalid.
EOPNOTSUPP The socket argument is associated with a
socket that does not support one or more of
the values set in flags.
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 socket is marked nonblocking, and no space
is available for the sendto() function.
| 39 - setsockopt() |
Sets options on a socket.
The $QIO equivalent is the IO$_SETMODE function.
Format
#include <types.h>
#include <socket.h>
int setsockopt ( int s, int level, int optname, char *optval,
int optlen );
39.1 - Arguments
s
A socket descriptor created by the socket() function.
level
The protocol level for which the socket options are to be
modified. It can have one of the following values:
SOL_SOCKET Set the options at the socket level.
p Any protocol number. Set the options for
protocol level p. See the IN.H header file
for the various IPPROTO values.
optname
Interpreted by the protocol specified in level. Options at each
protocol level are documented with the protocol.
Refer to:
o <REFERENCE>(op_setsock_tab) for a list of socket options
o <REFERENCE>(tcp_set_tab_opt) for a list of TCP options
o <REFERENCE>(ip_set_tab_opt) for a list of IP options
optval
Points to a buffer containing the arguments of the specified
option.
All socket-level options other than SO_LINGER 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 the
SOCKET.H header file. This structure specifies the desired state
of the option and the linger interval. The option value for the
SO_LINGER command is the address of a linger structure.
If the socket promises the reliable delivery of data and l_onoff
is nonzero, the system blocks the process on the close() attempt
until it is able to transmit the data or until it decides it is
unable to deliver the information. A timeout period, called the
linger interval, is specified in l_linger.
If l_onoff is set to zero and a close() is issued, the system
processes the close in a manner that allows the process to
continue as soon as possible.
optlen
An integer specifying the size of the buffer pointed to by
optval.
39.2 - Description
This function manipulates options associated with a socket.
Options can exist at multiple protocol levels. They are always
present at the uppermost socket level.
When manipulating socket options, specify the level at which the
option resides and the name of the option. To manipulate options
at the socket level, specify the value of level as SOL_SOCKET. To
manipulate options at any other level, supply the protocol number
of the appropriate protocol controlling the option. For example,
to indicate that an option is to be interpreted by TCP, set the
value for level argument to the protocol number (IPPROTO_TCP) of
TCP. See the IN.H header file for the various IPPROTO values.
39.3 - Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
39.4 - Errors
EACCES The calling process does not have appropriate
permissions.
EBADF The descriptor is invalid.
EDOM The send and receive timeout values are too
large to fit in the timeout fields of the
socket structure.
EINVAL The optlen argument is invalid.
EISCONN The socket is already connected; the specified
option cannot be set when the socket is in the
connected state.
EFAULT The optval argument is not in a readable part
of the user address space.
ENOBUFS The system had insufficient resources to
complete the call.
ENOPROTOOPT The option is unknown.
ENOTSOCK The socket descriptor is invalid.
EFAULT The optname argument is invalid.
| 40 - shutdown() |
Shuts down all or part of a bidirectional connection on a socket.
This function does not allow further receives or sends, or both.
The $QIO equivalent is the IO$_DEACCESS function with the IO$M_
SHUTDOWN function modifier.
Format
#include <socket.h>
int shutdown ( int s, int how) ;
40.1 - Arguments
s
A socket descriptor that is in a connected state as a result of a
previous call to either connect() or accept().
how
How the socket is to be shut down. Use one of the following
values:
0 Do not allow further calls to recv() on the socket.
1 Do not allow further calls to send() on the socket.
2 Do not allow further calls to both send() and recv().
40.2 - Description
This function allows communications on a socket to be shut down
one piece at a time rather than all at once. Use the shutdown()
function to create unidirectional connections rather than the
normal bidirectional (full-duplex) connections.
Related Functions
See also connect() and socket().
40.3 - Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
40.4 - Errors
EBADF The socket descriptor is invalid.
EINVAL The how argument is invalid.
ENOBUFS The system has insufficient resources to
complete the call.
ENOTCONN The specified socket is not connected.
ENOTSOCK The socket descriptor is invalid.
| 41 - 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 );
41.1 - 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 <REFERENCE>(EX_TCP_ASRV_SOCK).
type
The socket types are:
o SOCK_STREAM - Provides sequenced, reliable, two-way,
connection-based byte streams with an available out-of-band
data transmission mechanism.
o SOCK_DGRAM - Supports datagrams (connectionless, unreliable
data transmission mechanism).
o 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.
41.2 - 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().
41.3 - Return Values
x A file descriptor that refers to the socket
descriptor.
-1 Error; errno is set to indicate the error.
41.4 - 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.
| 42 - 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 );
42.1 - 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.
42.2 - Description
This function attempts to write a buffer of data to a socket or
file.
Related Functions
See also socket().
42.3 - Return Values
x The number of bytes written to the socket or
file.
-1 Error; errno is set to indicate the error.
42.4 - 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:
o The STREAM or multiplexer referenced
by d is linked (directly or indirectly)
downstream from a multiplexer.
o The iov_count argument value was less than
or equal to zero or greater than IOV_MAX.
o The sum of the iov_len values in the iov
array overflows a ssize_t data type.
o The file position pointer associated with
the d argument was a negative value.
o 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.
| 43 - $ASSIGN |
Provides a calling process with an I/O channel, thereby allowing
the calling process to perform I/O operations on the network
pseudodevice.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$ASSIGN devnam, chan, [acmode], [mbxnam], [flags]
C Prototype
int sys$assign (void *devnam, unsigned short int *chan,
unsigned int acmode, void *mbxnam,...);
Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. All system services return (by
immediate value) a condition value in R0. Condition values that
can be returned by this service are listed under Condition Values
Returned.
43.1 - Arguments
devnam
OpenVMS usage:device_name
type: character-coded text string
access: read only
mechanism: by 32- or 64-bit descriptor-fixed-length string
descriptor (Alpha)
by 32-bit descriptor-fixed-length string descriptor
(VAX)
Name of the device to which $ASSIGN is to assign a channel. The
devnam argument is the 32- or 64-bit address (on Alpha systems)
or the 32-bit address (on VAX systems) of a character string
descriptor pointing to the network pseudodevice name string
(either TCPIP$DEVICE: or SYS$NET:).
chan
OpenVMS usage:channel
type: word (unsigned)
access: write only
mechanism: by 32- or 64-bit reference (Alpha)
by 32-bit reference (VAX)
Number of the channel that is assigned. The chan argument is the
32- or 64-bit address (on Alpha systems) or the 32-bit address
(on VAX systems) of a word into which $ASSIGN writes the channel
number.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode to be associated with the channel. I/O operations on
the channel can be performed only from equal and more privileged
access modes. The $PSLDEF macro defines the following symbols for
the four access modes:
Access
Symbol Mode Numeric Value
PSL$C_KERNEL Kernel 0
PSL$C_EXEC Executive 1
PSL$C_SUPER Supervisor 2
PSL$C_USER User 3
mbxnam
OpenVMS usage:device_name
type: character-coded text string
access: read only
mechanism: by 32- or 64-bit descriptor-fixed-length string
descriptor (Alpha)
by 32-bit descriptor-fixed-length string descriptor
(VAX)
This argument is not used.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
An optional device-specific argument. The flags argument is a
longword bit mask. For more information about the applicability
of the flags argument for a particular device, refer to the
OpenVMS I/O User's Reference Manual.
43.2 - Description
The $ASSIGN system service establishes a path to a device but
does not check whether the calling process has the capability
to do I/O operations to the device. The device drivers may apply
privilege and protection restrictions. The calling process must
have NETMBX privilege to assign a channel.
System dynamic memory is required for the target device, and the
I/O byte limit quota from the process buffer is used.
When a channel is assigned to the TCPIP$DEVICE: template network
device, the network software creates a new device called BGn,
where n is a unique unit number. The corresponding channel number
is used in any subsequent operation requests for that device.
When the auxiliary server creates a process for a service with
the LISTEN flag set, the server creates a device socket. In
order for your application to receive the device socket, assign
a channel to SYS$NET, which is the logical name of a network
pseudodevice, and perform an appropriate $QIO(IO$_SETMODE)
operation.
Channels remain assigned either until they are explicitly
deassigned with the Deassign I/O Channel ($DASSGN) service or,
if they are user-mode channels, until the image that assigned the
channel exits.
43.3 - Condition Values Returned
SS$_NORMAL The service completed successfully.
SS$_ACCVIO The caller cannot read the device string or
string descriptor, or the caller cannot write
the channel number.
SS$_DEVALLOC The device is allocated to another process.
SS$_DEVLSTFULL The system maximum number of BG: device units
has been reached.
SS$_EXQUOTA The process has exceeded its buffered I/O byte
limit (BIOLM) quota.
SS$_IVDEVNAM No device name was specified, the logical name
translation failed, or the device name string
contains invalid characters.
SS$_IVLOGNAM The device name string has a length of zero or
has more than 63 characters.
SS$_NOIOCHAN No I/O channel is available for assignment.
SS$_NOSUCHDEV The specified device does not exist.
| 44 - $CANCEL |
Cancels all pending I/O requests on a specified channel.
Related Functions
The equivalent Sockets API function is close().
Format
SYS$CANCEL chan
C Prototype
int sys$cancel (unsigned short int chan);
Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. All system services return (by
immediate value) a condition value in R0. Condition values that
can be returned by this service are listed under Condition Values
Returned.
44.1 - Arguments
chan
OpenVMS usage:channel
type: word (unsigned)
access: read only
mechanism: by value
I/O channel on which I/O is to be canceled. The chan argument is
a word containing the channel number.
44.2 - Description
To cancel I/O on a channel, the access mode of the calling
process must be equal to or more privileged than the access mode
of the process that made the original channel assignment.
The $CANCEL service requires system dynamic memory and uses the
process's buffered I/O limit (BIOLM) quota.
When a request currently in progress is canceled, the driver is
notified immediately. Actual cancellation may or may not occur
immediately, depending on the logical state of the driver. When
cancellation does occur, the action taken for I/O in progress is
similar to that taken for queued requests. For example:
o The specified event flag is set.
o The first word of the I/O status block, if specified, is set
to SS$_CANCEL if the I/O request is queued, or to SS$_ABORT if
the I/O operation is in progress.
o If the asynchronous system trap (AST) is specified, it is
queued.
For proper synchronization between this service and the actual
canceling of I/O requests to take place, the issuing process
must wait for the I/O process to complete normally. Note that
the I/O has been canceled. Outstanding I/O requests are canceled
automatically at image exit.
44.3 - Condition Values Returned
SS$_NORMAL The service completed successfully.
SS$_ABORT A physical line went down during a network
connect operation.
SS$_CANCEL The I/O operation was canceled by executing a
$CANCEL system service.
SS$_EXQUOTA The process has exceeded its buffered I/O
limit (BIOLM) quota.
SS$_INSFMEM Insufficient system dynamic memory to cancel
the I/O.
SS$_IVCHAN An invalid channel was specified (that is, a
channel number of 0 or a number larger than
the number of channels available).
SS$_NOPRIV The specified channel is not assigned or was
assigned from a more privileged access mode.
| 45 - $DASSGN |
Deassigns (releases) an I/O channel previously acquired using the
Assign I/O Channel ($ASSIGN) service.
Related Functions
The equivalent Sockets API function is close().
Format
SYS$DASSGN chan
C Prototype
int sys$dassgn (unsigned short int chan);
Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. All system services return (by
immediate value) a condition value in R0. Condition values that
can be returned by this service are listed under Condition Values
Returned.
45.1 - Arguments
chan
OpenVMS usage:channel
type: word (unsigned)
access: read only
mechanism: by value
Number of the I/O channel to be deassigned. The chan argument is
a word containing this number.
45.2 - Description
After all communication is completed, use the $DASSGN system
service to free an I/O channel. A $DASSGN operation executed
on a channel associated with a network pseudodevice does the
following:
o Ends all pending operations to send or receive data at $QIO
level ($CANCEL system service).
o Clears the port associated with the channel. When executing
the $DASSGN system service for TCP sockets, the socket remains
until the connection is closed on both the local and remote
sides.
o Ends all communications with the network pseudodevice that the
I/O channel identifies.
o Frees the channel associated with the network pseudodevice. An
I/O channel can be deassigned only from an access mode equal
to or more privileged than the access mode from which the
original channel assignment was made.
I/O channels assigned from user mode are automatically deassigned
at image exit.
NOTE
Even after a $DASSGN has been issued, a TCP socket may
remain until the TCP close timeout interval expires. The
default and maximum timeout interval is either 10 minutes
if the peer host is not responding or 30 seconds after
acknowledging the socket close. Although the TCP socket
is open, you cannot make a reference to that socket after
issuing a $DASSGN.
45.3 - Condition Values Returned
SS$_NORMAL The service completed successfully.
SS$_IVCHAN An invalid channel number was specified (that
is, a channel number of zero or a number
larger than the number of channels available).
SS$_NOPRIV The specified channel is not assigned or is
assigned from a more privileged access mode.
| 46 - $QIO |
Queues an I/O request to a channel associated with a network
pseudodevice.
The $QIO service is completed asynchronously; that is, it returns
to the caller immediately after queuing the I/O request, without
waiting for the I/O operation to be completed. )
For synchronous completion, use the Queue I/O Request and Wait
($QIOW) service. The $QIOW service is identical to the $QIO
service, except the $QIOW returns to the caller after the I/O
operation has completed.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$QIO [efn],chan,func, [iosb],[astadr],[astprm],
[p1],[p2],[p3],[p4], [p5],[p6]
C Prototype
int sys$qio (unsigned int efn, unsigned short int chan,
unsigned int func, struct _iosb *iosb, void
(*astadr)(__unknown_params), __int64 astprm, void
*p1, __int64 p2, __int64 p3, __int64 p4, __int64
p5, __int64 p6);
Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. All system services return (by
immediate value) a condition value in R0. Condition values that
can be returned by this service are listed under Condition Values
Returned.
46.1 - Arguments
efn
OpenVMS usage:ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Event flag that $QIO sets when the I/O operation completes. The
efn argument is a longword value containing the number of the
event flag, however, $QIO uses only the low-order byte.
If efn is not specified, event flag 0 is set.
The specified event flag is set if the service terminates without
queuing an I/O request.
chan
OpenVMS usage:channel
type: word (unsigned)
access: read only
mechanism: by value
I/O channel that is assigned to the device to which the request
is directed. The chan argument is a word value containing the
number of the I/O channel.
func
OpenVMS usage:function_code
type: longword (unsigned)
access: read only
mechanism: by value
Function codes and function modifiers specifying the operation
to be performed. The func argument is a longword containing the
function code.
For information about the network pseudodevice and TELNET device
function codes and modifiers, see Network Pseudodevice Driver
Functions and <REFERENCE>(TEL_FUNC_CODE).
iosb
OpenVMS usage:io_status_block
type: quadword (unsigned)
access: write only
mechanism: by 32-bit reference or 64-bit reference (Alpha)
by 32-bit reference (VAX)
I/O status block to receive the final completion status of the
I/O operation. The iosb is the address of the quadword I/O status
block.
When the $QIO begins executing, it clears the event flag. The
$QIO also clears the quadword I/O status block if the iosb
argument is specified.
Although the iosb argument is optional, Compaq strongly
recommends that you specify it, for the following reasons:
o If you are using an event flag to signal the completion of
the service, you can test the I/O status block for a condition
value to be sure that the event flag was not set by an event
other than service completion.
o If you are using the $SYNCH service to synchronize completion
of the service, the I/O status block is a required argument
for $SYNCH.
o The condition value returned in R0 and the condition value
returned in the I/O status block provide information about
different aspects of the call to the $QIO service. The
condition value returned in R0 provides information about the
success or failure of the service call itself; the condition
values returned in the I/O status block give information on
the success or failure of the service operation. Therefore,
to access the success or failure of the $QIO call, check the
condition values returned in both the R0 and the I/O status
block.
astadr
OpenVMS usage:ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by 32- or 64-bit reference (Alpha)
by 32-bit reference (VAX)
AST service routine to be executed when the I/O completes. The
astadr argument is the address of the AST routine.
The AST routine executes at the access mode of the caller of
$QIO.
astprm
OpenVMS usage:user_arg
type: quadword unsigned (Alpha); longword unsigned (VAX)
access: read only
mechanism: by 32- or 64-bit value (Alpha)
by 32-bit value (VAX)
AST parameter to be passed to the AST service routine. On Alpha
systems, the astprm argument is a quadword value containing the
AST parameter. On VAX systems, the astprm argument is a longword
value containing the AST parameter.
p1 to p6
OpenVMS usage:varying_arg
type: quadword unsigned (Alpha); longword unsigned (VAX)
access: read only
mechanism: by 32- or 64-bit reference or by 64-bit value
depending on the I/O function (Alpha)
by 32-bit reference or by 32-bit value depending on
the I/O function (VAX)
Optional device- and function-specific I/O request arguments. The
parameter values contained in these arguments vary according to
the function for which they are used. See Network Pseudodevice
Driver I/O Functions for descriptions of the network pseudodevice
driver I/O function codes; see List Codes for the p5 Item through
Service Type Codes for related TELNET device driver I/O function
codes.
46.2 - Description
The Queue I/O Request service operates only on assigned I/O
channels and only from access modes that are equal to or more
privileged than the access mode from which the original channel
assignment was made.
For TCP/IP Services, $QIO uses the following system resources:
o The process's AST limit (ASTLM) quota, if an AST service
routine is specified.
o System dynamic memory, which is required to queue the I/O
request. System dynamic memory requirements are protocol
specific.
o Additional memory, on a device-dependent basis.
For $QIO, completion can be synchronized as follows:
o By specifying the astadr argument to have an AST routine
execute when the I/O is completed.
o By calling the $SYNCH synchronize service to await completion
of the I/O operation. (If you want your I/O operation to
complete synchronously, use the $QIOW system service instead.)
46.3 - Condition Values Returned
Each function used with $QIO has its own error codes. See the
error codes listed under the individual descriptions of the
device driver I/O function code in the remainder of this chapter.
46.4 - Network Pseudodevice Driver Functions
The network pseudodevice allows physical, logical, and virtual
I/O functions. The physical and logical I/O functions are used
only with the IP layer. Network Pseudodevice Driver I/O Functions
lists the basic I/O functions and their modifiers. The sections
that follow describe in greater detail the operation of these I/O
functions.
Table 1 Network Pseudodevice Driver I/O Functions
Function Code and Function
Arguments Modifier Description
IO$_ACCESS p3,p4 IO$M_ACCEPT Opens a connection.
IO$M_EXTEND
IO$M_NOW
IO$_ACPCONTROL p1, Performs an ACP (ancillary
p2, p3, p4 control process) operation.
IO$_DEACCESS p4 IO$M_NOW Aborts or closes a
IO$M_SHUTDOWN connection.
IO$_READVBLK IO$M_EXTEND Reads a virtual block.
p1,p2,p3,p4,p6 IO$M_
INTERRUPT
IO$M_LOCKBUF Controls the buffer
IO$M_PURGE operations.
IO$_SENSEMODE Reads the network
p2,p3,p4,p6 pseudodevice
characteristics.
IO$_SENSECHAR Reads the network
p2,p3,p4,p6 pseudodevice
characteristics.
IO$_SETMODE p1,p2, IO$M_OUTBAND Sets the network
p3,p4,p5 IO$M_READATTN pseudodevice characteristics
IO$M_WRTATTN for subsequent operations.
IO$_SETCHAR p1,p2, IO$M_OUTBAND Sets the network
p3,p4,p5 IO$M_READATTN pseudodevice characteristics
IO$M_WRTEATTN for subsequent operations.
IO$_WRITEVBLK IO$M_ Writes a virtual block.
p1,p2,p3,p4,p5 INTERRUPT
The following table contains the file names of the symbol
definition files. These files specify $QIO arguments
(p1,p2,...p6) for applications written in the corresponding
programming languages. You must invoke the symbol definition
by using the appropriate include statement in your application.
Table 2 Network Symbol Definition Files
File Name Language
<REFERENCE>(filpref)$INDECEC.or VAX C
<REFERENCE>(filpref)$INVAXEFortran
<REFERENCE>(filpref)$INVAXEPASCAL
<REFERENCE>(filpref)$INMACRO-32R
<REFERENCE>(filpref)$INVAXEPL/1I
<REFERENCE>(filpref)$INBLISS-322
<REFERENCE>(filpref)$INVAXEADADA
<REFERENCE>(filpref)$INVAXEBASIC
46. 4.1 - IO$_ACCESS
When using a connection-oriented protocol, such as TCP, the IO$_
ACCESS function initiates a connection and specifies a remote
port number and internet address. When using a connectionless
protocol, such as UDP, the IO$_ACCESS function sets the remote
port number and internet address.
For TCP, a connection request times out at a specified interval
(75 seconds is the default). This interval can be changed by
the system manager. The program can also set a specific timeout
interval for a socket that it has created.
If a connection fails, you must deallocate the socket and then
create a new socket before trying to reconnect.
Related Functions
The equivalent Sockets API function is connect().
46. 4. 1.1 - Arguments
p3
OpenVMS usage:socket_name
type: vector byte (unsigned)
access: read only
mechanism: by item_list_2 descriptor
The remote port number and internet address of the host to
connect. The p3 argument is the address of an item_list_2
descriptor that points to the socket address structure containing
the remote port number and internet address.
46. 4. 1.2 - Function Modifiers
IO$M_NOW Regardless of a $QIO or $QIOW, if the system
detects a condition that would cause the
operation to block, the system completes the
I/O operation and returns the SS$_SUSPENDED
status code.
46. 4. 1.3 - Condition Values Returned
SS$_NORMAL The service completed successfully.
SS$_BADPARAM Programming error that occurred for one of the
following reasons:
o $QIO system service was specified without a
socket.
o An IO$_ACCESS function was specified
without the address of a remote socket
name (p3 was null).
SS$_BUGCHECK Inconsistent state. Report the problem to your
Compaq support representative.
SS$_CANCEL The I/O operation was canceled by a $CANCEL
system service.
SS$_CONNECFAIL The connection to a network object timed out
or failed.
SS$_DEVINTACT The network driver was not started.
SS$_DEVNOTMOUNT The network driver is loaded, but the INETACP
is not currently available for use.
SS$_DUPLNAM A network configuration error. No ports were
available for new connections.
SS$_EXQUOTA The process has exceeded its socket quota or
some other process quota.
SS$_FILALRACC The specified socket name is already in use by
one of the following:
o On a raw socket, the remote internet
address was already specified on a previous
IO$_ACCESS call.
o On a datagram, the remote internet address
was already specified on a previous
IO$_ACCESS call.
o On a stream socket, the IO$_ACCESS function
targeted a stream socket that was already
connected.
SS$_ILLCNTRFUNC Illegal function.
SS$_INSFMEM Insufficient system dynamic memory to complete
the service.
SS$_IVADDR The specified internet address was not found,
or an invalid port number and internet address
combination was specified with the IO$_ACCESS
function. Port 0 is not allowed with the
IO$_ACCESS function.
SS$_IVBUFLEN The size of the socket name structure
specified with the IO$_ACCESS function was
invalid.
SS$_LINKABORT The remote socket closed the connection.
SS$_NOLICENSE The Compaq TCP/IP Services for OpenVMS license
is not present.
SS$_PROTOCOL A network protocol error occurred. The
address family specified in the socket address
structure is not supported.
SS$_REJECT The network connection is rejected for one of
the following reasons:
o An attempt was made to connect to a remote
socket that is already connected.
o An error was encountered while establishing
the connection
o The peer socket refused the connection
request or is closing the connection.
SS$_SHUT The local or remote node is no longer
accepting connections.
SS$_SUSPENDED The system detected a condition that might
cause the operation to block.
SS$_TIMEOUT A TCP connection timed out before the
connection could be established.
SS$_UNREACHABLE The remote node is currently unreachable.
46. 4.2 - IO$_ACCESS|IO$M_ACCEPT
This function is used with a connection-based protocol, such as
TCP, to accept a new connection on a passive socket.
This function completes the first connection on the queue of
pending connections.
Related Functions
The equivalent Sockets API function is accept() .
46. 4. 2.1 - Arguments
p3
OpenVMS usage:socket_name
type: vector byte (unsigned)
access: read only
mechanism: by item_list_3 descriptor
The remote port number and internet address of a new connection.
The p3 argument is the address of an item_list_3 descriptor that
points to the socket address structure into which the remote port
number and internet address of the new connection is written.
Use the IO$_ACCESS function with the IO$M_EXTEND modifier to
specify a BSD Version 4.4 formatted socket address structure.
p4
OpenVMS usage:channel
type: word (unsigned)
access: write only
mechanism: by reference
The I/O channel number assigned to a new connection. The p4
argument is the address of a word into which the new connection's
channel number is written.
46. 4. 2.2 - Function Modifiers
IO$M_EXTEND Allows the usage of BSD Version 4.4 formatted
socket address structures.
IO$M_NOW Regardless of a $QIO or $QIOW, if the system
detects a condition that would cause the
operation to block, the system completes the
I/O operation and returns the SS$_SUSPENDED
status code.
46. 4. 2.3 - Condition Values Returned
SS$_NORMAL The service completed successfully.
SS$_BADPARAM Programming error that occurred for one of the
following reasons:
o $QIO system service was specified without a
socket.
o A IO$_ACCESS|IO$M_ACCEPT function was
specified without the address of the
channel for the new connection (p4 was
null or invalid).
SS$_BUGCHECK Inconsistent state. Report the problem to your
Compaq support representative.
SS$_CANCEL The I/O operation was canceled by a $CANCEL
system service.
SS$_DEVINTACT The network driver was not started.
SS$_DEVNOTMOUNT The network driver is loaded, but the INETACP
is not currently available for use.
SS$_EXQUOTA The process has exceeded its socket quota or
some other process quota.
SS$_FILALRACC The specified socket name is already in use by
one of the following:
o On a raw socket, the remote internet
address was already specified on a previous
IO$_ACCESS call.
o On a datagram, the remote internet address
was already specified on a previous
IO$_ACCESS call.
o On a stream socket, the IO$_ACCESS function
targeted a stream socket that was already
connected.
SS$_ILLCNTRFUNC Illegal function.
SS$_INSFMEM Insufficient system dynamic memory to complete
the service.
SS$_IVADDR The specified internet address was not found,
or an invalid port number and internet address
combination was specified with the IO$_ACCESS
function. Port 0 is not allowed with the
IO$_ACCESS function.
SS$_IVBUFLEN The size of the socket name structure
specified with the IO$_ACCESS function was
invalid.
SS$_LINKABORT The remote socket closed the connection.
SS$_NOLICENSE The TCP/IP Services license is not present.
SS$_PROTOCOL A network protocol error occurred. The
address family specified in the socket address
structure is not supported.
SS$_REJECT The network connection is rejected for one of
the following reasons:
o An attempt was made to connect to a remote
socket that is already connected.
o An error was encountered while establishing
the connection
o The peer socket refused the connection
request or is closing the connection.
SS$_SHUT The local or remote node is no longer
accepting connections.
SS$_SUSPENDED The system detected a condition that might
cause the operation to block.
SS$_TIMEOUT A TCP connection timed out before the
connection could be established.
SS$_UNREACHABLE The remote node is currently unreachable.
46. 4.3 - IO$_ACPCONTROL
The IO$_ACPCONTROL function accesses the network ACP to retrieve
information from the host and the network database files.
Related Functions
The equivalent Sockets API functions are gethostbyaddr(),
gethostbyname(), getnetbyaddr(), and getnetbyname().
46. 4. 3.1 - Arguments
p1
OpenVMS usage:subfunction_code
type: longword (unsigned)
access: read only
mechanism: by descriptor-fixed-length descriptor
A longword identifying the network ACP operation to perform.
The p1 argument is the address of a descriptor pointing to this
longword.
To specify the network ACP operation to perform, select a
subfunction code from Subfunction Codes and a call code from
Call Codes.
Subfunction Codes defines subfunction codes for network ACP
operations.
Table 3 Subfunction Codes
Subfunction Code Description
INETACP_FUNC$C_ Get the host name of the specified
GETHOSTBYADDR internet address from the host
database.
INETACP_FUNC$C_ Get the internet address of the
GETHOSTBYNAME specified host from the host
database.
INETACP_FUNC$C_ Get the network name of the specified
GETNETBYADDR internet address from the network
database.
INETACP_FUNC$C_ Get the internet address of the
GETNETBYNAME specified network from the network
database.
Call Codes defines call codes for network ACP operations.
Table 4 Call Codes
Call Code Description
INETACP$C_ALIASES Returns the list of alias names associated
with the specified host or network from
the internet hosts or network database.
INETACP$C_TRANS Returns the internet address associated
with the specified host or network as a
32-bit value in network byte order.
INETACPC$C_HOSTENT_ Returns full host information in a
OFFSET modified hostent structure. In the
modified structure, pointers are replaced
with offsets from the beginning of the
structure.
INETACP$C_NETENT_ Returns full network information in
OFFSET a modified netent structure. In the
modified structure, pointers are replaced
with offsets from the beginning of the
structure.
IO$_ACPCONTROL searches the local host database for the host's
name. If a matching host name is not found in the local host
database, IO$_ACPCONTROL then searches the BIND database if the
BIND resolver is enabled.
p2
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Input string for the network ACP operation containing one of the
following: host internet address, host name, network internet
address, or network name. The p2 argument is the address of a
string descriptor pointing to the input string.
All internet addresses are specified in dotted-decimal notation.
p3
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length in bytes of the output buffer returned by IO$_ACPCONTROL.
The p3 argument is the address of a word in which the length of
the output buffer is written.
p4
OpenVMS usage:buffer
type: vector byte (unsigned)
access: write only
mechanism: by descriptor-fixed-length descriptor
Buffer into which IO$_ACPCONTROL writes its output data. The p4
argument is the address of a descriptor pointing to the output
buffer.
The format of the data returned in the output buffer is dictated
by the call code specified by the p1 argument.
o Strings returned by IO$_ACPCONTROL with a call code of
INETACP$C_ALIASES consist one of the following: host internet
address, host name, network internet address, or network name.
All internet addresses are formatted using dotted-decimal
notation. Alias names are separated by a null character (0).
The length of the returned string includes all null characters
that separate alias names.
o Internet addresses returned by IO$_ACPCONTROL with a call code
of INETACP$C_TRANS are 32-bit value and in network byte order.
o All hostent and netent structures returned by IO$_ACPCONTROL
with a call code of INETACP$C_HOSTENT_OFFSET or INETACP$C_
NETENT_OFFSET are modified; pointers are replaced with offsets
from the beginning of the structure.
46. 4. 3.2 - Condition Values Returned
SS$_NORMAL The service completed successfully
SS$_ABORT An error was detected while performing an ACP
function.
SS$_BADPARAM Programming or internal error. A bad
parameter (name or address) was specified
in a GET{HOST,NET}BY{NAME,ADDRESS} ACP call.
SS$_BUFFEROVF Programming error. There was not enough space
for returning all alias names in a
GET{HOST,NET}BY{NAME,ADDRESS} ACP call.
SS$_ENDOFFILE The information requested is not in the
database.
SS$_ILLCNTRFUNC Illegal function.
SS$_NOPRIV No privilege for the execution of an ACP
function.
SS$_RESULTOVF The ACP overflowed the buffer in returning a
parameter.
SS$_SHUT The local or remote node is no longer
accepting connections.
46. 4.4 - IO$_DEACCESS
The IO$_DEACCESS function closes a connection and deletes a
socket. Any pending messages queued for transmission are sent
before tearing down the connection.
When used with the IO$M_SHUTDOWN function modifier, the IO$_
DEACCESS function shuts down all or part of a bidirectional
connection on a socket. Use the p4 argument to specify the
disposition of pending I/O operations on the socket.
You can specify a wait time or time-to-linger socket parameter
(TCPIP$C_LINGER option) for transmission completion before
disconnecting the connection. Use the IO$_SETMODE or IO$_SETCHAR
function to set and clear the TCPIP$C_LINGER option.
If you set the TCPIP$C_LINGER option, a $QIO call that uses the
IO$_DEACCESS function allows data queued to the socket to arrive
at the destination. The system is blocked until data arrives at
the remote socket. The socket data structure remains open for the
duration of the TCP idle time interval.
If you do not set the TCPIP$C_LINGER option (option is set to 0),
a $QIO call that uses the IO$_DEACCESS function discards any data
queued to the socket and deallocates the socket data structure.
NOTE
For compatibility with Compaq Tru64 UNIX, the TCP/IP
Services forces a time to linger of 2 minutes on TCP stream
sockets.
Related Functions
The equivalent Sockets API functions are close() and shutdown().
46. 4. 4.1 - Arguments
p4
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Longword of shutdown flags to specify the disposition of pending
I/O operations on the socket. The p4 argument is used only with
the IO$M_SHUTDOWN function modifier. The following table lists
available shutdown flags.
Shutdown Flag Description
TCPIP$C_DSC_ Discards messages from the receive queue and
RCV disallows further receiving. Pending messages
in the receive queue for this connection are
discarded.
TCPIP$C_DSC_ Discards messages from the send queue and
SND disallows sending new messages. Pending messages
in the transmit queue for this connection are
discarded.
TCPIP$C_DSC_ Discards all messages and disallows both
ALL sending and receiving. All pending messages are
discarded.
Specifying this flag has the same effect as
issuing a $CANCEL QIO followed by an IO$_DEACCESS
QIO without specifying any flags.
46. 4. 4.2 - Function Modifiers
IO$M_SHUTDOWN Causes all or part of a full-duplex connection
on a socket to be shut down.
IO$M_NOW Regardless of a $QIO or $QIOW, if the system
detects a condition that would cause the
operation to block, the system completes the
I/O operation and returns the SS$_SUSPENDED
status code.
46. 4. 4.3 - Condition Values Returned
SS$_NORMAL The service completed successfully.
SS$_BADPARAM The IO$_DEACCESS operation failed to specify a
socket.
SS$_CANCEL The I/O operation was canceled by a $CANCEL
system service.
SS$_DEVINTACT The network driver was not started.
SS$_DEVNOTMOUNT The network driver is loaded, but the INETACP
is not currently available for use.
SS$_NOLINKS The specified socket was not connected.
SS$_SHUT The local or remote node is no longer
accepting connections.
SS$_SUSPENDED The system detected a condition that might
cause the operation to block.
46. 4.5 - IO$_READVBLK
The IO$_READVBLK function transfers data received from an
internet host to the specified user buffers. Use both p1 and
p2 arguments to specify a single user buffer. Use the p6 argument
to specify multiple buffers.
For connection-oriented protocols, such as TCP, data is buffered
in system space as a stream of bytes. The IO$_READVBLK function
completes (1) when there is no more data buffered in system space
for this socket, or (2) when there is no more available space in
the user buffer. Data that is buffered in system space but did
not fit in the user buffer is available to the user in subsequent
$QIOs.
For connectionless protocols, datagram and raw socket data is
buffered in system space as a chain of records. The user buffer
specified with a IO$_READVBLK function is filled with data that
is buffered in one record. Each IO$_READVBLK reads data from one
record. The IO$_READVBLK function completes (1) when all data
from a record is transferred to the user buffer, or (2) when
there is no more available space in the user buffer. Any data
remaining in the current record that did not fit in the user
buffer is discarded. A subsequent $QIO reads data from the next
record buffered in system space.
Use the management command SHOW DEVICE_SOCKET/FULL to display
counters related to read operations.
Related Functions
The equivalent Sockets API functions are read(), recv(),
recvfrom(), and recvmsg().
46. 4. 5.1 - Arguments
p1
OpenVMS usage:buffer
type: vector byte (unsigned)
access: read only
mechanism: by 32- or 64-bit reference (Alpha)
by 32-bit reference (VAX)
The 32- or 64-bit address (on Alpha systems) or the 32-bit
address (on VAX systems) of the buffer to receive the incoming
data. The length of this buffer is specified by the p2 argument.
p2
OpenVMS usage:buffer_length
type: quadword unsigned (Alpha); longword unsigned (VAX)
access: read only
mechanism: by 64-bit value (Alpha)
by 32-bit value (VAX)
The length (in bytes) of the buffer available to hold the
incoming data. The address of this buffer is specified by the
p1 argument.
p3
OpenVMS usage:socket_name
type: vector byte (unsigned)
access: read only
mechanism: by item_list_3 descriptor
The remote port number and internet address of the source of
the datagram or raw IP message (not TCP). The p3 argument is the
address of an item_list_3 descriptor that points to the socket
address structure into which the remote port number and internet
address of the message source is written.
Use the IO$_READVBLK function with the IO$M_EXTEND modifier to
specify a BSD Version 4.4 formatted socket address structure.
If the IO$M_EXTEND modifier is not specified, the IO$_READVBLK
function returns a BSD Version 4.3 formatted socket address
structure.
p4
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Longword of flags to specify attributes for the read operations.
Read Flags lists the available read flags.
Table 5 Read Flags
Read Flag Description
TCPIP$C_MSG_OOB Reads an out-of-band byte.
TCPIP$C_MSG_PEEK Reads a message but leaves the message in the
queue.
TCPIP$C_MSG_NBIO Does not block the I/O operation if the
receive queue is empty (similar to using
IO$M_NOWAIT).
TCPIP$C_MSG_PURGE Flushes data from the queue (similar to using
IO$M_PURGE).
TCPIP$C_MSG_ Blocks the completion of the operation until
BLOCKALL the buffer is filled completely or until the
connection is closed (similar to using IO$M_
LOCKBUF).
p6
OpenVMS usage:buffer_list
type: vector byte (unsigned)
access: read only
mechanism: by 32- or 64-bit descriptor-fixed-length descriptor
(Alpha)
by 32-bit descriptor-fixed-length descriptor (VAX)
Output buffer list describing one or more buffers to hold the
incoming data. The p6 argument is the 32- or 64-bit address
(on Alpha systems) or the 32-bit address (on VAX systems) of
a descriptor that points to a output buffer list. Buffers are
filled in the order specified by the output buffer list. The
transfer-length value returned in the I/O status block is the
total number of bytes transferred to all buffers.
If you use the p1 and p2 arguments, do not use the p6 argument;
they are mutually exclusive.
46. 4. 5.2 - Function Modifiers
IO$M_EXTEND Specifies the format of the socket address
structure to return when used with the p3
argument.
When specified, a BSD Version 4.4 formatted
socket address structure is returned that
identifies the source of the received UDP
datagram or raw IP message.
IO$M_INTERRUPT Reads an out-of-band (OOB) message. This
has the same effect as specifying the
TCPIP$C_MSG_OOB flag in the p4 argument.
On receiving a TCP/IP OOB character, TCP/IP
stores the pointer in the received stream with
the character that precedes the OOB character.
A read operation with a user-buffer size
larger than the size of the received stream
up to the OOB character completes and returns
to the user the received stream up to, but not
including, the OOB character.
To determine whether the socket must issue
more read $QIOs before getting all the
characters from the stream preceding an OOB
character, poll the socket. To do this, issue
a $QIO with the $IO_SENSEMODE function, and
the TCPIP$C_IOCTL subfunction that specifies
the SIOCATMARK command. The SIOCATMARK values
are as follows:
o 0 = Issue more read QIOs to read more data
before reading the OOB.
o 1 = The next read QIO will return the OOB.
Polling a socket is particularly useful
when the OOBINLINE socket option is set.
When the OOBINLINE is set, TCP/IP reads the
OOB character with the characters in the
stream (IO$_READVBLK), but not before reading
the preceding characters. Use this polling
mechanism to determine whether the first
character in the user buffer on the next read
is an OOB character.
On a socket without the OOBINLINE option
set, a received OOB will always be
read by issuing a $QIO with either the
IO$_READVBLK|IO$M_INTERRUPT or IO$_READVBLK
and the TCPIP$C_MSG_OOB flag set. This
can occur regardless of how many preceding
characters in the stream have been returned to
the user.
IO$M_LOCKBUF Blocks the completion of the I/O operation
until the user buffer is completely filled
or until the connection is closed. This
is particularly useful when you want to
minimize the number of $QIO service calls
issued to read a data stream of a set size.
This function modifier supports only stream
protocols.
IO$M_NOWAIT Regardless of a $QIO or $QIOW, if the
system detects a condition that would
cause the operation to block, the system
completes the I/O operation and returns the
SS$_SUSPENDED status code.
IO$M_PURGE Flushes data from the socket receive queue
(discards data). If the user buffer is larger
than the amount of data in the queue, all data
is flushed.
46. 4. 5.3 - Condition Values Returned
SS$_NORMAL The service completed successfully.
SS$_ABORT Programming error, INET management error, or
hardware error. The execution of the I/O was
aborted.
SS$_ACCVIO Access to an invalid memory location or buffer
occurred.
SS$_BADPARAM One of the following methods was used to
specify a $QIO function with an invalid
parameter:
o An I/O function executed without specifying
a device socket. First issue a $QIO with
the IO$_SETMODE function and the proper
parameters to create the device socket.
o An IO$_READVBLK function that does not
specify a correct buffer address (p1 or p6
is null).
o An IO$_READVBLK function specified an
invalid vectored buffer (p6 is an invalid
descriptor).
o The socket has the OOBINLINE option set,
or there is no OOB character in the
socket's OOB queue because the character
was either already read or never received.
This condition happens only if you use
the IO$M_INTERRUPT modifier or set the
TCPIP$C_MSG_OOB flag with IO$_READVBLK.
SS$_CANCEL The I/O operation was canceled by a $CANCEL
system service.
SS$_DEVINTACT The network driver was not started.
SS$_DEVNOTMOUNT The network driver is loaded, but the INETACP
is not currently available for use.
SS$_INSFMEM INET management or programming error. There
is not enough buffer space for allocation.
The INET software needs more buffer space.
You should set a higher quota for the dynamic
buffer space, or shut down and restart your
internet with a larger static buffer space.
SS$_IVBUFLEN Programming error occurred for one of the
following reasons:
o The size of the buffer for an I/O function
is insufficient.
o An IO$_READVBLK specified a correct buffer
address (p1 valid), but does not specify a
buffer length (p2 is null).
SS$_LINKDISCON A virtual circuit (TCP/IP) was closed at the
initiative of the peer.
SS$_NOLINKS Programming error. Read attempt on unconnected
TCP socket.
SS$_SHUT The network is being shut down.
SS$_SUSPENDED The operation is blocked for one of the
following reasons:
o No messages were received, so the receive
operation cannot complete. The socket is
marked as nonblocking.
o The socket has the OOBINLINE option clear,
and the OOB character has already been
read.
SS$_TIMEOUT This applies to a socket that has KEEPALIVE
set. The connection was idle for longer
than the timeout interval (10 minutes is the
default).
SS$_UNREACHABLE Communication status. The remote host or
network is unreachable.
46. 4.6 - IO$_SENSEMODE/IO$_SENSECHAR
The IO$_SENSEMODE and IO$_SENSECHAR functions return one or more
parameters (characteristics) pertaining to the network driver.
Socket names (local and remote peer) are returned by using IO$_
SENSEMODE's p3 and p4 arguments. Other parameters such as socket
and protocol options, are specified in an output parameter list
using the IO$_SENSEMODE p6 argument.
IO$_SENSEMODE p3 and p4 arguments can be used with the p6
argument in a single $QIO system service to return socket names
as well as socket and protocol options. IO$_SENSEMODE processes
arguments in this order: p3, p4, p6. If IO$_SENSEMODE detects an
error, the IOSB contains the error and argument address or the
value that was at fault.
Refer to individual argument descriptions for details about
specifying the type and format of output parameters.
46. 4. 6.1 - Arguments
p3
OpenVMS usage:socket_name
type: vector byte (unsigned)
access: read only
mechanism: by item_list_3 descriptor
The port number and internet address of the local name associated
with the socket. The p3 argument is the address of an item_list_3
descriptor that points to the socket address structure into which
the local name is written.
Use the IO$_SENSEMODE function with the IO$M_EXTEND modifier to
specify a BSD Version 4.4 formatted socket address structure.
Related Functions
The Sockets API equivalent for this function is getsockname().
p4
OpenVMS usage:socket_name
type: vector byte (unsigned)
access: read only
mechanism: by item_list_3 descriptor
The port number and internet address of the remote name
associated with the socket's peer. The p3 argument is the address
of an item_list_3 descriptor that points to the socket address
structure into which the peer name is written.
Use the IO$_SENSEMODE function with the IO$M_EXTEND modifier to
specify a BSD Version 4.4 formatted socket address structure.
Related Functions
The equivalent Sockets API function is getpeername().
p6
OpenVMS usage:output_parameter_list
type: vector byte (unsigned)
access: read only
mechanism: by item_list_2 descriptor
Output parameter list describing one or more parameters to
return. The p6 argument is the address of an item_list_2
descriptor that points to and identifies the type of output
parameter list.
The following are the types of output parameter lists:
Symbolic Name Output Parameter List Type
TCPIP$C_SOCKOPT Socket options
TCPIP$C_TCPOPT TCP protocol options
TCPIP$C_IPOPT IP protocol options
TCPIP$C_IOCTL I/O control commands
Each item_list_3 structure appearing in an output parameter
list describes an individual parameter or item to return. See
<REFERENCE>(op_setsock_tab) for details about socket option
parameters; see <REFERENCE>(tcp_set_tab_opt) for TCP protocol
option parameters; and see <REFERENCE>(ip_set_tab_opt) for
IP protocol option parameters. Unsupported socket or protocol
options are ignored.
Each ioctl_com structure that appears in an output parameter list
contains an I/O control command - the get IOCTL request code and
its associated IOCTL structure address. See <REFERENCE>(ioctl_
cmds2) for details about IOCTL command parameters.
Unsupported socket options are ignored.
The equivalent Sockets API functions are getsockopt() and
ioctl().
46. 4. 6.2 - Function Modifiers
IO$M_EXTEND Specifies the format of the socket address
structure to return when used with the p3 or
p4 arguments.
When specified, a BSD Version 4.4 formatted
socket address structure is returned.
46. 4. 6.3 - Condition Values Returned
SS$_NORMAL The service completed successfully.
SS$_ACCVIO The service cannot access a buffer specified
by one or more arguments.
SS$_BADPARAM Programming error occurred for one of the
following reasons:
o $QIO system service was specified without a
socket.
o Error occurred processing a socket or
protocol option.
SS$_DEVINTACT The network driver was not started.
SS$_DEVNOTMOUNT The network driver is loaded, but the INETACP
is not currently available for use.
SS$_ILLCNTRFUNC Programming error. The operation is
unsupported for one of the following reasons:
o An invalid IO$_SENSEMODE function for the
interface was specified. The interface does
not have an IOCTL routine.
o An IO$_SENSEMODE function that requires a
socket was specified, but the device did
not have one. Create a socket and then
issue the function.
o An unsupported operation was performed on
at least one of the following protocols:
raw IP, datagram, or stream sockets.
SS$_INSFMEM Insufficient system dynamic memory to complete
the service.
SS$_IVBUFLEN The size of a socket option buffer specified
with the IO$_SENSEMODE function was invalid.
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 The specified socket was not connected.
SS$_NOOPER Programming error. An attempt to get ARP
information occurred without OPER privilege.
SS$_PROTOCOL A network protocol error occurred. The
address family specified in the socket address
structure is not supported.
SS$_SHUT The local or remote node is no longer
accepting connections.
SS$_UNREACHABLE The remote node is currently unreachable.
46. 4.7 - IO$_SETMODE/IO$_SETCHAR
The IO$_SETMODE and IO$_SETCHAR functions set one or more
parameters (characteristics) pertaining to the network driver.
Sockets are created using the IO$_SETMODE p1 argument. Names are
assigned to sockets using the IO$_SETMODE p3 argument. Active
sockets are converted to passive sockets using the IO$_SETMODE p4
argument. Other parameters, such as socket and protocol options,
are specified in an input parameter list using the IO$_SETMODE p5
argument.
The IO$_SETMODE p1, p3, and p4 arguments can be used with the
p5 argument in a single $QIO system service to set socket names
as well as socket and protocol options. IO$_SETMODE processes
arguments in this order: p1, p3, p4, p5. If IO$_SETMODE detects
an error, the IOSB contains the error and argument address or the
value that was at fault.
Refer to individual argument descriptions for details about
specifying the type and format of input parameters.
46. 4. 7.1 - Arguments
p1
OpenVMS usage:socket_characteristics
type: longword (unsigned)
access: read only
mechanism: by reference
Longword specifying the protocol, socket type, and address
family, of a new socket. The p1 argument is the address of the
longword containing the socket characteristics.
The newly created socket is marked privileged if the image that
creates a socket runs in a process that has a privileged UIC or
has BYPASS, OPER, or SYSPRV privilege.
The following table shows protocol codes:
Protocol Description
TCPIP$C_TCP TCP/IP protocol
TCPIP$C_UDP UDP/IP protocol
TCPIP$C_RAW_ IP protocol
IP
Socket Types lists the valid socket types.
Table 6 Socket Types
Socket Type Description
TCPIP$C_STREAM Permits bidirectional, reliable, sequenced,
and unduplicated data flow without record
boundaries.
TCPIP$C_DGRAM Permits bidirectional data flow with record
boundaries. No provisions for sequencing,
reliability, or unduplicated messages.
TCPIP$C_RAW Permits access to the IP layer; used to develop
new protocols that are layered upon the IP
layer.
The following table shows address family codes:
Address
Family Description
TCPIP$C_AF_ Internet domain (default).
INET
TCPIP$C_AUXS Accept hand-off of a socket already created and
initialized by the auxiliary server.
Related Functions
The equivalent Sockets API function is socket().
p3
OpenVMS usage:socket_name
type: vector byte (unsigned)
access: read only
mechanism: by item_list_2 descriptor
The local name (that is, port number and internet address) to
assign to the socket. The p3 argument is the address of an item_
list_2 descriptor that points to the socket address structure
containing the local name.
Related Functions
The equivalent Sockets API function is bind() .
p4
OpenVMS usage:connection_backlog
type: byte (unsigned)
access: read only
mechanism: by value
Maximum limit of outstanding connection requests for a socket
that is connection oriented. If more connection requests are
received than are specified, the additional requests are ignored
so that TCP retries can succeed.
Related Functions
The equivalent Sockets API function is listen().
p5
OpenVMS usage:input_parameter_list
type: vector byte (unsigned)
access: read only
mechanism: by item_list_2 descriptor
Input parameter list describing one or more parameters to set.
The p5 argument is the address of an item_list_2 descriptor that
points to and identifies the type of input parameter list.
The following are the types of input parameter lists:
Symbolic Name Input Parameter List Type
TCPIP$C_SOCKOPT Socket options
TCPIP$C_TCPOPT TCP protocol options
TCPIP$C_IPOPT IP protocol options
TCPIP$C_IOCTL I/O control commands
Each item_list_2 structure appearing in an input parameter
list describes an individual parameter or item to set. See
<REFERENCE>(op_setsock_tab) for details about socket option
parameters; see <REFERENCE>(tcp_set_tab_opt) for TCP protocol
option parameters; and see <REFERENCE>(ip_set_tab_opt) for
details about IP protocol option parameters. Unsupported socket
or protocol options are ignored.
Each ioctl_com structure that appears in an input parameter list
contains an I/O control command - the set IOCTL request code and
its associated IOCTL structure address. See <REFERENCE>(ioctl_
cmds2) for details about IOCTL command parameters.
You can use one $QIO system call to set up several socket options
at once.
Unsupported socket options are ignored.
To execute set IOCTL operations, you need a system UIC or SYSPRV,
BYPASS, or OPER privilege.
Related Functions
The equivalent Sockets API functions are setsockopt() and
ioctl().
46. 4. 7.2 - Condition Values Returned
SS$_NORMAL The service completed successfully.
SS$_ACCVIO The service cannot access a buffer specified
by one or more arguments.
SS$_BADPARAM Programming error that occurred for one of the
following reasons:
o $QIO system service was specified without a
socket.
o Error occurred processing a socket or
protocol option.
SS$_DEVINTACT The network driver was not started.
SS$_DEVNOTMOUNT The network driver is loaded, but the INETACP
is not currently available for use.
SS$_DUPLNAM Programming error. The port being bound is
already in use. An attempt to bind the socket
to an address and port failed.
SS$_EXQUOTA Programming or INET management error occurred
for one of the following reasons:
o An attempt to create a new socket with
the IO$_SETMODE function occurred, but the
maximum number of sockets was exceeded.
Increase the maximum number of sockets
(INET parameter).
o The number of sockets specified with the
IO$_SETMODE (listen) exceeds the maximum
number of sockets. Increase the maximum
number of sockets (INET parameter), or
reduce the listen parameter (the number of
sockets the listener socket can create).
SS$_FILALRACC Programming error. The INET address is already
in use. An attempt to bind the socket to an
address and port failed.
SS$_ILLCNTRFUNC Programming error. The operation is not
supported for one of the following reasons:
o An invalid IO$_SETMODE function for the
interface occurred that does not have an
IOCTL routine.
o An attempt to perform an IO$_SETMODE
function required a socket, but the device
did not have one. Create a socket before
issuing the function.
SS$_IVADDR Programming error. The INET address you
specified using the IO$_SETMODE function was
not placed into the system. This resulted
in an invalid port number or INET address
combination. The INET address was invalid for
one of the following reasons:
o Port zero and INET address zero are not
allowed, or port zero is not allowed
when using an IO$_ACCESS or IO$_WRITEVBLK
function.
o An attempt to exceed the limit of allowable
permanent entries in the ARP table
occurred.
o An attempt to bind a raw IP socket when
there are no interfaces defined in the
system occurred.
o An attempt to bind a raw IP socket to a
null INET address occurred.
SS$_INSFMEM Insufficient system dynamic memory to complete
the service.
SS$_IVBUFLEN The size of a socket option buffer specified
with the IO$_SETMODE function was invalid.
SS$_NOLICENSE Programming or system management error. A
TCP/IP Services license is not present.
SS$_NOOPER Programming or INET management error. An
attempt to execute an I/O function that needs
the OPER privilege occurred.
SS$_NOPRIV Programming or INET management error. There
are not enough privileges for the attempted
operation for one of the following reasons:
o An attempt to broadcast an IP datagram on
a process without a system UIC or SYSPRV,
BYPASS, or OPER privilege occurred.
o An attempt to use a reserved port number
lower than 1024 occurred.
o An attempt to access a process that
requires a system UIC or SYSPRV, or BYPASS
privilege occurred.
o An attempt to use raw IP on a privileged
socket that requires the SYSPRV or BYPASS
privilege occurred.
SS$_NOSUCHDEV Programming error or INET management error. An
attempt to show or delete an ARP table entry
failed because the INET address is not found.
SS$_NOSUCHNODE Programming error or INET management error.
An attempt to delete a route from the routing
table failed because the entry was not found.
SS$_PROTOCOL Programming error. A specified protocol or
address family caused an error for one of the
following reasons:
o An invalid protocol type was specified at
socket creation.
o An unsupported protocol was specified.
o A protocol type that was not found in the
internal tables was specified.
o The address family is unsupported for one
of the following reasons:
- An unsupported address family with the
IO$_SETMODE subfunction was specified.
Instead, specify the TCPIP$C_AF_INET or
TCPIP$C_UNSPEC address family.
- An unsupported address family for a
remote INET address with the IO$_ACCESS
or IO$_WRITEVBLK function was specified.
Instead, specify the TCPIP$C_AF_INET
address family.
- An unsupported address family for the
local INET address with the IO$_SETMODE
function was specified. Instead, specify
the TCPIP$C_AF_INET address family.
- An unsupported address family for the
INET address of the routing module was
specified. Instead, specify the TCPIP$C_
AF_INET address family.
SS$_SHUT The local or remote node is no longer
accepting connections.
46. 4.8 - IO$_SETMODE|IO$M_OUTBAND
The IO$_SETMODE|IO$M_OUTBAND function/modifier combination
requests that the asynchronous system trap (AST) for an out-
of-band (OOB) character be delivered to the requesting process.
This is to be done only when an OOB character is received on the
socket and there is no waiting read request. The socket must be a
TCP (stream) socket.
The Enable OOB character AST function allows an Attention AST
to be delivered to the requesting process only once. After the
AST occurs, the function must explicitly reenable AST delivery
before a new AST can be delivered. This function is subject to
AST quotas.
46. 4. 8.1 - Arguments
p1
OpenVMS usage:ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by reference
To enable the AST, the p1 argument is the address of the OOB
character AST routine. To disable the AST, p1 equals 0.
p2
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
AST parameter to be delivered to the AST routine specified by the
p1 argument.
p3
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode to deliver the AST.
46. 4. 8.2 - Condition Values Returned
SS$_NORMAL The service completed successfully.
SS$_ABORT Programming, INET management, or hardware
error.
SS$_ACCVIO Programming error. An attempt to access an
invalid memory location or buffer occurred.
SS$_BADPARAM Programming error. A $QIO service with an
invalid parameter occurred for one of the
following reasons:
o An attempt to execute an IO$_SETMODE
function (all subfunctions, except socket
creation) without specifying a device
socket. Instead, create a device socket
by issuing a $QIO with the IO$_SETMODE
function and the proper parameters.
o A socket option was specified incorrectly.
SS$_DEVACTIVE INET management error. An attempt to change
the static INET parameters occurred. If new
parameters are needed, shut down the internet,
reset the static parameters, and issue the
START COMMUNICATION command.
SS$_DEVINTACT INET management error. The driver was not
started. Issue a START COMMUNICATION command
before issuing $QIO functions.
SS$_DEVNOTMOUNT INET management error. The INET startup
procedure executed incorrectly. The driver was
loaded, but the INET_ACP was not activated.
Execute the INET startup procedure again.
SS$_DUPLNAM Programming error. An attempt to bind a port
that is already in use occurred. An attempt to
bind the socket to an address and port failed.
SS$_EXQUOTA Programming or INET management error occurred
because of one of the following reasons:
o An attempt to create a new socket with the
IO$_SETMODE function failed because the
maximum number of sockets was exceeded.
Increase the maximum number of sockets
(INET parameter).
o The number of sockets specified with the
IO$_SETMODE (listen) exceeds the maximum
number of sockets. Increase the maximum
number of sockets (INET parameter), or
reduce the listen parameter (the number
of sockets that the listener socket can
create).
SS$_FILALRACC Programming error. INET address is already
in use. An attempt to bind the socket to an
address and port failed.
SS$_INSFMEM Programming or system management error: Not
enough resources to allocate new socket.
SS$_ILLCNTRFUNC Programming error. Operation is not supported
because of one of the following reasons:
o Invalid IO$_SETMODE (IOCTL) function was
used for the interface. The interface does
not have an IOCTL routine.
o An attempt to perform an IO$_SETMODE
(IOCTL) function that required a socket,
but the device did not have one. Create a
socket and issue the IOCTL function.
SS$_IVADDR Programming error. The specified INET address
is not in the system, and an invalid port
number or an invalid INET address combination
was specified with an IO$_SETMODE function (a
bind) for one of the following reasons:
o An attempt to bind the address failed
because the INET address is not in the
system and port zero and INET address zero
are not allowed.
o An attempt to make a permanent entry in an
ARP table that was full failed.
o An attempt was made to bind an IP socket
(raw IP) when there are no interfaces
defined in the system.
o An attempt was made to bind an IP socket
(raw IP) to a null INET address.
SS$_IVBUFLEN Programming error. The socket option buffer
has an invalid size.
SS$_NOLICENSE Programming or system management error. TCP/IP
Services not present.
SS$_NOOPER Programming or INET management error. An
attempt was made to execute an I/O function
that needs the OPER privilege.
SS$_NOPRIV Programming or INET management error. Not
enough privileges for the attempted operation
for one of the following reasons:
o Broadcasting an IP datagram was denied
because the process does not have a system
UIC or SYSPRV, BYPASS, or OPER privilege.
o An attempt was made to use a reserved port
number lower than 1024.
o An operation accesses only processes that
have a system UIC or SYSPRV or BYPASS
privilege.
o Raw IP protocol can be used only on
privileged sockets. The process must have a
SYSPRV or BYPASS privilege.
SS$_NOSUCHDEV Programming error or INET management error.
An INET address is not in the ARP table. An
attempt to show or delete an ARP table entry
failed.
SS$_NOSUCHNODE Programming or INET management error. An
attempt to delete a route from the routing
table failed because a route entry was not
found.
SS$_PROTOCOL Programming error because of one of the
following reasons:
o The protocol type specified at socket
creation is not valid.
o The protocol is not supported.
o The protocol type specified is not found
in the internal tables and therefore is an
invalid type.
o The address family is not supported for one
of the following reasons:
- The address family specified with an
IO$_SETMODE function (IOCTL subfunction)
is not supported. The address family
should be the TCPIP$C_AF_INET or
TCPIP$C_UNSPEC address family.
- The address family of the local INET
address specified with an IO$_SETMODE
(bind) function is not supported. The
address family should be the TCPIP$C_AF_
INET address family.
- The address family of the INET address
specified in a request to the routing
module is not supported. The address
family should be the TCPIP$C_AF_INET
address family.
SS$_SHUT The local or remote node is no longer
accepting connections.
46. 4.9 - IO$_SETMODE|IO$M_READATTN
The IO$_SETMODE|IO$M_READATTN function/modifier combination
requests that an Attention AST be delivered to the requesting
process when a data packet is received on the socket and there is
no waiting read request.
The Enable Read Attention AST function enables an Attention AST
to be delivered to the requesting process only once. After the
AST occurs, the function must explicitly reenable AST delivery
before the AST can occur again. The function is subject to AST
quotas.
Consider the following when using IO$M_READATTN:
o There is a one-to-one correspondence between the number of
times you enable an Attention AST and the number of times the
AST is delivered. For example, for each enabled AST, one AST
is delivered. If you enable an Attention AST several times,
several ASTs are delivered for one event when an event occurs.
o If an out-of-band (OOB) Attention AST is enabled, the OOB AST
is delivered, regardless of the following:
- An enabled Read Attention AST
- The TCPIP$C_OOBINLINE socket option
- A READ $QIO waiting for completion on the socket
If the TCPIP$C_OOBINLINE option is set, then a waiting READ
$QIO is completed and the OOB character is returned in the data
stream.
o If both an OOB AST and a Read Attention AST are enabled, only
the OOB AST is delivered when an OOB character is received.
o If a Read Attention AST is enabled and the TCPIP$C_OOBINLINE
socket option is set, a waiting READ $QIO completes and the
OOB character is returned in the data stream.
o If a Read Attention AST is enabled and the TCPIP$C_OOBINLINE
socket option is not set (clear), the Read Attention AST
is delivered when an OOB character is received, regardless
of whether a READ $QIO is waiting for completion. In this
case, the OOB character is not returned in the data stream.
Therefore, if the OOB character is the only character
received, the READ $QIO does not complete.
46. 4. 9.1 - Arguments
p1
OpenVMS usage:ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by reference
To enable the AST, the p1 argument is the address of the Read
Attention AST routine. To disable the AST, set p1 to 0.
p2
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
AST parameter to be delivered to the AST routine.
p3
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode to deliver the AST.
46. 4. 9.2 - Condition Values Returned
SS$_ABORT Programming, INET management, or hardware
error. The route entry already exists, so
the attempt to add a route entry using the
IO$_SETMODE function failed.
SS$_ACCVIO Programming error. An attempt to access an
invalid memory location or buffer occurred.
SS$_BADPARAM Programming error. The parameter specified
for a $QIO function was invalid for one of the
following reasons:
o An attempt to execute the IO$_SETMODE
subfunctions without specifying a device
socket occurred. Instead, create a device
socket by issuing a $QIO with the IO$_
SETMODE function and the proper parameters.
o A socket option was specified incorrectly.
SS$_DEVACTIVE INET management error. An attempt to change
the static INET parameter was unsuccessful.
If you need new parameters, shut down the
internet, reset the static parameters, and
issue the START COMMUNICATION command.
SS$_DEVINTACT INET management error. The driver was not
started. Issue a START COMMUNICATION command
before issuing $QIO functions.
SS$_DEVNOTMOUNT INET management error. TCP/IP Services
improperly executed the startup procedure. The
driver was loaded, but the INET_ACP was not
activated. Execute the INET startup procedure
again.
SS$_DUPLNAM Programming error. An attempt to bind a port
already in use occurred so the operation
to bind the socket to the address and port
failed.
SS$_EXQUOTA Programming or INET management error. The
quota for the valid number of sockets caused
an error for one of the following reasons:
o An attempt to exceed the maximum number
of sockets by creating new socket with the
IO$_SETMODE function occurred. Increase the
maximum number of allowable sockets (INET
parameter) before creating more sockets.
o The number of sockets specified with the
IO$_SETMODE function exceeds the maximum
number of sockets allowed. Increase the
maximum number of sockets (INET parameter)
or reduce the number of sockets that
the listener socket can create (listen
parameter).
SS$_FILALRACC Programming error. An attempt to bind the
socket to an address that is already in use
occurred and the operation failed.
SS$_INSFMEM Programming or system management error. The
system does not have enough resources to
allocate new socket.
SS$_ILLCNTRFUNC Programming error. Operation is not supported.
o Invalid IO$_SETMODE (IOCTL) function was
used for the interface. The interface does
not have an IOCTL routine.
o An attempt was made to perform an IO$_
SETMODE (IOCTL) function that required
a socket, but the device did not have
one. Create a socket and issue the IOCTL
function.
SS$_IVADDR Programming error. The specified INET address
is not in the system, and an invalid port
number or an invalid INET address combination
was specified with an IO$_SETMODE function (a
bind).
o An attempt to bind the address failed
because the INET address is not in the
system, port zero and INET address zero are
not allowed, or port zero is not allowed
when using an IO$_ACCESS or IO$_WRITEVBLK
function.
o An attempt to make a permanent entry in the
ARP table failed because of lack of space.
Too many permanent entries.
o An attempt was made to bind an IP socket
(raw IP) when there are no interfaces
defined in the system.
o An attempt was made to bind an IP socket
(raw IP) to a null INET address.
SS$_IVBUFLEN Programming error. The socket option buffer
has an invalid size.
SS$_NOLICENSE Programming or system management error. TCP/IP
Services not present.
SS$_NOOPER Programming or INET management error. An
attempt was made to execute an I/O function
that needs the OPER privilege.
SS$_NOPRIV Programming or INET management error. Not
enough privileges for the attempted operation.
o Broadcasting an IP datagram was denied
because the process does not have a system
UIC or SYSPRV, BYPASS, or OPER privilege.
o An attempt was made to use a reserved port
number lower than 1024.
o An operation accesses only processes that
have a system UIC or SYSPRV, or BYPASS
privilege.
o Raw IP protocol can be used only on
privileged sockets. The process must have a
SYSPRV or BYPASS privilege.
SS$_NOSUCHDEV Programming error or INET management error.
An INET address is not in the ARP table. An
attempt to show or delete an ARP table entry
failed.
SS$_NOSUCHNODE Programming error or INET management error.
An attempt to delete a route from the routing
table failed because a route entry was not
found.
SS$_PROTOCOL Programming error.
o The protocol type specified at socket
creation is not valid.
o The protocol is not supported.
o The protocol type specified is not found in
the internal tables. It is an invalid type.
o The address family is not supported:
- The address family specified with an
IO$_SETMODE function (IOCTL subfunction)
is not supported. The address family
should be the TCPIP$C_AF_INET or
TCPIP$C_UNSPEC address family.
- The address family of the remote INET
address specified with an IO$_ACCESS or
IO$_WRITEVBLK function is not supported
(UDP/IP or TCP/IP). The address family
should be the TCPIP$C_AF_INET address
family.
- The address family of the local INET
address specified with an IO$_SETMODE
(bind) function is not supported. The
address family should be the TCPIP$C_AF_
INET address family.
- The address family of the INET address
that is specified in a request to the
routing module is not supported. The
address family should be the TCPIP$C_AF_
INET address family.
SS$_SHUT The local or remote node is no longer
accepting connections.
46. 4.10 - IO$_SETMODE|IO$M_WRTATTN
The IO$_SETMODE|IO$M_WRTATTN function/modifier combination (IO$M_
WRTATTN is Enable Write Attention AST) requests that an Attention
AST be delivered to the requesting process when a data packet can
be queued to the socket. For TCP sockets, this occurs when space
becomes available in the TCP transmit queue.
The Enable Write Attention AST function enables an Attention AST
to be delivered to the requesting process only once. After the
AST occurs, the function must explicitly reenable AST delivery
before the AST can occur again. The function is subject to AST
quotas.
There is a one-to-one correspondence between the number of
times you enable an Attention AST and the number of times the
AST is delivered. For example, for each enabled AST, one AST is
delivered. If you enable an Attention AST several times, several
ASTs are delivered for one event when the event occurs.
You can use the management command SHOW DEVICE_SOCKET to display
information about the socket's characteristics, options, and
state.
46. 4. 10.1 - Arguments
p1
OpenVMS usage:ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by reference
To enable the AST, the p1 argument is the address of the Write
Attention AST routine. To disable the AST, p1 is set to 0.
p2
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
AST parameter to be delivered to the AST routine.
p3
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode to deliver the AST.
46. 4. 10.2 - Condition Values Returned
SS$_ABORT Programming error, INET management error,
or hardware error. The route specified with
the IO$_SETMODE function already exists.
Therefore, the operation failed.
SS$_ACCVIO Programming error. An attempt to access an
invalid memory location or buffer occurred.
SS$_BADPARAM Programming error. The parameter specified for
the $QIO I/O function was invalid for one of
the following reasons:
o An attempt to execute the IO$_SETMODE
functions without specifying a device
socket occurred. Instead, create a device
socket by issuing a $QIO with the IO$_
SETMODE function and the proper parameters.
o A socket option was specified incorrectly.
SS$_DEVACTIVE INET management error. You attempted to change
the static INET parameters. If you need new
parameters, shut down the internet, reset
the static parameters, and issue the START
COMMUNICATION command.
SS$_DEVINTACT INET management error. The driver is not
started. Issue a START COMMUNICATION command
before issuing $QIO functions.
SS$_DEVNOTMOUNT INET management error. The INET startup
procedure was improperly executed. The
driver was loaded, but the INET_ACP was not
activated. Execute the INET startup procedure
again.
SS$_DUPLNAM Programming error. Port that is being bound is
already in use. An attempt to bind the socket
to an address and port failed.
SS$_EXQUOTA Programming or INET management error.
o An attempt to create a new socket with the
IO$_SETMODE function and it failed because
the maximum number of sockets was exceeded.
Increase the maximum number of sockets
(INET parameter), and then create a new
socket.
o The number of sockets specified with the
IO$_SETMODE function exceeds the allowable
maximum number of sockets. Increase the
maximum number of sockets (INET parameter),
or reduce the number of sockets that
the listener socket can create (listen
parameter).
SS$_FILALRACC Programming error. Because the INET address is
already in use, an attempt to bind the socket
to an address and port failed.
SS$_INSFMEM Programming or system management error. There
are not enough resources to allocate a new
socket.
SS$_ILLCNTRFUNC Programming error. The operation is
unsupported for one of the following reasons:
o An invalid IO$_SETMODE function for the
interface was specified. The interface does
not have an IOCTL routine.
o An attempt to execute an IO$_SETMODE
function that required a socket, but the
device did not have one. Instead, create a
socket and issue the function.
SS$_IVADDR Programming error. An invalid port number and
INET address combination was specified with
the IO$_SETMODE bind function. This caused
the operation to fail for one of the following
reasons:
o An illegal combination of port zero and
INET address zero was specified.
o An attempt to make a permanent entry in
the ARP table occurred, and the operation
failed because of lack of space. There are
too many permanent entries.
o An attempt to bind a raw IP socket occurred
when there were no interfaces defined in
the system.
o An attempt to bind a raw IP socket to a
null INET address occurred.
SS$_IVBUFLEN Programming error. An invalid size was
specified for the socket option buffer.
SS$_NOLICENSE Programming or system management error. There
is no TCP/IP Services license present.
SS$_NOOPER Programming or INET management error. An
attempt to execute an I/O function that needs
the OPER privilege occurred.
SS$_NOPRIV Programming or INET management error. The
operation failed for one of the following
reasons:
o An attempt to broadcast an IP datagram for
a process without having a system UIC or
SYSPRV, BYPASS, or OPER privilege.
o An attempt to use a reserved port number
lower than 1024 occurred.
o An attempt to access a process without
having a system UIC or SYSPRV, or BYPASS
privilege occurred.
o An attempt to use raw IP on a socket that
is not a privileged socket occurred. To
do this, the process must have SYSPRV or
BYPASS privilege.
SS$_NOSUCHDEV Programming error or INET management error. An
attempt to show or delete an entry in the
ARP table occurred. However, because the
INET address was not in the ARP table, the
operation failed.
SS$_NOSUCHNODE Programming error or INET management error.
An attempt to delete a route from the routing
information table (RIT) occurred. However,
because the route was not found in the RIT,
the operation failed.
SS$_PROTOCOL Programming error.
o An invalid protocol type was specified when
creating a socket.
o An unsupported protocol was specified.
o An unsupported protocol type was specified
because it is not found in the internal
tables.
o An unsupported address family was specified
for one of the following reasons:
- An invalid address family was
specified with an IO$_SETMODE
subfunction. Instead, specify the
TCPIP$C_AF_INET or TCPIP$C_UNSPEC
address family.
- An address family of the remote INET
address for a datagram or stream
socket was specified with an IO$_
ACCESS or IO$_WRITEVBLK function.
Instead, specify the TCPIP$C_AF_INET
address family.
- An invalid address family of the
local INET address was specified
with an IO$_SETMODE bind function.
Instead, specify the TCPIP$C_AF_INET
address family.
- You made a request to the routing
module by specifying the address
family of the INET address. Instead,
specify the TCPIP$C_AF_INET address
family.
SS$_SHUT The local or remote node is no longer
accepting connections.
46. 4.11 - IO$_WRITEVBLK
The IO$_WRITEVBLK function transmits data from the specified
user buffers to an internet host. Use both p1 and p2 arguments
to specify a single user buffer. Use the p5 argument to specify
multiple buffers.
For connection-oriented protocols, such as TCP, if the socket
transmit buffer is full, the IO$_WRITEVBLK function is blocked
until the socket transmit buffer has room for the user data.
For connectless-oriented protocols, such as UDP and raw IP, the
user data is transmitted in one datagram. If the user data is
greater than the socket's transmit quota, the error code (SS$_
TOOMUCHDATA) is returned.
Related Functions
The equivalent Sockets API functions are send(), sendto(),
sendmsg(), and write().
46. 4. 11.1 - Arguments
p1
OpenVMS usage:buffer
type: vector byte (unsigned)
access: read only
mechanism: by 32- or 64-bit reference (Alpha)
by 32-bit reference (VAX)
The 32- or 64-bit address (on Alpha systems) or the 32-bit
address (on VAX systems) of the buffer containing the data to
be transmitted. The length of this buffer is specified by the p2
argument.
p2
OpenVMS usage:buffer_length
type: quadword unsigned (Alpha); longword unsigned (VAX)
access: read only
mechanism: by 64-bit value (Alpha)
by 32-bit value (VAX)
The length (in bytes) of the buffer containing data to be
transmitted. The address of this buffer is specified by the p1
argument.
p3
OpenVMS usage:socket_name
type: vector byte (unsigned)
access: read only
mechanism: by item_list_2 descriptor
The remote port number and internet address of the message
destination. The p3 argument is the address of an item_list_2
descriptor pointing to the socket address structure containing
the remote port number and internet address.
p4
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Longword of flags to specify attributes for this write operation.
The following table lists the available write flags:
Write Flag Description
TCPIP$C_MSG_OOB Writes an out-of-band (OOB) byte.
TCPIP$C_MSG_ Sends message directly without routing.
DONTROUTE
TCPIP$C_MSG_NBIO Completes the I/O operation and returns
an error if a condition arises that would
cause the I/O operation to be blocked.
(Similar to using IO$M_NOWAIT.)
p5
OpenVMS usage:buffer_list
type: vector byte (unsigned)
access: read only
mechanism: by 32- or 64-bit descriptor-fixed-length descriptor
(Alpha)
by 32-bit descriptor-fixed-length descriptor (VAX)
Input buffer list describing one or more buffers containing the
data to be transmitted. The p5 argument is the 32- or 64-bit
address (on Alpha systems) or the 32-bit address (on VAX systems)
of a descriptor pointing to a input buffer list. Buffers are
transmitted in the order specified by the input buffer list. The
transfer-length value returned in the I/O status block is the
total number of bytes transferred from all buffers.
If you use the p1 and p2 arguments, do not use the p5 argument;
they are mutually exclusive.
46. 4. 11.2 - Function Modifiers
IO$M_EXTEND Allows the use of extended modifiers with BSD
Version 4.4. Valid only for datagram sockets
(UDP or raw IP); ignored for TCP.
IO$M_INTERRUPT Sends an OOB message.
IO$M_NOWAIT Regardless of a $QIO or $QIOW, if the system
detects a condition that would cause the
operation to block, the system completes the
I/O operation and returns the SS$_SUSPENDED
status code.
When using this function modified, always
check the message length in the IOSB to ensure
that all data is transferred. IO$_WRITEVBLK
returns a success status even if data is only
partially transferred.
46. 4. 11.3 - Condition Values Returned
SS$_ABORT Programming error, INET management error, or
hardware error. The execution of the I/O was
aborted.
SS$_ACCVIO Programming error. An attempt was made to
access an invalid memory location or buffer.
SS$_BADPARAM Programming error. A $QIO I/O function was
specified using an invalid parameter.
o An attempt was made to execute an
IO$_WRITEVBLK function without specifying a
device socket. First create a device socket
by issuing an IO$_SETMODE function and the
proper arguments.
o An attempt was made to issue an
IO$_WRITEVBLK function that did not specify
a correct buffer address (p1 or p5 is
null).
o An attempt was made to issue an IO$_
WRITEVBLK that specifies an invalid
vectored buffer (p5 specifies an invalid
address descriptor).
SS$_CANCEL The I/O operation was canceled by the $CANCEL
system service.
SS$_DEVINTACT The network driver was not started.
SS$_DEVNOTMOUNT The network driver is loaded, but the INETACP
in not currently available for use.
SS$_EXQUOTA Returned when process resource mode wait is
disabled. There is no internet request packet
(IRP) available for completing the request.
Increase the buffered I/O quota.
SS$_FILALRACC Programming error.
o INET address is already in use. An attempt
was made to bind the socket to an address
but the port failed.
o IP protocol (raw socket). An attempt was
made to specify a remote INET socket
address with an IO$_WRITEVBLK function,
while an INET address was already specified
with an IO$_ACCESS function.
o UDP/IP protocol. An attempt was made to
specify a remote INET socket address with
an IO$_WRITEVBLK function, while an INET
address was already specified with the IO$_
ACCESS function.
SS$_ILLCNTRFUNC Programming error. Unsupported operation on
the protocol (IP, UDP/IP, TCP/IP).
SS$_INSFMEM INET management or programming error returned
when process resource mode wait is disabled.
Not enough system space for buffering user
data. A higher quota for socket buffer space
needs to be set, or the internet needs more
dynamic buffer space (number of dynamic
clusters should be increased).
SS$_IVADDR Programming error. The specified INET address
is not in the system, and an invalid port
number or an INET address combination was
specified with an IO$_WRITEVBLK operation.
o An attempt to bind the socket failed
because the INET address is not in the
system, port number zero and INET address
zero are not allowed, or port zero is not
allowed with an IO$_ACCESS or IO$_WRITEVBLK
function.
o An attempt to get an interface INET
address, broadcast mask, or network mask
failed.
o A send request was made on a datagram-
oriented protocol, but the destination
address is unknown or not specified.
SS$_IVBUFLEN Programming error.
o The size of the buffer for an I/O function
is insufficient.
o An attempt was made to issue an
IO$_WRITEVBLK function that specifies a
correct buffer address (p1 valid) but does
not specify a buffer length (p2 is null).
SS$_LINKDISCON Notification. Connection completion return
code. The virtual circuit (TCP/IP) was closed
at the initiative of the peer. The application
must stop sending data and must either shut
down or close the socket.
SS$_PROTOCOL Programming error. The address family of
the remote INET address specified with an
IO$_WRITEVBLK function is not supported
(UDP/IP or TCP/IP). The address family should
be the TCPIP$C_AF_INET address family.
SS$_NOLINKS Programming error. The socket was not
connected (TCP/IP), or an INET port and
address were not specified with an IO$_ACCESS
(UDP/IP or IP).
o An IO$_WRITEVBLK with no remote INET socket
address was issued on a socket that was not
the object of an IO$_ACCESS function (raw
IP).
o An IO$_WRITEVBLK with no remote INET socket
address was issued on a socket that was
not the object of an IO$_ACCESS function
(UDP/IP).
o An attempt was made to disconnect a socket
that is not connected, or an attempt was
made to issue an IO$_WRITEVBLK function on
an unconnected socket (TCP/IP).
SS$_SHUT The local or remote node is no longer
accepting connections.
SS$_SUSPENDED The system detected a condition that might
cause the operation to block.
SS$_TIMEOUT Programming error, INET management error, or
hardware error.
o A TCP/IP connection timed out after several
unsuccessful retransmissions.
o On a TCP socket where KEEPALIVE is set,
the connection was idle for longer than
the timeout interval (The default is 10
minutes).
SS$_TOOMUCHDATA Programming or INET management error. The
message size was too large.
o An IP packet that is broadcast cannot be
fragmented.
o The Not Fragment IP flag was set and the IP
datagram was too large to be sent without
being fragmented.
o Internal error. The length of the Ethernet
datagram does not allow enough space for
the minimum IP header.
o The message to be sent on a UDP/IP or raw
IP socket is larger than the socket buffer
high water allows.
o An attempt was made to send or receive
more than 16 buffers specified with the p5
argument.
SS$_UNREACHABLE Communication status. The remote host is
currently unreachable.
Hardware error. The data link adapter detected
an error and shut itself off. The TCP/IP
Services software is waiting for the adapter
to come back on line.
46.5 - TELNET Port Driver QIO Interface
The TELNET port driver (TNDRIVER) provides terminal session
support for TCP stream connections using the RAW, NVT, RLOGIN,
and TELNET protocols. Either a remote device or an application
can be present at the remote endpoint of the connection.
A user program can manage a TELNET connection with the standard
OpenVMS $QIO system service by using the IO$_TTY_PORT and IO$_
TTY_PORT_BUFIO I/O function codes. This section describes these
I/O function codes and their associated arguments.
46. 5.1 - Interface Definition
The following definitions are used by the interface. The symbols
are defined in SYS$LIBRARY:TNIODEF.H.
46. 5. 1.1 - Item List Codes
List Codes for the p5 Item describes the symbols used with the p5
parameter.
Table 7 List Codes for the p5 Item
Maximum
Item Code Size Description
TN$_ACCPORNAM 64 Access port name string. When
written, the string's length is
determined by the item_length
field. The value of item_length
should not be more than 63 bytes.
When read, the string is returned
in ASCIC format (the first byte
contains the string's length), so a
size of 64 is appropriate.
TN$_ 4 Characteristics mask. This longword
CHARACTERISTICS contains a bit mask of the device's
characteristics read or to be
written. (See Characteristic Mask
Bits.)
TN$_CONNECTION_ 4 Reconnection attempts. This item
ATTEMPTS is the number of unsuccessful
reconnection attempts which have
been made on a reconnectable
device. The value will be
reinitialized when a successful
connection is made. This item is
read only.
TN$_CONNECTION_ 4 Minimum time (in seconds) before
INTERVAL reconnection attempts.
TN$_CONNECTION_ 4 Current time (in seconds) since
TIMEOUT the last reconnection attempt. This
item is read only.
TN$_DATA_HIGH 4 Maximum amount of output data (in
bytes) buffered at the network
port. This number does not affect
the amount of data buffered within
the socket.
TN$_DEVICE_UNIT 4 Terminal device unit number. When
written, this value must be between
1 and 9999.
TN$_IDLE_INTERVAL 4 Maximum idle time (in seconds)
allowed before a connection is
to be broken. Connections are not
broken if the device is stalled.
TN$_IDLE_TIMEOUT 4 Current time (in seconds) since
last output on the terminal. This
item is read only.
TN$_LOCAL_ADDRESS 32 Local sockaddr of the active
connection. When written, the
value of item_length determines
the size of the sockaddr. Note that
the sockaddr is in BSD Version 4.4
format, which includes a sockaddr
size field. (C programs should be
compiled with the _SOCKADDR_LEN
symbol defined.) This item is read
only.
TN$_NETWORK_ 64 Name of the network pseudodevice
DEVICE_NAME currently bound to the terminal.
When read, the data is returned
in ASCIC format (the first byte
contains the string's length). This
item is read only.
TN$_PROTOCOL 4 Session protocol. (See Protocol
Type Codes.)
TN$_REMOTE_ADDRESS 32 Remote peer's sockaddr of the
active connection. Note that
the sockaddr is in BSD Version
4.4 format, which includes a
sockaddr size field. The size of
the sockaddr should be determined
from this field. This item is read
only.
TN$_SERVICE_TYPE 4 Class of terminal service. (See
Service Type Codes.)
TN$_STATUS 4 Current device and session status.
This item is read only.
46. 5. 1.2 - Characteristic Mask Bits
Characteristic Mask Bits describes the characteristic mask bits
used with the p5 parameter.
Table 8 Characteristic Mask Bits
Characteristic Description
TN$M_AUTOCONNECT The device supports automatic
connect/reconnect.
TN$M_LOGIN_ON_ Initiate a login when the TELNET device is
DASSGN deassigned. This characteristic requires the
BYPASS or SYSNAM privilege or executive or
kernel mode calls.
TN$M_LOGIN_TIMER Used in conjunction with TN$M_LOGIN_ON_DASSGN,
this bit indicates that the login completion
timer applies. If the TN device fails to
login within 60 seconds, the connection will
be broken and the device deallocated. This
characteristic requires the BYPASS or SYSNAM
privileges or executive or kernel mode calls.
TN$M_PERMANENT_ The TELNET device is to remain until
UCB explicitly deleted.
TN$M_RETAIN_ON_ The TELNET device is not to be deleted upon
DASSGN the deassignment of the last channel to this
device. This condition is cleared on this
last deassignment, so that a subsequent assign
and deassign will result in the device being
deleted.
TN$M_VIRTUAL_ When logging in under this device, a virtual
TERMINAL terminal is to be created by TTDRIVER.
46. 5. 1.3 - Protocol Types
Protocol Type Codes describes the protocol types used with the p5
parameter.
Table 9 Protocol Type Codes
Protocol Type Description
TN$K_PROTOCOL_ There is no explicit protocol for this
UNDEFINED session. Data is transmitted and received
on the socket without any interpretation.
This is a raw connection.
TN$K_PROTOCOL_NVT Network Virtual Terminal (NVT) protocol.
The protocol understands basic session
control but does not include the options
negotiation present in the TELNET
protocol.
TN$K_PROTOCOL_RLOGIN BSD Remote Login protocol. This simple
protocol provides some special control
character support but lacks the
architecture independence of the NVT and
TELNET protocols.
TN$K_PROTOCOL_TELNET TELNET protocol. Including the basic NVT
protocol, TELNET adds support for options
negotiation. This can provide an enhanced
terminal session depending upon the client
and server involved.
46. 5. 1.4 - Service Types
Service Type Codes describes the service type codes used with the
p5 parameter.
Table 10 Service Type Codes
Service Type Description
TN$K_SERVICE_NONE The service type is not currently known.
TN$K_SERVICE_ The service is an incoming connection.
INCOMING
TN$K_SERVICE_ The service is an outgoing connection.
OUTGOING
46. 5.2 - Passing Parameters to the TELNET Port Driver
The IO$_TTY_PORT function is used to pass $QIO parameters
through the terminal driver to the TELNET port driver. The actual
subfunction is encoded as an option mask and may be:
o IO$M_TN_STARTUP - Bind socket to a TELNET terminal.
o IO$M_TN_SHUTDOWN - Unbind socket from a TELNET terminal.
46.6 - IO$_TTY_PORT|IO$M_TN_STARTUP
Bind socket to a TELNET terminal.
This subfunction will bind a created (connected) socket to a
TELNET terminal device.
46. 6.1 - Arguments
p1
OpenVMS usage:channel
type: word (unsigned)
access: read only
mechanism: by value
The p1 argument contains the channel number of the socket over
which the TELNET session is to be established.
p2
OpenVMS usage:protocol_number
type: longword (unsigned)
access: read only
mechanism: by value
The p2 argument contains the protocol selection.
p3
OpenVMS usage:characteristics_mask
type: longword (unsigned)
access: read only
mechanism: by value
The p3 argument specifies a mask of characteristics to apply
against the connection. See Characteristic Mask Bits for possible
values.
46. 6.2 - Description
The IO$M_TN_STARTUP subfunction allows the application to
communicate over a socket using the terminal driver QIO
interface. Note that incoming and outgoing data is processed
by the terminal driver, and that the terminal's characteristics
may affect the format of the data. Be aware that by default, the
terminal will echo incoming data back to the sender.
Once the subfunction completes, the application is free to
perform all terminal QIO functions on the connection. While the
socket is bound to a terminal device, it will process neither the
IO$_READxBLK nor the IO$_WRITExBLK function, and will return the
error SS$_DEVINUSE.
46. 6.3 - Condition Values Returned
SS$_IVCHAN Programming error. The specified channel is
not valid.
SS$_IVMODE Programming error. The access mode of the
channel is more privileged than the access
mode of the terminal's channel.
SS$_NOPRIV Programming error. The TN$M_LOGIN_ON_
DASSGN characteristic was specified in a
characteristics mask from a QIO in USER or
SUPERVISOR mode without either the BYPASS or
SYSPRV privilege.
SS$_NOTNETDEV Programming error. The specified channel is an
assignment to a non-BG device.
SS$_PROTOCOL Programming error. The specified protocol
number is not valid, or the internet network
is not available.
46.7 - IO$_TTY_PORT|IO$M_TN_SHUTDOWN
Unbind socket from a TELNET terminal.
This subfunction will unbind a previously bound socket-terminal
connection.
46. 7.1 - Arguments
p1
OpenVMS usage:channel
type: word (unsigned)
access: read only
mechanism: by value
The p1 argument contains the channel number of the socket to
establish the TELNET session.
46. 7.2 - Description
The IO$M_TN_SHUTDOWN subfunction allows the application to break
a previously bound socket-terminal connection (created with IO$M_
TN_STARTUP). The channel must be from an assignment to the same
network pseudodevice in the socket-terminal connection.
Upon completion, the application retains the assignments to
the connection and the TELNET terminal, but they are no longer
related. Any subsequent IO$_READxBLK or IO$_WRITExBLK function on
the socket channel will no longer return the error SS$_DEVINUSE.
46. 7.3 - Condition Values Returned
SS$_IVCHAN Programming error. The specified channel is
not valid.
SS$_IVMODE Programming error. The access mode of the
channel is more privileged than the access
mode of the terminal's channel.
SS$_NOTNETDEV Programming error. The specified channel is an
assignment to a non-BG device.
SS$_DEVREQERR Programming error. The device on the channel
does not match the device in the socket-
terminal connection.
46. 7.4 - Buffered Reading and Writing of Item Lists
The IO$_TTY_PORT_BUFIO function is used to pass $QIO parameters
through the terminal driver to the TELNET port driver. IO$_TTY_
PORT_BUFIO differs from IO$_TTY_PORT in that certain subfunctions
accept buffered item lists for reading or writing parameters to
the terminal device.
o IO$M_TN_SENSEMODE - Read device parameters.
o IO$M_TN_SETMODE - Write device parameters.
The subfunctions of IO$_TTY_PORT_BUFIO accept an item list for
input or output. Subfunction Item List shows the format of this
item list.
The item list is terminated with an item_code and item_length,
both of which are zero.
The subfunctions of IO$_TTY_PORT_BUFIO can be combined into
a single QIO. For example, the IO$M_TN_SETMODE and IO$M_TN_
CONNECT can be combined to set the device's parameters and then
to attempt to make a connection.
The subfunctions are performed in the following order:
1. IO$M_TN_SETMODE
2. IO$M_TN_CONNECT
3. IO$M_TN_SENSEMODE
4. IO$M_TN_DISCON
NOTE
Certain items are read only (IO$M_TN_SENSEMODE) and cannot
be written (IO$M_TN_SETMODE). Normally, attempting to write
such items would result in the error SS$_BADATTRIB. However,
if a combination operation (IO$M_TN_SENSEMODE|IO$M_TN_
SETMODE) is being performed, these items will not result
in an error. Rather, the items will be ignored in the IO$M_
TN_SETMODE processing, and the QIO will continue with IO$M_
TN_SENSEMODE processing, returning the information that the
item specifies.
46. 7.5 - IO$_TTY_PORT_BUFIO|IO$M_TN_SENSEMODE
Read device parameters.
46. 7. 5.1 - Arguments
p5
OpenVMS usage:item_list_2
type: vector byte (unsigned)
access: read only
mechanism: by reference
The p5 argument is the address of an item list that contains a
summary of information to be read from the device.
46. 7. 5.2 - Description
The IO$M_TN_SENSEMODE subfunction of IO$_TTY_PORT_BUFIO is used
to read the parameters associated with a device.
46. 7. 5.3 - Condition Values Returned
SS$_BADATTRIB Programming error. The item code within the
list is not valid. This could be because of
its code, an attempt to write a read-only
parameter, or inappropriate size. The address
of the item's buffer is returned in the second
longword of the I/O status block.
SS$_IVBUFLEN Programming error. The length of the specified
item is not acceptable. The address of the
item's buffer is returned in the second
longword of the I/O status block.
SS$_NOPRIV Programming error. An item that requires a
privilege which the requestor does not have
is present in the item list. The address of
the item's buffer is returned in the second
longword of the I/O status block.
46. 7.6 - IO$_TTY_PORT_BUFIO|IO$M_TN_SETMODE
Write device parameters.
46. 7. 6.1 - Arguments
p5
OpenVMS usage:item_list_2
type: vector (byte unsigned)
access: read only
mechanism: by reference
The p5 argument is the address of an item list that contains a
summary of information to be written to the device.
46. 7. 6.2 - Description
The IO$M_TN_SETMODE subfunction of IO$_TTY_PORT_BUFIO is used to
write the parameters associated with a device.
46. 7. 6.3 - Condition Values Returned
SS$_BADATTRIB Programming error. The item code within the
list is not valid. This could be because of
its code, an attempt to write a read-only
parameter, or inappropriate size. The address
of the item's buffer is returned in the second
longword of the I/O status block.
SS$_DUPLNAM Programming error. An attempt to set the
device's unit number via the TN$_DEVICE_UNIT
item has failed because that specified unit
number was already present.
SS$_IVBUFLEN Programming error. The length of the specified
item is not acceptable. The address of the
item's buffer is returned in the second
longword of the I/O status block.
SS$_NOPRIV Programming error. An item that requires a
privilege which the requester does not have
is present in the item list. The address of
the item's buffer is returned in the second
longword of the I/O status block.
|
|
