TCP/IP Services includes a standard C sockets API and a standard
Open Network Computing Remote Procedure Call (ONC RPC) API.
The standard C socket API provides UNIX-style access to the TCP
and UDP transports and to the IP network layer.
The ONC RPC library provides a method of creating communicating
programs without the need to program the details of the transport
protocol being used. The ONC RPC library is divided into calls
frequently used by client programs, calls used to access the
Portmapper utility, and calls frequently used by server programs.
The ONC RPC library also includes XDR routines which provide
the ability to transport data over the network in a standard
fashion.
1 – RPC Client Routines
Client routines allow C programs to make procedure calls to
server programs across the network.
Important: In order to maintain uniqueness for the OpenVMS HELP
utility, some client routines have a "_#" appended at the end. Do
not use the "_#" when coding the routine in a program.
1.1 – auth_destroy
A macro that frees the memory associated with the authentication
handle created by the authnone_create and authunix_create
routines.
Format
#include <rpc/rpc.h>
void auth_destroy(AUTH *auth_handle)
1.1.1 – Arguments
auth_handle
An RPC authentication handle created by the authnone_create,
authunix_create, or authunix_create_default routine.
1.1.2 – Description
Frees the memory associated with the AUTH data structure created
by the authnone_create, authunix_create, or authunix_create_
default routine. Be careful not to reference the data structure
after calling this routine.
1.1.3 – Return Values
None
1.2 – authnone_create
Creates an authentication handle for passing null credentials and
verifiers to remote systems.
Format
#include <rpc/rpc.h>
AUTH *authnone_create ( )
1.2.1 – Arguments
None
1.2.2 – Description
Creates and returns an authentication handle that passes
null authentication information with each remote procedure
call. Use this routine if the server process does not require
authentication information. RPC uses this routine as the default
authentication routine unless you create another authentication
handle using either the authunix_create or authunix_create_
default routine.
1.2.3 – Return Values
AUTH * Authentication handle containing the pertinent
information.
NULL Indicates allocation of AUTH handle failed.
1.3 – authunix_create
Creates and returns an RPC authentication handle that contains
UNIX-style authentication information.
Format
#include <rpc/rpc.h>
AUTH *authunix_create(char *host, int uid, int gid, int len,
int *aup_gids );
1.3.1 – Arguments
host
Pointer to the name of the host on which the information was
created. This is usually the name of the system running the
client process.
uid
The user's user identification.
gid
The user's current group.
len
The number of elements in aup_gids array.
NOTE
This parameter is ignored by the product's RPC
implementation.
aup_gids
A pointer to an array of groups to which the user belongs.
NOTE
This parameter is ignored by the product's RPC
implementation.
1.3.2 – Description
Implements UNIX-style authentication parameters. The client uses
no encryption for its credentials and only sends null verifiers.
The server sends back null verifiers or, optionally, a verifier
that suggests a new shorthand for the credentials.
1.3.3 – Return Values
AUTH * Authentication handle containing the pertinent
information.
NULL Indicates allocation of AUTH handle failed.
1.4 – authunix_create_default
Returns a default authentication handle.
Format
#include <rpc/rpc.h>
AUTH *authunix_create_default( )
1.4.1 – Arguments
None
1.4.2 – Description
Calls the authunix_create routine with the local host name,
effective process ID and group ID, and the process default
groups.
1.4.3 – Return Values
AUTH * Authentication handle containing the pertinent
information.
NULL Indicates allocation of AUTH handle failed.
1.4.4 – Examples
1.auth_destroy(client->cl_auth)
client->cl_auth = authunix_create_default();
This example overrides the default authnone_create action. The
client handle, client, is returned by the clnt_create, clnt_
create_vers, clnttcp_create, or clntudp_create routine.
1.5 – callrpc
Executes a remote procedure call.
Format
#include <rpc/rpc.h>
int callrpc(char *host, u_long prognum, u_long versnum, u_long
procnum, xdrproc_t inproc, char *in, xdrproc_t outproc,
char *out);
1.5.1 – Arguments
host
A pointer to the name of the host on which the remote procedure
resides.
prognum
The program number associated with the remote procedure.
versnum
The version number associated with the remote procedure.
procnum
The procedure number associated with the remote procedure.
inproc
The XDR routine used to encode the remote procedure's arguments.
in
A pointer to the remote procedure's arguments.
outproc
The XDR routine used to decode the remote procedure's results.
out
A pointer to the remote procedure's results.
1.5.2 – Description
Calls the remote procedure associated with prognum, versnum,
and procnum on the host host. This routine performs the same
functions as a set of calls to the clnt_create, clnt_call, and
clnt_destroy routines. This routine returns RPC_SUCCESS if it
succeeds, or the value of enum clnt_stat cast to an integer if it
fails. The routine clnt_perrno is handy for translating a failure
status into a message.
NOTE
Calling remote procedures with this routine uses UDP/IP as
a transport; see clntudp_create for restrictions. You do
not have control of timeouts or authentication using this
routine. If you want to use the TCP transport, use the clnt_
create or clnttcp_create routine.
1.5.3 – Return Values
RPC_SUCCESS Indicates success.
clnt_stat Returns a value of type enum clnt_stat cast to
type int containing the status of the callrpc
operation.
1.6 – clnt_broadcast
Executes a remote procedure call that is sent to all locally
connected networks using the broadcast address.
Format
#include <rpc/rpc.h>
enum clnt_stat clnt_broadcast(u_long prognum, u_long versnum,
u_long procnum, xdrproc_t inproc, char * in,
xdrproc_t outproc, char * out, resultproc_t
eachresult);
1.6.1 – Arguments
prognum
The program number associated with the remote procedure.
versnum
The version number associated with the remote procedure.
procnum
The procedure number associated with the remote procedure.
inproc
The XDR routine used to encode the remote procedure's arguments.
in
A pointer to the remote procedure's arguments.
outproc
The XDR routine used to decode the remote procedure's results.
out
A pointer to the remote procedure's results.
eachresult
Called each time the routine receives a response. Specify the
routine as follows:
int eachresult(char *resultsp, struct sockaddr_in *addr)
resultsp is the same as the parameter passed to clnt_broadcast(),
except that the remote procedure's output is decoded there. addr
is a pointer to a sockaddr_in structure containing the address of
the host that sent the results.
If eachresult is NULL, the clnt_broadcast routine returns without
waiting for any replies.
1.6.2 – Description
Performs the same function as the callrpc routine, except that
the call message is sent to all locally connected networks using
the broadcast address. Each time it receives a response, this
routine calls the eachresult routine. If eachresult returns
zero, clnt_broadcast waits for more replies; otherwise it assumes
success and returns RPC_SUCCESS.
NOTE
This routine uses the UDP protocol. Broadcast sockets are
limited in size to the maximum transfer unit of the data
link. For Ethernet, this value is 1400 bytes. For FDDI, this
value is 4500 bytes.
1.6.3 – Return Values
RPC_SUCCESS Indicates success.
clnt_stat Returns the buffer of type enum clnt_stat
containing the status of the clnt_broadcast
operation.
1.7 – clnt_call
A macro that calls a remote procedure.
Format
#include <rpc/rpc.h>
enum clnt_stat clnt_call(CLIENT *handle, u_long procnum,
xdrproc_t inproc, char *in, xdrproc_t outproc,
char *out, struct timeval timeout);
1.7.1 – Arguments
handle
A pointer to a client handle created by any of the client-handle
creation routines.
procnum
The procedure number associated with the remote procedure.
inproc
The XDR routine used to encode the remote procedure's arguments.
in
A pointer to the remote procedure's arguments.
outproc
The XDR routine used to decode the remote procedure's results.
out
A pointer to the remote procedure's results.
timeout
A structure describing the time allowed for results to return to
the client. If you have previously used the clnt_control macro
with the CLSET_TIMEOUT code, this value is ignored.
1.7.2 – Description
Use the clnt_call macro after using one of the client-handle
creation routines. After you are finished with the handle, return
it using the clnt_destroy macro. Use the clnt_perror to print any
errors that occurred.
1.7.3 – Return Values
RPC_SUCCESS Indicates success.
clnt_stat Returns the buffer of type enum clnt_stat
containing the status of the clnt_call
operation.
1.8 – clnt_control
A macro that changes or retrieves information about an RPC client
process.
Format
#include <rpc/rpc.h>
bool_t clnt_control(CLIENT *handle, u_int code, char *info);
1.8.1 – Arguments
handle
A pointer to a client handle created by any of the client-handle
creation routines.
code
A code designating the type of information to be set or
retrieved.
info
A pointer to a buffer containing the information for a SET
operation or the results of a GET operation.
1.8.2 – Description
For UDP and TCP transports specify any of the following for code:
CLSET_TIMEOUT struct Set total timeout
timeval
CLGET_TIMEOUT struct Get total timeout
timeval
CLGET_SERVER_ADDR struct Get server address
sockaddr_
in
CLGET_FD int Get associated socket
CL_FD_CLOSE void Close socket on clnt_destroy
CL_FD_NCLOSE void Leave socket open on clnt_
destroy
If you set the timeout using clnt_control, ONC RPC ignores the
timeout parameter in all future clnt_call calls. The default
total timeout is 25 seconds.
For the UDP transport two additional options are available:
CLSET_RETRY_ struct Set retry timeout
TIMEOUT timeval
CLGET_RETRY_ struct Get retry timeout
TIMEOUT timeval
The timeout value in these two calls is the time that UDP waits
for a response before retransmitting the message to the server.
The default time is 5 seconds. The retry timeout controls when
UDP retransmits the request; the total timeout controls the total
time that the client should wait for a response. For example,
with the default settings, UDP will retry the transmission four
times at 5-second intervals.
1.8.3 – Return Values
TRUE Success
FALSE Failure
1.9 – clnt_create_#
Creates a client handle and returns its address.
Format
#include <rpc/rpc.h>
CLIENT *clnt_create(char *host, u_long prognum, u_long
versnum, char *protocol);
1.9.1 – Arguments
host
A pointer to the name of the remote host.
prognum
The program number associated with the remote procedure.
versnum
The version number associated with the remote procedure.
protocol
A pointer to a string containing the name of the protocol for
transmitting and receiving RPC messages. Specify either tcp or
udp.
1.9.2 – Description
The clnt_create routine creates an RPC client handle for prognum.
An RPC client handle is a structure containing information about
the RPC client. The client can use the UDP or TCP transport
protocol.
This routine uses the Portmapper. You cannot control the local
port.
The default sizes of the send and receive buffers are 8800 bytes
for the UDP transport, and 4000 bytes for the TCP transport. The
retry time for the UDP transport is five seconds.
Use the clnt_create routine instead of the callrpc or clnt_
broadcast routines if you want to use one of the following:
o The TCP transport
o A non-null authentication
o More than one active client at the same time
You can also use the clnttcp_create routine to use the TCP
protocol, or the clntudp_create routine to use the UDP protocol.
The clnt_create routine uses the global variable rpc_createerr.
rpc_createerr is a structure that contains the most recent
service creation error. Use rpc_createerrif you want the client
program to handle the error. The value of rpc_createerr is set by
any RPC client creation routine that does not succeed.
NOTE
If the requested program is available on the host but the
program does not support the requested version number, this
routine still succeeds. A subsequent call to the clnt_call
routine will discover the version mismatch. Use the clnt_
create_vers routine if you want to avoid this condition.
1.9.3 – Return Values
CLIENT * Client handle containing the server
information.
NULL Error occurred while creating the client
handle. Use the clnt_pcreateerror or clnt_
spcreateerror routine to obtain diagnostic
information.
1.10 – clnt_create_vers
Creates a client handle and returns its address. Seeks to use a
server supporting the highest version number within a specified
range.
Format
#include <rpc/rpc.h>
CLIENT *clnt_create_vers(char *host, u_long prognum, u_long
*versnum, u_long min_vers, u_long max_vers, char
*protocol);
1.10.1 – Arguments
host
A pointer to the name of the remote host.
prognum
The program number associated with the remote procedure.
versnum
The version number associated with the remote procedure. This
value is returned by the routine. The value is the highest
version number supported by the remote server that is in the
range of version numbers specified by min_vers and max_vers. The
argument may remain undefined; see additional information in the
Description section.
min_vers
The minimum acceptable version number for the remote procedure.
max_vers
The maximum acceptable version number for the remote procedure.
protocol
A pointer to a string containing the name of the protocol for
transmitting and receiving RPC messages. Specify either tcp or
udp.
1.10.2 – Description
The clnt_create_vers routine creates an RPC client handle
for prognum. An RPC client handle is a structure containing
information about the RPC client. The client can use the UDP
or TCP transport protocol.
This routine uses the Portmapper. You cannot control the local
port.
The default sizes of the send and receive buffers are 8800 bytes
for the UDP transport, and 4000 bytes for the TCP transport. The
retry time for the UDP transport is 5 seconds.
The clnt_create_vers routine differs from the standard clnt_
create routine in that it seeks out the highest version number
supported by the server. If the server does not support any
version numbers within the requested range, the routine returns
NULL and the versnum variable is undefined.
The clnt_create_vers routine uses the global variable rpc_
createerr. rpc_createerr is a structure that contains the most
recent service creation error. Use rpc_createerr if you want the
client program to handle the error. The value of rpc_createerr is
set by any RPC client creation routine that does not succeed.
1.10.3 – Return Values
CLIENT * Clien-thandle containing the server
information.
NULL Error occurred while creating the client
handle. Usually the error indicates that the
server does not support any version numbers
within the requested range. Use the clnt_
pcreateerror or clnt_spcreateerror routine to
obtain diagnostic information.
1.11 – clnt_destroy
A macro that frees the memory associated with an RPC client
handle.
Format
#include <rpc/rpc.h>
void clnt_destroy(CLIENT *handle);
1.11.1 – Arguments
handle
A pointer to a client handle created by any of the client-handle
creation routines.
1.11.2 – Description
The clnt_destroy routine destroys the client's RPC handle by
deallocating all memory related to the handle. The client is
undefined after the clnt_destroy call.
If the clnt_create routine had previously opened the socket
associated with the client handle or the program had used the
clnt_control routine to set CL_FD_CLOSE, this routine closes the
socket. If the clnt_create routine had not previously opened the
socket associated with the client handle or the program had used
the clnt_control routine to set CL_FD_NCLOSE, this routine leaves
the socket open.
1.11.3 – Return Values
None
1.12 – clnt_freeres
A macro that frees the memory that was allocated when the remote
procedure's results were decoded.
Format
#include <rpc/rpc.h>
bool_t clnt_freeres(CLIENT *handle, xdrproc_t outproc, char
*out);
1.12.1 – Arguments
handle
A pointer to a client handle created by any of the client-handle
creation routines.
outproc
The XDR routine used to decode the remote procedure's results.
out
A pointer to the remote procedure's results.
1.12.2 – Description
The clnt_freeres routine calls the xdr_free routine to deallocate
the memory where the remote procedure's results are stored.
1.12.3 – Return Values
TRUE Success.
FALSE Error occurred while freeing the memory.
1.13 – clnt_geterr
A macro that returns error information indicating why an RPC call
failed.
Format
#include <rpc/rpc.h>
void clnt_geterr(CLIENT *handle, struct rpc_err *errp);
1.13.1 – Arguments
handle
A pointer to a client handle created by any of the client-handle
creation routines.
errp
A pointer to an rpc_err structure containing information that
indicates why an RPC call failed. This information is the same
information as clnt_stat contains, plus one of the following:
the C error number, the range of server versions supported, or
authentication errors.
1.13.2 – Description
This macro copies the error information from the client handle
to the structure referenced by errp. The macro is mainly for
diagnostic use.
1.13.3 – Return Values
None
1.14 – clnt_pcreateerror
Prints a message explaining why ONC RPC could not create a client
handle.
Format
#include <rpc/rpc.h>
void clnt_pcreateerror(char *sp);
1.14.1 – Arguments
sp
A pointer to a string to be used as the beginning of the error
message.
1.14.2 – Description
The clnt_pcreateerror routine prints a message to SYS$OUTPUT. The
message consists of the sp parameter followed by an RPC-generated
error message. Use this routine when the clnt_create, clnttcp_
create, or clntudp_create routine fails.
1.14.3 – Return Values
None
1.15 – clnt_perrno
Prints a message indicating why the callrpc or clnt_broadcast
routine failed.
Format
#include <rpc/rpc.h>
void clnt_perrno(enum clnt_stat stat) ;
1.15.1 – Arguments
stat
A buffer containing status information.
1.15.2 – Description
Prints a message to standard error corresponding to the condition
indicated by the stat argument.
The data type declaration for clnt_stat in rpc/rpc.h lists the
standard errors.
1.15.3 – Return Values
None
1.16 – clnt_perror
Prints a message explaining why an ONC RPC routine failed.
Format
#include <rpc/rpc.h>
void clnt_perror(CLIENT *handle, char *sp);
1.16.1 – Arguments
handle
A pointer to the client handle used in the call that failed.
sp
A pointer to a string to be used as the beginning of the error
message.
1.16.2 – Description
Prints a message to standard error indicating why an ONC RPC call
failed. The message is prepended with string sp and a colon.
1.16.3 – Return Values
None
1.17 – clnt_spcreateerror
Returns a message indicating why RPC could not create a client
handle.
Format
#include <rpc/rpc.h>
char *clnt_spcreateerror(char *sp);
1.17.1 – Arguments
sp
A pointer to a string to be used as the beginning of the error
message.
1.17.2 – Description
The clnt_spcreateerror routine returns the address of a message
string. The message consists of the sp parameter followed by an
error message generated by calling the clnt_sperrno routine. Use
the clnt_spcreateerror routine when the clnt_create, clnttcp_
create, or clntudp_create routine fails.
Use this routine if:
o You want to save the string.
o You do not want to use fprintf to print the message.
o The message format is different from the one that clnt_perrno
supports.
The address that clnt_spcreateerror returns is the address of
its own internal string buffer. The clnt_spcreateerror routine
overwrites this buffer with each call. Therefore, you must copy
the string to your own buffer if you wish to save the string.
1.17.3 – Return Values
char * A pointer to the message string terminated
with a NULL character.
NULL The routine was not able to allocate its
internal buffer.
1.18 – clnt_sperrno
Returns a message indicating why the callrpc or clnt_broadcast
routine failed to create a client handle.
Format
#include <rpc/rpc.h>
char *clnt_sperrno(enum clnt_stat stat);
1.18.1 – Arguments
stat
A buffer containing status information.
1.18.2 – Description
The clnt_sperrno routine returns a pointer to a string.
Use this routine instead if:
o The server does not have a stderr file; many servers do not.
o You want to save the string.
o You do not want to use fprintf to print the message.
o The message format is different from the one that clnt_perrno
supports.
The address that clnt_sperrno returns is a pointer to the error
message string for the error. Therefore, you do not have to copy
the string to your own buffer in order to save the string.
1.18.3 – Return Values
char * A pointer to the message string terminated
with a NULL character.
1.19 – clnt_sperror
Returns a message indicating why an ONC RPC routine failed.
Format
#include <rpc/rpc.h>
char *clnt_sperror(CLIENT *handle, char *sp);
1.19.1 – Arguments
handle
A pointer to the client handle used in the call that failed.
sp
A pointer to a string to be used as the beginning of the error
message.
1.19.2 – Description
The clnt_sperror routine returns a pointer to a message string.
The message consists of the sp parameter followed by an error
message generated by calling the clnt_sperrno routine. Use this
routine when the clnt_call routine fails.
Use this routine if:
o You want to save the string.
o You do not want to use fprintf to print the message.
o The message format is different from the one that clnt_perrno
supports.
The address that clnt_sperror returns is a pointer to its own
internal string buffer. The clnt_sperror routine overwrites this
buffer with each call. Therefore, you must copy the string to
your own buffer if you wish to save the string.
1.19.3 – Return Values
char * A pointer to the message string terminated
with a NULL character.
NULL The routine was not able to allocate its
internal buffer.
1.20 – clntraw_create
Creates a client handle for memory-based ONC RPC for simple
testing and timing.
Format
#include <rpc/rpc.h>
CLIENT *clntraw_create(u_long prognum, u_long versnum);
1.20.1 – Arguments
prognum
The program number associated with the remote program.
versnum
The version number associated with the remote program.
1.20.2 – Description
Creates an in-program ONC RPC client for the remote program
prognum, version versnum. The transport used to pass messages
to the service is actually a buffer within the process's address
space, so the corresponding server should live in the same
address space; see svcraw_create. This allows simulation of
and acquisition of ONC RPC overheads, such as round-trip times,
without any kernel interference.
1.20.3 – Return Values
CLIENT * A pointer to a client handle.
NULL Indicates failure.
1.21 – clnttcp_create
Creates an ONC RPC client handle for a TCP/IP connection.
Format
#include <rpc/rpc.h>
CLIENT *clnttcp_create(struct sockaddr_in *addr, u_long
prognum, u_long versnum, int *sockp, u_int sendsize,
u_int recvsize);
1.21.1 – Arguments
addr
A pointer to a buffer containing the Internet address where the
remote program is located.
prognum
The program number associated with the remote procedure.
versnum
The version number associated with the remote procedure.
sockp
A pointer to the socket number to be used for the remote
procedure call. If sockp is RPC_ANYSOCK, then this routine opens
a new socket and sets sockp.
sendsize
The size of the send buffer. If you specify zero, the routine
chooses a suitable default.
recvsize
The size of the receive buffer. If you specify zero, the routine
chooses a suitable default.
1.21.2 – Description
Creates an ONC RPC client handle for the remote program prognum,
version versnum at address addr. The client uses TCP/IP as a
transport. The routine is similar to the clnt_create routine,
except clnttcp_create allows you to specify a socket and the send
and receive buffer sizes.
If you specify the port number as zero by using addr->sin_port,
the Portmapper provides the number of the port on which the
remote program is listening.
The clnttcp_create routine uses the global variable rpc_
createerr. rpc_createerr is a structure that contains the most
recent service creation error. Use rpc_createerr if you want the
client program to handle the error. The value of rpc_createerr is
set by any RPC client creation routine that does not succeed. The
rpc_createerr variable is defined in the CLNT.H file.
The socket referenced by sockp is copied into a private area for
RPC to use. It is the client's responsibility to close the socket
referenced by sockp.
The authentication scheme for the client, client->cl_auth, gets
set to null authentication. The calling program can set this to
something different if necessary.
NOTE
If the requested program is available on the host but the
program does not support the requested version number, this
routine still succeeds. A subsequent call to the clnt_call
routine will discover the version mismatch. Use the clnt_
create_vers routine if you want to avoid this condition.
1.21.3 – Return Values
CLIENT * A pointer to the client handle.
NULL Indicates failure.
1.22 – clntudp_bufcreate
Creates an ONC RPC client handle for a buffered I/O UDP
connection.
Format
#include <rpc/rpc.h>
CLIENT *clntudp_bufcreate(struct sockaddr_in *addr, u_long
prognum, u_long versnum, struct timeval wait, register
int *sockp, u_int sendsize, u_int recvsize);
1.22.1 – Arguments
addr
A pointer to a buffer containing the Internet address where the
remote program is located.
prognum
The program number associated with the remote procedure.
versnum
The version number associated with the remote procedure.
wait
The amount of time used between call retransmission if no
response is received. Retransmission occurs until the ONC RPC
calls time out.
sockp
A pointer to the socket number to be used for the remote
procedure call. If sockp is RPC_ANYSOCK, then this routine opens
a new socket and sets sockp.
sendsize
The size of the send buffer. If you specify zero, the routine
chooses a suitable default.
recvsize
The size of the receive buffer. If you specify zero, the routine
chooses a suitable default.
1.22.2 – Description
Creates an ONC RPC client handle for the remote program prognum,
version versnum at address addr. The client uses UDP as the
transport. The routine is similar to the clnt_create routine,
except clntudp_bufcreate allows you to specify a socket, the UDP
retransmission time, and the send and receive buffer sizes.
If you specify the port number as zero by using addr->sin_port,
the Portmapper provides the number of the port on which the
remote program is listening.
The clntudp_bufcreate routine uses the global variable rpc_
createerr. rpc_createerr is a structure that contains the most
recent service creation error. Use rpc_createerr if you want the
client program to handle the error. The value of rpc_createerr is
set by any RPC client creation routine that does not succeed. The
rpc_createerr variable is defined in the CLNT.H file.
The socket referenced by sockp is copied into a private area for
RPC to use. It is the client's responsibility to close the socket
referenced by sockp.
The authentication scheme for the client, client->cl_auth, gets
set to null authentication. The calling program can set this to
something different if necessary.
NOTE
If addr->sin_port is 0 and the requested program is
available on the host but the program does not support the
requested version number, this routine still succeeds. A
subsequent call to the clnt_call routine will discover the
version mismatch. Use the clnt_create_vers routine if you
want to avoid this condition.
1.22.3 – Return Values
CLIENT * A pointer to the client handle.
NULL Indicates failure.
1.23 – clntudp_create
Creates an ONC RPC client handle for a nonbuffered I/O UDP
connection.
Format
#include <rpc/rpc.h>
CLIENT *clntudp_create(struct sockaddr_in *addr, u_long
prognum, u_long versnum, struct timeval wait, register
int *sockp);
1.23.1 – Arguments
addr
A pointer to a buffer containing the Internet address where the
remote program is located.
prognum
The program number associated with the remote procedure.
versnum
The version number associated with the remote procedure.
wait
The amount of time used between call retransmission if no
response is received. Retransmission occurs until the ONC RPC
calls time out.
sockp
A pointer to the socket number to be used for the remote
procedure call. If sockp is RPC_ANYSOCK, then this routine opens
a new socket and sets sockp.
1.23.2 – Description
Creates an ONC RPC client handle for the remote program prognum,
version versnum at address addr. The client uses UDP as the
transport. The routine is similar to the clnt_create routine,
except clntudp_create allows you to specify a socket and the UDP
retransmission time.
If you specify the port number as zero by using addr->sin_port,
the Portmapper provides the number of the port on which the
remote program is listening.
The clntudp_create routine uses the global variable rpc_
createerr. rpc_createerr is a structure that contains the most
recent service creation error. Use rpc_createerr if you want the
client program to handle the error. The value of rpc_createerr is
set by any RPC client creation routine that does not succeed. The
rpc_createerr variable is defined in the CLNT.H file.
The socket referenced by sockp is copied into a private area for
RPC to use. It is the client's responsibility to close the socket
referenced by sockp.
The authentication scheme for the client, client->cl_auth, gets
set to null authentication. The calling program can set this to
something different if necessary.
NOTES
Since UDP/IP messages can only hold up to 8 KB of encoded
data, this transport cannot be used for procedures that take
large arguments or return huge results.
If addr->sin_port is 0 and the requested program is
available on the host but the program does not support the
requested version number, this routine still succeeds. A
subsequent call to the clnt_call routine will discover the
version mismatch. Use the clnt_create_vers routine if you
want to avoid this condition.
1.23.3 – Return Values
CLIENT * A pointer to the client handle.
NULL Indicates failure.
1.24 – get_myaddress
Returns the local host's Internet address.
Format
#include <rpc/rpc.h>
void get_myaddress(struct sockaddr_in *addr);
1.24.1 – Arguments
addr
A pointer to a sockaddr_in structure that the routine will load
with the Internet address of the host where the local procedure
resides.
1.24.2 – Description
Puts the local host's Internet address into addr without doing
any name translation. The port number is always set to htons
(PMAPPORT).
1.24.3 – Return Values
None
1.25 – get_myaddr_dest
Returns the local host's Internet address according to a
destination address.
Format
#include <rpc/rpc.h>
void get_myaddr_dest(struct sockaddr_in *addr, struct
sockaddr_in *dest);
1.25.1 – Arguments
addr
A pointer to a sockaddr_in structure that the routine will load
with the local Internet address that would provide a connection
to the remote address specified in dest.
dest
A pointer to a sockaddr_in structure containing an Internet
address of a remote host.
1.25.2 – Description
Since the local host may have multiple network addresses (each
on its own interface), this routine is used to select the local
address that would provide a connection to the remote address
specified in dest.
This is an alternative to gethostbyname, which invokes yellow
pages. It takes a destination (where we are trying to get to) and
finds an exact network match to go to.
1.25.3 – Return Values
None
2 – RPC Portmapper Routines
Portmapper routines allow C programs to access the Portmapper
network service.
Important: In order to maintain uniqueness for the OpenVMS HELP
utility, some XDR routines have a "_#" appended at the end. Do
not use the "_#" when coding the routine in a program.
2.1 – pmap_getmaps_#
Returns a copy of the current port mappings on a remote host.
Format
#include <rpc/pmap_clnt.h>
struct pmaplist *pmap_getmaps(struct sockaddr_in *addr);
2.1.1 – Arguments
addr
A pointer to a sockaddr_in structure containing the Internet
address of the host whose Portmapper you want to call.
2.1.2 – Description
A client interface to the Portmapper, which returns a list of the
current ONC RPC program-to-port mappings on the host located at
the Internet address addr. The SHOW PORTMAPPER management command
uses this routine.
2.1.3 – Return Values
struct pmaplist * A pointer to the returned list of server-to-
port mappings on host addr.
NULL Indicates failure.
2.2 – pmap_getmaps_vms
Returns a copy of the current port mappings on a remote host
running TCP/IP Services software.
Format
#include <rpc/pmap_clnt.h>
struct pmaplist_vms *pmap_getmaps_vms(struct sockaddr_in
*addr);
2.2.1 – Arguments
addr
A pointer to a sockaddr_in structure containing the Internet
address of the host whose Portmapper you wish to call.
2.2.2 – Description
This routine is similar to the pmap_getmaps routine. However,
pmap_getmaps_vms also returns the process identifiers (PIDs) that
are required for mapping requests to TCP/IP Services hosts.
2.2.3 – Return Values
struct pmaplist * A pointer to the returned list of server-to-
port mappings on host addr.
NULL Indicates failure.
2.3 – pmap_getport
Returns the port number on which the specified service is
waiting.
Format
#include <rpc/pmap_clnt.h>
u_short pmap_getport(struct sockaddr_in *addr, u_long prognum,
u_long versnum, u_long protocol );
2.3.1 – Arguments
addr
A pointer to a sockaddr_in structure containing the Internet
address of the host where the remote Portmapper resides.
prognum
The program number associated with the remote procedure.
versnum
The version number associated with the remote procedure.
protocol
The transport protocol that the remote procedure uses. Specify
either IPPROTO_UDP or IPPROTO_TCP.
2.3.2 – Description
A client interface to the Portmapper. This routine returns the
port number on which waits a server that supports program number
prognum, version versnum, and speaks the transport protocol
associated with protocol (IPPROTO_UDP or IPPROTO_TCP).
NOTES
If the requested version is not available, but at least the
requested program is registered, the routine returns a port
number.
The pmap_getport routine returns the port number in host
byte order not network byte order. For certain routines you
may need to convert this value to network byte order using
the htons routine. For example, the sockaddr_in structure
requires that the port number be in network byte order.
2.3.3 – Return Values
x The port number of the service on the remote
system.
0 No mapping exists or RPC could not contact the
remote Portmapper service. In the latter case,
the global variable rpc_createerr.cf_error
contains the ONC RPC status.
2.4 – pmap_rmtcall
The client interface to the Portmapper service for a remote call
and broadcast service. This routine allows a program to do a
lookup and call in one step.
Format
#include <rpc/pmap_clnt.h>
enum clnt_stat pmap_rmtcall(struct sockaddr_in *addr, u_long
prognum, u_long versnum, u_long procnum,
xdrproc_t inproc, char * in xdrproc_t outproc,
char * out, struct timeval timeout, u_long
*port );
2.4.1 – Arguments
addr
A pointer to a sockaddr_in structure containing the Internet
address of the host where the remote Portmapper resides.
prognum
The program number associated with the remote procedure.
versnum
The version number associated with the remote procedure.
procnum
The procedure number associated with the remote procedure.
inproc
The XDR routine used to encode the remote procedure's arguments.
in
A pointer to the remote procedure's arguments.
outproc
The XDR routine used to decode the remote procedure's results.
out
A pointer to the remote procedure's results.
timeout
A timeval structure describing the time allowed for the results
to return to the client.
port
A pointer to a location for the returned port number. Modified
to the remote program's port number if the pmap_rmtcall routine
succeeds.
2.4.2 – Description
A client interface to the Portmapper, which instructs the
Portmapper on the host at the Internet address *addr to make
a call on your behalf to a procedure on that host. Use this
procedure for a ping operation and nothing else. You can use
the clnt_perrno routine to print any error message.
NOTE
If the requested procedure is not registered with the remote
Portmapper, the remote Portmapper does not reply to the
request. The call to pmap_rmtcall will eventually time out.
The pmap_rmtcall does not perform authentication.
2.4.3 – Return Values
enum clnt_stat Returns the buffer containing the status of
the operation.
2.5 – pmap_set
Called by the server procedure to have the Portmapper create a
mapping of the procedure's program and version number.
Format
#include <rpc/pmap_clnt.h>
bool_t pmap_set(u_long prognum, u_long versnum, u_long
protocol, u_short port);
2.5.1 – Arguments
prognum
The program number associated with the server procedure.
versnum
The version number associated with the server procedure.
protocol
The transport protocol that the server procedure uses. Specify
either IPPROTO_UDP or IPPROTO_TCP.
port
The port number associated with the server program.
2.5.2 – Description
A server interface to the Portmapper, which establishes a mapping
between the triple [prognum,versnum,protocol] and port on the
server's Portmapper service. The svc_register routine calls this
routine to register the server with the local Portmapper.
2.5.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
2.6 – pmap_unset
Called by the server procedure to have the Portmapper delete a
mapping of the procedure's program and version number.
Format
#include <rpc/pmap_clnt.h>
bool_t pmap_unset(u_long prognum, u_long versnum);
2.6.1 – Arguments
prognum
The program number associated with the server procedure.
versnum
The version number associated with the server procedure.
2.6.2 – Description
A server interface to the Portmapper, which destroys all mapping
between the triple [prognum, versnum, *] and ports on the local
host's Portmapper.
2.6.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
3 – RPC Server Routines
Server routines allow C programs to receive procedure calls from
client programs over the network.
3.1 – registerrpc
Obtains a unique systemwide procedure identification number.
Format
#include <rpc/rpc.h>
int registerrpc(u_long prognum, u_long versnum, u_long
procnum, char *(*progname)(), xdrproc_t inproc, xdrproc_t
outproc );
3.1.1 – Arguments
prognum
The program number associated with the service procedure.
versnum
The version number associated with the service procedure.
procnum
The procedure number associated with the service procedure.
progname
The address of the service procedure being registered with the
ONC RPC service package.
inproc
The XDR routine used to decode the service procedure's arguments.
outproc
The XDR routine used to encode the service procedure's results.
3.1.2 – Description
The registerrpc routine performs the following tasks for a
server:
o Creates a UDP server handle. See the svcudp_create routine for
restrictions.
o Calls the svc_register routine to register the program with
the Portmapper.
o Adds prognum, versnum, and procnum to an internal list of
registered procedures. When the server receives a request, it
uses this list to determine which routine to call.
A server should call registerrpc for every procedure it
implements, except for the NULL procedure. If a request arrives
for program prognum, version versnum, and procedure procnum,
progname is called with a pointer to its parameters.
3.1.3 – Return Values
0 Indicates success.
-1 Indicates failure.
3.2 – seterr_reply
Fills in the error text in a reply message.
Format
#include <rpc/rpc.h>
void seterr_reply(struct rpc_msg *msg, struct rpc_err *error);
3.2.1 – Arguments
msg
A pointer to a reply message buffer.
error
A pointer to an rpc_err structure containing the error associated
with the reply message.
3.2.2 – Description
Given a reply message, seterr_reply fills in the error field.
3.2.3 – Return Values
None
3.3 – svc_destroy
A macro that frees the memory associated with an RPC server
handle.
Format
#include <rpc/rpc.h>
void svc_destroy(SVCXPRT *xprt);
3.3.1 – Arguments
xprt
A pointer to an RPC server handle created by any of the server-
handle creation routines.
3.3.2 – Description
The svc_destroy routine returns all the private data structures
associated with a server handle. If the server-handle creation
routine received the value RPC_ANYSOCK as the socket, svc_destroy
closes the socket. Otherwise, your program must close the socket.
3.3.3 – Return Values
None
3.4 – svc_freeargs
A macro that frees the memory allocated when the procedure's
arguments were decoded.
Format
#include <rpc/rpc.h>
bool_t svc_freeargs(SVCXPRT *xprt, xdrproc_t inproc, char
*in);
3.4.1 – Arguments
xprt
A pointer to an RPC server handle created by any of the server-
handle creation routines.
inproc
The XDR routine used to decode the service procedure's arguments.
in
A pointer to the service procedure's decoded arguments.
3.4.2 – Description
The svc_destroy routine returns the memory that the svc_getargs
routine allocated to hold the service procedure's decoded
arguments. This routine calls the xdr_free routine.
3.4.3 – Return Values
TRUE Success; memory successfully deallocated.
FALSE Failure; memory not deallocated.
3.5 – svc_getargs
A macro that decodes the service procedure's arguments.
Format
#include <rpc/rpc.h>
bool_t svc_getargs(SVCXPRT *xprt, xdrproc_t inproc, char *in);
3.5.1 – Arguments
xprt
A pointer to an RPC server handle created by any of the server-
handle creation routines.
inproc
The XDR routine used to decode the service procedure's arguments.
in
A pointer to the service procedure's decoded arguments.
3.5.2 – Description
This routine calls the specified XDR routine to decode the
arguments passed to the service procedure.
3.5.3 – Return Values
TRUE Successfully decoded.
FALSE Decoding unsuccessful.
3.6 – svc_getcaller
A macro that returns the address of the client that called the
service procedure.
Format
#include <rpc/rpc.h>
struct sockaddr_in *svc_getcaller(SVCXPRT *xprt);
3.6.1 – Arguments
xprt
A pointer to an RPC server handle created by any of the server-
handle creation routines.
3.6.2 – Description
This routine returns a sockaddr_in structure containing the
Internet address of the RPC client routine that called the
service procedure.
3.6.3 – Return Values
struct sockaddr_ A pointer to the socket descriptor.
in
3.7 – svc_getreqset
Returns data for each server connection.
Format
#include <rpc/rpc.h>
void svc_getreqset(fd_set *rdfds);
3.7.1 – Arguments
rdfds
A pointer to the read file descriptor bit mask modified by the
select routine.
3.7.2 – Description
The svc_getreqset routine is for servers that implement custom
asynchronous event processing or that do not use the svc_run
routine. You can only use svc_fdset when the server does not use
svc_run.
You are unlikely to call this routine directly, because the
svc_run routine calls it. However, there are times when you
cannot call svc_run. For example, suppose a program services
RPC requests and reads or writes to another socket at the same
time. The program cannot call svc_run. It must call select and
svc_getreqset.
The server calls svc_getreqset when a call to the select system
call determines that the server has received one or more RPC
requests. The svc_getreqset routine reads in data for each server
connection, then calls the server program to handle the data.
The svc_getreqset routine does not return a value. It finishes
executing after all sockets associated with the variable rdfds
have been serviced.
You can use the global variable svc_fdset with svc_getreqset. The
svc_fdset variable is the RPC server's read file descriptor bit
mask.
To use svc_fdset:
1. Copy the global variable svc_fdset into a temporary variable.
2. Pass the temporary variable to the select routine. The select
routine overwrites the variable and returns it.
3. Pass the temporary variable to the svc_getreqset routine.
3.7.3 – Example
#define MAXSOCK 10
int readfds[ MAXSOCK+1], /* sockets to select from*/
i, j;
for(i = 0, j = 0; i << MAXSOCK; i++)
if((svc_fdset[i].sockname != 0) && (svc_
fdset[i].sockname != -1))
readfds[j++] = svc_fdset[i].sockname;
readfds[j] = 0; /* list of sockets ends with a zero */
switch(select(0, readfds, 0, 0, 0))
{
case -1: /* an error happened */
case 0: /* time out */
break;
default: /* 1 or more sockets ready for reading */
errno = 0;
svc_getreqset(readfds);
if( errno == ENETDOWN || errno == ENOTCONN)
sys$exit( SS$_THIRDPARTY);
}
3.7.4 – Return Values
None
3.8 – svc_register
Registers the server program with the Portmapper service.
Format
#include <rpc/rpc.h>
bool_t svc_register(SVCXPRT *xprt, u_long prognum, u_long
versnum, void (*dispatch)(), u_long protocol);
3.8.1 – Arguments
xprt
A pointer to an RPC server handle created by any of the server-
handle creation routines.
prognum
The program number associated with the server procedure.
versnum
The version number associated with the server procedure.
dispatch
The address of the service dispatch procedure that the server
procedure calls. The procedure dispatch has the following form:
void dispatch(request, xprt)
struct svc_req *request;
SVCXPRT *xprt;
The svc_run and svc_getreqset call the dispatch routine.
protocol
The protocol that the server procedure uses. Values for this
parameter are zero, IPPROTO_UDP, or IPPROTO_TCP. If protocol is
zero, the service is not registered with the Portmapper service.
3.8.2 – Description
Associates prognum and versnum with the service dispatch
procedure dispatch. If protocol is nonzero, then a mapping of
the triple [prognum, versnum, protocol] to xprt->xp_port is also
established with the local Portmapper service.
3.8.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
3.9 – svc_run
Waits for incoming RPC requests and calls the svc_getreqset
routine to dispatch to the appropriate RPC server program.
Format
#include <rpc/rpc.h>
void svc_run();
3.9.1 – Arguments
None
3.9.2 – Description
The svc_run routine calls the select routine to wait for RPC
requests. When a request arrives, svc_run calls the svc_getreqset
routine. Then svc_run calls the select routine again.
The svc_run routine never returns.
You may use the global variable svc_fdset with the svc_run
routine. See the svc_getreqset routine for more information about
svc_fdset.
3.9.3 – Return Values
Never returns
3.10 – svc_sendreply
Sends the results of a remote procedure call to an RPC client.
Format
#include <rpc/rpc.h>
bool_t svc_sendreply(SVCXPRT *xprt, xdrproc_t outproc, char
*out);
3.10.1 – Arguments
xprt
A pointer to an RPC server handle created by any of the server-
handle creation routines.
outproc
The XDR routine used to encode the server procedure's results.
out
A pointer to the server procedure's results.
3.10.2 – Description
Called by an ONC RPC service's dispatch routine to send the
results of a remote procedure call.
3.10.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
3.11 – svc_unregister
Calls the Portmapper to unregister the specified program and
version for all protocols. The program and version are removed
from the list of active servers.
Format
#include <rpc/rpc.h>
void svc_unregister(u_long prognum, u_long versnum);
3.11.1 – Arguments
prognum
The program number associated with the server procedure.
versnum
The version number associated with the server procedure.
3.11.2 – Description
Removes all mapping of the double [prognum, versnum] to dispatch
routines, and of the triple [prognum, versnum, *] to port number.
3.11.3 – Return Values
None
3.12 – svcerr_auth
Sends an authentication error to the client.
Format
#include <rpc/rpc.h>
void svcerr_auth(SVCXPRT *xprt, enum auth_stat why);
3.12.1 – Arguments
xprt
A pointer to an RPC server handle created by any of the server-
handle creation routines.
why
The reason for the authentication error.
3.12.2 – Description
Called by a service dispatch routine that refuses to perform a
remote procedure call because of an authentication error.
3.12.3 – Return Values
None
3.13 – svcerr_decode
Sends an error code to the client indicating that the server
procedure cannot decode the client's arguments.
Format
#include <rpc/rpc.h>
void svcerr_decode(SVCXPRT *xprt);
3.13.1 – Arguments
xprt
A pointer to an RPC server handle created by any of the server-
handle creation routines.
3.13.2 – Description
Called by a service dispatch routine that cannot successfully
decode its parameters. See also the svc_getargs routine.
3.13.3 – Return Values
None
3.14 – svcerr_noproc
Sends an error code to the client indicating that the server
program does not implement the requested procedure.
Format
#include <rpc/rpc.h>
void svcerr_noproc(SVCXPRT *xprt);
3.14.1 – Arguments
xprt
A pointer to an RPC server handle created by any of the server-
handle creation routines.
3.14.2 – Description
Called by a service dispatch routine that does not implement the
procedure number that the client requested.
3.14.3 – Return Values
None
3.15 – svcerr_noprog
Sends an error code to the client indicating that the server
program is not registered with the Portmapper.
Format
#include <rpc/rpc.h>
void svcerr_noprog(SVCXPRT *xprt);
3.15.1 – Arguments
xprt
A pointer to an RPC server handle created by any of the server-
handle creation routines.
3.15.2 – Description
Called when the desired program is not registered with the ONC
RPC package. Generally, the Portmapper informs the client when a
server is not registered. Therefore, service implementors usually
do not use this routine.
3.15.3 – Return Values
None
3.16 – svcerr_progvers
Sends an error code to the client indicating that the requested
program is registered with the Portmapper but the requested
version of the program is not registered.
Format
#include <rpc/rpc.h>
void svcerr_progvers(SVCXPRT *xprt, u_long low_vers, u_long
high_vers);
3.16.1 – Arguments
xprt
A pointer to an RPC server handle created by any of the server-
handle creation routines.
low_vers
The lowest version of the requested program that the server
supports.
high_vers
The highest version of the requested program that the server
supports.
3.16.2 – Description
Called when the desired version of a program is not registered
with the ONC RPC package. Generally, the Portmapper informs
the client when a requested program version is not registered.
Therefore, service implementors usually do not use this routine.
3.16.3 – Return Values
None
3.17 – svcerr_systemerr
Sends an error code to the client indicating that an error
occurred that is not handled by the protocol being used.
Format
#include <rpc/rpc.h>
void svcerr_systemerr(SVCXPRT *xprt);
3.17.1 – Arguments
xprt
A pointer to an RPC server handle created by any of the server-
handle creation routines.
3.17.2 – Description
Called by a service dispatch routine when it detects a system
error not covered by any particular protocol. For example, if a
service can no longer allocate storage, it may call this routine.
3.17.3 – Return Values
None
3.18 – svcerr_weakauth
Sends an error code to the client indicating that an
authentication error occurred. The authentication information
was correct but was insufficient.
Format
#include <rpc/rpc.h>
void svcerr_weakauth(SVCXPRT *xprt);
3.18.1 – Arguments
xprt
A pointer to an RPC server handle created by any of the server-
handle creation routines.
3.18.2 – Description
Called by a service dispatch routine that refuses to perform
a remote procedure call because of insufficient (but correct)
authentication parameters. The routine calls svcerr_auth (xprt,
AUTH_TOOWEAK).
3.18.3 – Return Values
None
3.19 – svcraw_create
Creates a server handle for memory-based ONC RPC for simple
testing and timing.
Format
#include <rpc/rpc.h>
SVCXPRT *svcraw_create();
3.19.1 – Arguments
None
3.19.2 – Description
Creates a in-program ONC RPC service transport, to which it
returns a pointer. The transport is really a buffer within the
process's address space, so the corresponding client should live
in the same address space; see the clntraw_create routine. The
svcraw_create and clntraw_create routines allow simulation and
acquisition of ONC RPC overheads (such as round-trip times),
without any kernel interference.
3.19.3 – Return Values
SVCXPRT * A pointer to an RPC server handle for the
in-memory transport.
NULL Indicates failure.
3.20 – svcfd_create
Creates an RPC server handle using the specified open file
descriptor.
Format
#include <rpc/rpc.h>
SVCXPRT *svcfd_create(int fd, u_int sendsize, u_int recvsize);
3.20.1 – Arguments
fd
The number of an open file descriptor.
sendsize
The size of the send buffer. If you specify zero, the routine
chooses a suitable default.
recvsize
The size of the receive buffer. If you specify zero, the routine
chooses a suitable default.
3.20.2 – Description
Creates an RPC server handle using the specified TCP socket, to
which it returns a pointer. The server should call the svcfd_
create routine after it accepts an incoming TCP connection.
3.20.3 – Return Values
SVCXPRT * A pointer to the server handle.
NULL Indicates failure.
3.21 – svctcp_create
Creates an ONC RPC server handle for a TCP/IP connection.
Format
#include <rpc/rpc.h>
SVCXPRT *svctcp_create(int sock, u_int sendsize, u_int
recvsize);
3.21.1 – Arguments
sock
The socket with which the connection is associated. If sock is
RPC_ANYSOCK, then this routine opens a new socket and sets sock.
If the socket is not bound to a local TCP port, then this routine
binds it to an arbitrary port.
sendsize
The size of the send buffer. If you specify zero, the routine
chooses a suitable default.
recvsize
The size of the receive buffer. If you specify zero, the routine
chooses a suitable default.
3.21.2 – Description
Creates an RPC server handle using the TCP/IP transport, to
which it returns a pointer. Upon completion, xprt->xp_sock is
the transport's socket descriptor, and xprt->xp_port is the
transport's port number. The service is automatically registered
as a transporter (thereby including its socket in svc_fds such
that its socket descriptor is included in all RPC select system
calls).
3.21.3 – Return Values
SVCXPRT * A pointer to the server handle.
NULL Indicates failure.
3.22 – svcudp_bufcreate
Creates an ONC RPC server handle for a buffered I/O UDP
connection.
Format
#include <rpc/rpc.h>
SVCXPRT *svcudp_bufcreate(int sock, u_int sendsize, u_int
recvsize);
3.22.1 – Arguments
sock
The socket with which the connection is associated. If sock is
RPC_ANYSOCK, then this routine opens a new socket and sets sock.
sendsize
The size of the send buffer. If you specify zero, the routine
chooses a suitable default.
recvsize
The size of the receive buffer. If you specify zero, the routine
chooses a suitable default.
3.22.2 – Description
Creates an RPC server handle using the UDP transport, to
which it returns a pointer. Upon completion, xprt->xp_sock is
the transport's socket descriptor, and xprt->xp_port is the
transport's port number. The service is automatically registered
as a transporter (thereby including its socket in svc_fds such
that its socket descriptor is included in all RPC select system
calls).
3.22.3 – Return Values
SVCXPRT * A pointer to the server handle.
NULL Indicates failure.
3.23 – svcudp_create
Creates an ONC RPC server handle for a nonbuffered I/O UDP
connection.
Format
#include <rpc/rpc.h>
SVCXPRT *svcudp_create(int sock);
3.23.1 – Arguments
sock
The socket with which the connection is associated. If sock is
RPC_ANYSOCK, then this routine opens a new socket and sets sock.
3.23.2 – Description
Creates an RPC server handle using the UDP transport, to
which it returns a pointer. Upon completion, xprt->xp_sock is
the transport's socket descriptor, and xprt->xp_port is the
transport's port number. The service is automatically registered
as a transporter (thereby including its socket in svc_fds such
that its socket descriptor is included in all RPC select system
calls).
NOTE
Since UDP/IP-based ONC RPC messages can only hold up to
8 KB of encoded data, this transport cannot be used for
procedures that take large arguments or return huge results.
3.23.3 – Return Values
SVCXPRT * A pointer to the server handle.
NULL Indicates failure.
3.24 – xprt_register
Adds a socket associated with an RPC server handle to the list of
registered sockets.
Format
#include <rpc/rpc.h>
void xprt_register(SVCXPRT *xprt);
3.24.1 – Arguments
xprt
A pointer to an RPC server handle created by any of the server-
handle creation routines.
3.24.2 – Description
Activation of a transport handle involves setting the most
appropriate bit for the socket associated with xprt in the svc_
fds mask. When svc_run() is invoked, activity on the transport
handle is eligible to be processed by the server.
The svc_register routine calls this routine; therefore, you are
unlikely to use this routine directly.
3.24.3 – Return Values
None
3.25 – xprt_unregister
Removes a socket associated with an RPC server handle from the
list of registered sockets.
Format
#include <rpc/rpc.h>
void xprt_unregister(SVCXPRT *xprt);
3.25.1 – Arguments
xprt
A pointer to an RPC server handle created by any of the server-
handle creation routines.
3.25.2 – Description
Removes the socket associated with the indicated handle from the
list of registered sockets maintained in the svc_fdset variable.
Activity on the socket associated with xprt will no longer be
checked by the svc_run routine.
The svc_unregister routine calls this routine; therefore, you are
unlikely to use this routine directly.
3.25.3 – Return Values
None
3.26 – _authenticate
Authenticates the request message.
Format
#include <rpc/rpc.h>
enum auth_stat _authenticate(struct svc_req *rqst, struct
rpc_msg *msg);
3.26.1 – Arguments
rqst
A pointer to an svc_req structure with the requested program
number, procedure number, version number, and credentials passed
by the client.
msg
A pointer to an rpc_msg structure with members that make up the
RPC message.
3.26.2 – Description
Returns AUTH_OK if the message is authenticated successfully. If
it returns AUTH_OK, the routine also does the following:
o Sets rqst->rq_xprt->verf to the appropriate response verifier.
o Sets rqst->rq_client_cred to the "cooked" form of the
credentials.
The expression rqst->rq_xprt->verf must be preallocated and its
length must be set appropriately.
The program still owns and is responsible for msg->u.cmb.cred and
msg->u.cmb.verf. The authentication system retains ownership of
rqst->rq_client_cred, the "cooked" credentials.
3.26.3 – Return Values
enum auth_stat The return status code for the authentication
checks:
AUTH_OK=0-Authentication checks successful.
AUTH_BADCRED=1-Invalid credentials (seal
broken)
AUTH_REJECTEDCRED=2-Client should begin new
session
AUTH_BADVERF=3-Invalid verifier (seal
broken)
AUTH_REJECTEDVERF=4-Verifier expired or was
replayed
AUTH_TOOWEAK=5-Rejected for security
reasons
AUTH_INVALIDRESP=6-Invalid response
verifier
AUTH_FAILED=7-Some unknown reason
4 – RPC XDR Routines
XDR routines specify external data representation. They allow C
programmers to describe arbitrary data structures in a system-
independent fashion.
Important: In order to maintain uniqueness for the OpenVMS HELP
utility, some XDR routines have a "_#" appended at the end. Do
not use the "_#" when coding the routine in a program.
4.1 – xdr_accepted_reply
Serializes and deserializes a message-accepted indication in an
RPC reply message.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_accepted_reply(XDR *xdrs, struct accepted_reply
*arp);
4.1.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
arp
A pointer to a buffer to which the message-accepted indication is
written.
4.1.2 – Description
Used for encoding reply messages. This routine encodes the status
of the RPC call and, in the case of success, the call results
as well. This routine is useful for users who want to generate
messages without using the ONC RPC package. It returns the
message-accepted variant of a reply message union in the arp
argument.
The xdr_replymsg routine calls this routine.
4.1.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure to encode the message.
4.2 – xdr_array
Serializes and deserializes the elements of a variable-length
array.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_array(XDR *xdrs, char **arrp, u_int *sizep, u_int
maxsize, u_int elsize, xdrproc_t elproc);
4.2.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
arrp
A pointer to the pointer to the array.
sizep
A pointer to the number of elements in the array. This element
count cannot exceed the maxsize parameter.
maxsize
The maximum size of the sizep parameter. This value is the
maximum number of elements that the array can hold.
elsize
The size, in bytes, of each of the array's elements.
elproc
The XDR routine to call that handles each element of the array.
4.2.2 – Description
A filter primitive that translates between variable-length arrays
and their corresponding external representations.
4.2.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.3 – xdr_authunix_parms
Serializes and deserializes credentials in an authentication
parameter structure.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_authunix_parms (XDR *xdrs, struct authunix_parms
*authp);
4.3.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
authp
A pointer to an authunix_parms structure.
4.3.2 – Description
Used for externally describing standard UNIX credentials. On a
TCP/IP Services host, this routine encodes the host name, the
user ID, and the group ID. It sets the group ID list to NULL.
This routine is useful for users who want to generate these
credentials without using the ONC RPC authentication package.
4.3.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.4 – xdr_bool
Serializes and deserializes boolean data.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_bool (XDR *xdrs, bool_t *bp);
4.4.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
bp
A pointer to the boolean data.
4.4.2 – Description
A filter primitive that translates between booleans (integers)
and their external representations. When encoding data, this
filter produces values of either 1 or 0.
4.4.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.5 – xdr_bytes
Serializes and deserializes a counted byte array.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_bytes (XDR *xdrs, char **bpp, u_int *sizep, u_int
maxsize);
4.5.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
bpp
A pointer to a pointer to the byte array.
sizep
A pointer to the length of the byte array.
maxsize
The maximum size of the length of the byte array.
4.5.2 – Description
A filter primitive that translates between a variable-length byte
array and its external representation. The length of the array
is located at sizep; the array cannot be longer than maxsize. If
*bpp is NULL, xdr_bytes allocates maxsize bytes.
4.5.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.6 – xdr_callhdr
Serializes and deserializes the static part of a call message
header.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_callhdr(XDR *xdrs, struct rpc_msg *chdrp);
4.6.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
chdrp
A pointer to the call header data.
4.6.2 – Description
Describes call header messages. This routine is useful for users
who want to generate messages without using the ONC RPC package.
The xdr_callhdr routine encodes the following fields: transaction
ID, direction, RPC version, server program number, and server
version.
4.6.3 – Return Values
TRUE Indicate success.
FALSE Indicates failure.
4.7 – xdr_callmsg
Serializes and deserializes an ONC RPC call message.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_callmsg(XDR *xdrs, struct rpc_msg *cmsgp);
4.7.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
cmsgp
A pointer to an rpc_msg structure that describes the RPC call
message.
4.7.2 – Description
This routine is useful for users who want to generate messages
without using the ONC RPC package. The xdr_callmsg routine
encodes the following fields: transaction ID, direction, RPC
version, server program number, server version number, server
procedure number, and client authentication.
The pmap_rmtcall and svc_sendreply routines call xdr_callmsg.
4.7.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.8 – xdr_char
Serializes and deserializes character data.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_char(XDR *xdrs, char *cp);
4.8.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
cp
A pointer to a character.
4.8.2 – Description
A filter primitive that translates between internal
representations of characters and their XDR representations.
4.8.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.9 – xdr_double
Serializes and deserializes VAX and IEEE double-precision
floating-point numbers.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_double(XDR *xdrs, double *dp);
4.9.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
dp
A pointer to the double-precision floating-point number.
4.9.2 – Description
A filter primitive that translates between double-precision
numbers and their external representations.
This routine is implemented by four XDR routines:
xdr_ Converts VAX D-format floating-point numbers.
double_D
xdr_ Converts VAX G-format floating-point numbers.
double_G
xdr_ Converts IEEE T-format floating-point numbers.
double_T
xdr_ Converts IEEE X-format floating-point numbers.
double_X
You can reference these routines explicitly or you can use
compiler settings to control which routine is used when you
reference the xdr_double routine.
4.9.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.10 – xdr_enum
Serializes and deserializes enumerations.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_enum(XDR *xdrs, enum_t *ep);
4.10.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
ep
A pointer to the enumeration data.
4.10.2 – Description
A filter primitive that translates between enumerations (actually
integers) and their external representations.
4.10.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.11 – xdr_float
Serializes and deserializes VAX and IEEE single-precision
floating-point numbers.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_float(XDR *xdrs, float *fp);
4.11.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
fp
A pointer to a single-precision floating-point number.
4.11.2 – Description
A filter primitive that translates between single-precision
floating-point numbers and their external representations.
This routine is implemented by two XDR routines:
xdr_ Converts VAX F-format floating-point numbers.
float_F
xdr_ Converts IEEE T-format floating-point numbers.
float_S
You can reference these routines explicitly or you can use
compiler settings to control which routine is used when you
reference the xdr_float routine.
4.11.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.12 – xdr_free
Deallocates the memory associated with the indicated data
structure.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_free(xdrproc_t proc, char *objp);
4.12.1 – Arguments
proc
The XDR routine for the data structure being freed.
objp
A pointer to the data structure to be freed.
4.12.2 – Description
Releases memory allocated for the data structure to which objp
points. The pointer passed to this routine is not freed, but what
it points to is freed (recursively). Use this routine to free
decoded data that is no longer needed. Never use this routine for
encoded data.
4.12.3 – Return Values
TRUE Indicate success.
FALSE Indicates failure.
4.13 – xdr_hyper
Serializes and deserializes VAX quadwords (known in XDR as
hyperintegers).
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_hyper(XDR *xdrs, quad *hp);
4.13.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
hp
A pointer to the hyperinteger data.
4.13.2 – Description
A filter primitive that translates between hyperintegers and
their external representations.
4.13.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.14 – xdr_int
Serializes and deserializes integers.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_int(XDR *xdrs, int *ip);
4.14.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
ip
A pointer to the integer data.
4.14.2 – Description
A filter primitive that translates between integers and their
external representations.
4.14.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.15 – xdr_long
Serializes and deserializes long integers.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_long(XDR *xdrs, long *lp);
4.15.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
lp
A pointer to a long integer.
4.15.2 – Description
A filter primitive that translates between long integers and
their external representations.
4.15.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.16 – xdr_opaque
Serializes and deserializes opaque structures.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_opaque(XDR *xdrs, char *op, u_int cnt);
4.16.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
op
A pointer to the opaque data.
cnt
The size of op in bytes.
4.16.2 – Description
A filter primitive that translates between fixed-size opaque data
and its external representation. This routine treats the data
as a fixed length of bytes and does not attempt to convert the
bytes.
4.16.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.17 – xdr_opaque_auth
Serializes and deserializes ONC RPC authentication information
message.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_opaque_auth(XDR *xdrs, struct opaque_auth *authp);
4.17.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
authp
A pointer to an opaque_auth structure describing authentication
information. The pointer should reference data created by the
authnone_create, authunix_create, or authunix_create_default
routine.
4.17.2 – Description
Translates ONC RPC authentication information messages. This
routine is useful for users who want to generate messages without
using the ONC RPC package.
4.17.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.18 – xdr_pmap_#
Serializes and deserializes Portmapper parameters.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_pmap(XDR *xdrs, struct pmap *regs);
4.18.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
regs
A pointer to the pmap structure. This structure contains the
program number, version number, protocol number, and port number.
4.18.2 – Description
Describes parameters to various Portmapper procedures,
externally. This routine is useful for users who want to generate
these parameters without using the Portmapper interface.
4.18.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.19 – xdr_pmap_vms
Serializes and deserializes OpenVMS specific Portmapper
parameters.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_pmap_vms(XDR *xdrs, struct pmap_vms *regs);
4.19.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
regs
A pointer to the pmap_vms structure. This structure contains the
program number, version number, protocol number, port number and
the OpenVMS specific process identification.
4.19.2 – Description
This routine is similar to xdr_pmap(), except it also includes
the process identification in the pmap_vms structure.
4.19.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.20 – xdr_pmaplist_#
Serializes and deserializes a list of Portmapper port mappings.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_pmaplist(XDR *xdrs, struct pmaplist **rpp);
4.20.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
rpp
A pointer to a pointer to a pmaplist structure containing a
list of Portmapper programs and their respective information.
If the routine is used to decode a Portmapper listing, it sets
rpp to the address of a newly allocated linked list of pmaplist
structures.
4.20.2 – Description
Describes a list of port mappings, externally. This routine is
useful for users who want to generate these parameters without
using the Portmapper interface.
4.20.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.21 – xdr_pmaplist_vms
Serializes and deserializes a list of Portmapper port mappings
for OpenVMS systems.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_pmaplist_vms (XDR *xdrs, struct pmaplist_vms
**rpp);
4.21.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
rpp
A pointer to a pointer to a pmaplist_vms structure containing
a list of Portmapper programs and their respective information,
including OpenVMS-specific information.
4.21.2 – Description
This routine is similar to the xdr_pmaplist routine, except that
it also includes the process identification in the pmaplist_vms
structure.
4.21.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.22 – xdr_pointer
Serializes and deserializes indirect pointers and the data being
pointed to.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_pointer(XDR *xdrs, char **objpp, u_int objsize,
xdrproc_t objproc);
4.22.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
objpp
A pointer to a pointer to the data being converted.
objsize
The size of the data structure in bytes.
objproc
The XDR procedure that filters the structure between its local
form and its external representation.
4.22.2 – Description
An XDR routine for translating data structures that contain
pointers to other structures, such as a linked list. The xdr_
pointer routine is similar to the xdr_reference routine. The
differences are that the xdr_pointer routine handles pointers
with the value NULL and that it translates the pointer values to
a boolean. If the boolean is TRUE, the data follows the boolean.
4.22.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.23 – xdr_reference
Serializes and deserializes indirect pointers and the data being
pointed to.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_reference(XDR *xdrs, char **objpp, u_int objsize,
xdrproc_t objproc);
4.23.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
objpp
A pointer to a pointer to the structure containing the data
being converted. If objpp is zero, the xdr_reference routine
allocates the necessary storage when decoding. This argument must
be nonzero during encoding.
objsize
The size of the structure in bytes.
objproc
The XDR procedure that filters the structure between its local
form and its external representation.
4.23.2 – Description
A primitive that provides pointer chasing within structures.
4.23.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.24 – xdr_rejected_reply
Serializes and deserializes the remainder of an RPC reply message
after the header indicates that the reply is rejected.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_rejected_reply(XDR *xdrs, struct rejected_reply
*rrp);
4.24.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
rrp
A pointer to the rejected_reply structure describing the rejected
reply message.
4.24.2 – Description
Describes ONC RPC reply messages. This routine is useful for
users who want to generate messages without using the ONC RPC
package.
4.24.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.25 – xdr_replymsg
Serializes and deserializes the RPC reply header and then calls
the appropriate routine to interpret the rest of the message.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_replymsg(XDR *xdrs, struct rpc_msg *rmsgp);
4.25.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
rmsgp
A pointer to the rpc_msg structure describing the reply message.
4.25.2 – Description
Describes ONC RPC reply messages. This routine is useful for
users who want to generate messages without using the ONC RPC
package. This routine interprets the message header and then
calls either the xdr_accepted_reply or the xdr_rejected_reply
routine to interpret the body of the RPC message.
4.25.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.26 – xdr_short
Serializes and deserializes short integers.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_short(XDR *xdrs, short *sp);
4.26.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
sp
A pointer to a short integer.
4.26.2 – Description
A filter primitive that translates between short integers and
their external representations.
4.26.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.27 – xdr_string
Serializes and deserializes strings (arrays of bytes terminated
by a NULL character).
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_string(XDR *xdrs, char **spp, u_int maxsize);
4.27.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
spp
A pointer to a pointer to a character string.
maxsize
The maximum size of the string.
4.27.2 – Description
A filter primitive that translates between strings and their
corresponding external representations. Strings cannot be longer
than the value specified with the maxsize parameter.
While decoding, if *spp is NULL, this routine allocates the
necessary storage to hold the NULL-terminated string and sets
*spp to point to the allocated storage.
This routine is the same as the xdr_wrapstring routine, except
that this routine allows you to specify maxsize.
4.27.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.28 – xdr_u_char
Serializes and deserializes unsigned characters.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_u_char(XDR *xdrs, char *ucp);
4.28.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
ucp
A pointer to a character.
4.28.2 – Description
A filter primitive that translates between internal
representation of unsigned characters and their XDR
representations.
4.28.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.29 – xdr_u_hyper
Serializes and deserializes unsigned VAX quadwords (known in XDR
as hyperintegers).
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_u_hyper(XDR *xdrs, unsigned quad *uhp);
4.29.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
uhp
A pointer to the unsigned hyperinteger.
4.29.2 – Description
A filter primitive that translates between unsigned hyperintegers
and their external representations.
4.29.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.30 – xdr_u_int
Serializes and deserializes unsigned integers.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_u_int(XDR *xdrs, unsigned *uip);
4.30.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
uip
A pointer to the unsigned integer.
4.30.2 – Description
A filter primitive that translates between unsigned integers and
their external representations.
4.30.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.31 – xdr_u_long
Serializes and deserializes unsigned long integers.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_u_long(XDR *xdrs, unsigned long *ulp);
4.31.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
ulp
A pointer to the unsigned long integer.
4.31.2 – Description
A filter primitive that translates between unsigned long integers
and their external representations.
4.31.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.32 – xdr_u_short
Serializes and deserializes unsigned short integers.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_u_short(XDR *xdrs, unsigned short *usp);
4.32.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
usp
A pointer to the unsigned short integer.
4.32.2 – Description
A filter primitive that translates between unsigned short
integers and their external representations.
4.32.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.33 – xdr_union
Serializes and deserializes discriminant unions.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_union(XDR *xdrs, enum *dscmp, char *unp, struct
xdr_discrim *choices, xdrproc_t default);
4.33.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
dscmp
A pointer to the union's discriminant.
unp
A pointer to the union's data.
choices
A pointer to an array of xdr_discrim structures. Each structure
contains an ordered pair of [value,proc]. The final structure in
the array is denoted by a pointer with the value NULL.
default
The address of the default XDR routine to call if the dscmp
argument is not found in the choices array.
4.33.2 – Description
A filter primitive that translates between a discriminated union
and its corresponding external representation. The xdr_union
routine first translates the discriminant of the union located at
dscmp. This discriminant is always of type enum_t.
Next, the routine translates the union data located at unp. To
translate the union data the xdr_union routine first searches
the structure pointed to by the choices argument for the union
discriminant passed in the dscmp argument. If a match is found,
the xdr_union routine calls proc to translate the union data.
The end of the xdr_discrim structure array must contain an entry
with the value NULL for proc. If the xdr_union routine reaches
this entry before finding a match, the routine calls the default
procedure (if it is not NULL).
4.33.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.34 – xdr_vector
Serializes and deserializes the elements of a fixed-length array
(known as a vector).
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_vector(XDR *xdrs, char **vecpp, u_int elnum, u_int
elsize, xdrproc_t elproc);
4.34.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
vecpp
A pointer to a pointer to the array.
elnum
The number of elements in the array.
elsize
The size, in bytes, of each element.
elproc
The XDR routine to handle each element.
4.34.2 – Description
A routine that calls elproc to prepare the elements of an array
for XDR messages.
4.34.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.35 – xdr_void
When there is no data to convert, this routine is passed to ONC
RPC routines that require an XDR procedure parameter.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_void();
4.35.1 – Description
This routine is used as a placeholder for a program that passes
no data in a remote procedure call. Most client and server
routines expect an XDR routine to be called, even when there
is no data to pass.
4.35.2 – Return Values
This routine always returns TRUE.
4.36 – xdr_wrapstring
Serializes and deserializes NULL-terminated strings.
Format
#include <tcpip$rpcxdr.h>
bool_t xdr_wrapstring(XDR *xdrs, char **spp);
4.36.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
spp
A pointer to a pointer to a string.
4.36.2 – Description
A primitive that calls xdr_string(xdrs, sp, MAXUNSIGNED), where
MAXUNSIGNED is the maximum value of an unsigned integer. This
routine is useful because the ONC RPC client and server routines
pass the XDR stream handle and a single pointer as parameters
to any referenced XDR routines. The xdr_string routine, one
of the most frequently used ONC RPC primitives, requires three
parameters.
While decoding, if *sp is NULL, the necessary storage is
allocated to hold the NULL-terminated string and *sp is set to
point to it.
4.36.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.37 – xdrmem_create
Initializes an XDR stream descriptor for a memory buffer.
Format
#include <tcpip$rpcxdr.h>
void xdrmem_create(XDR *xdrs, char *addr, u_int size, enum
xdr_op op);
4.37.1 – Arguments
xdrs
A pointer to the XDR stream handle being created. The routine
xdrmem_create fills in xdrs with encoding and decoding
information.
addr
A pointer to the memory buffer.
size
The length of the memory buffer.
op
An XDR operation, one of: XDR_ENCODE, XDR_DECODE, and XDR_FREE.
4.37.2 – Description
The stream handle xdrs is initialized with the operation op, the
buffer addr and size, and the operations context for an xdrmem
stream.
4.37.3 – Return Values
None
4.38 – xdrrec_create
Initializes a record-oriented XDR stream descriptor.
Format
#include <tcpip$rpcxdr.h>
void xdrrec_create(XDR *xdrs, u_int sendsize, u_int recvsize,
char *tcp_handle, int (*readit)(), int (*writeit)());
4.38.1 – Arguments
xdrs
A pointer to the XDR stream handle being created. The routine
xdrrec_create fills in xdrs with encoding and decoding
information.
sendsize
The send buffer size.
recvsize
The receive buffer size.
tcp_handle
A pointer to an opaque handle that is passed as the first
parameter to the procedures (*readit)() and (*writeit)().
(*readit)()
Read procedure that takes the opaque handle tcp_handle. The
routine must use the following format:
int readit(char *tcp_handle, char *buffer, u_long len)
where tcp_handle is the client or server handle, buffer is the
buffer to fill, and len is the number of bytes to read. The
readit routine should return either the number of bytes read
or the value -1 if an error occurs.
(*writeit)()
Write procedure that takes the opaque handle tcp_handle. The
routine must use the following format:
int writeit(char *tcp_handle, char *buffer, u_long len)
where tcp_handle is the client or server handle, buffer is the
buffer to write, and len is the number of bytes to write. The
readit routine should return either the number of bytes written
or the value -1 if an error occurs.
4.38.2 – Description
The stream descriptor for xdrs initializes the maximum allowable
size for a request recvsize and reply sendsize, the addresses of
the routine to perform the read (readit) and write (writeit), and
the TCP handle used for network I/O.
4.38.3 – Return Values
None
4.39 – xdrrec_endofrecord
Generates an end-of-record for an XDR record.
Format
#include <tcpip$rpcxdr.h>
bool_t xdrrec_endofrecord (XDR *xdrs, bool_t sendnow);
4.39.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
sendnow
Indicates whether the record should be sent. If sendnow is TRUE,
xdrrec_endofrecord sends the record by calling the writeit
routine specified in the call to xdrrec_create. If sendnow is
FALSE, xdrrec_endofrecord marks the end of the record and calls
writeit when the buffer is full.
4.39.2 – Description
This routine lets an application support batch calls and
pipelined procedure calls.
4.39.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.40 – xdrrec_eof
Moves the buffer pointer to the end of the current record and
returns an indication if any more data exists in the buffer.
Format
#include <tcpip$rpcxdr.h>
bool_t xdrrec_eof (XDR *xdrs);
4.40.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
4.40.2 – Description
Returns TRUE if there is no more input in the buffer after
consuming the rest of the current record.
4.40.3 – Return Values
TRUE Indicates no more input in the buffer.
FALSE Indicates more input in the buffer.
4.41 – xdrrec_skiprecord
Guarantees proper record alignment during deserialization from an
incoming stream.
Format
#include <tcpip$rpcxdr.h>
bool_t xdrrec_skiprecord (XDR *xdrs);
4.41.1 – Arguments
xdrs
A pointer to an XDR stream handle created by one of the XDR
stream-handle creation routines.
4.41.2 – Description
This routine ensures that the stream is properly aligned in
preparation for a subsequent read. It is recommended that, when a
record stream is being used, this routine be called prior to any
operations that would read from the stream.
This routine is similar to the xdrrec_eof routine, except that
this routine does not verify whether there is more data in the
buffer.
4.41.3 – Return Values
TRUE Indicates success.
FALSE Indicates failure.
4.42 – xdrstdio_create
Initializes an stdio XDR stream.
Format
#include <tcpip$rpcxdr.h>
void xdrstdio_create (XDR *xdrs, FILE *file, enum xdr_op op);
4.42.1 – Arguments
xdrs
A pointer to the XDR stream handle being created. The routine
xdrstdio_create fills in xdrs with encoding and decoding
information..
file
A pointer to the FILE structure that is to be associated with the
stream.
op
An XDR operation, one of: XDR_ENCODE, XDR_DECODE, and XDR_FREE.
4.42.2 – Description
Initializes a stdio stream for the specified file.
4.42.3 – Return Values
None
5 – Socket API Functions
Socket functions let you write network programs that can be
easily ported to other operating systems.
5.1 – accept()
Accepts a connection on a passive socket.
The $QIO equivalent is the IO$_ACCESS system service with the
IO$M_ACCEPT modifier.
Format
#include <types.h>
#include <socket.h>
int accept ( int s, struct sockaddr *addr, int *addrlen );
(_DECC_V4_SOURCE)
int accept ( int s, struct sockaddr *addr, size_t *addrlen );
(not_DECC_V4_SOURCE)
5.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 argument filled in with the address of the connecting
entity, as known to the TCP/IP kernel. The exact format of the
structure to which the address parameter points is determined by
the address family. Specify either the IPv4 address family (AF_
INET) or the IPv6 address family (AF_INET6).
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 TCP/IP kernel.
5.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).
You can select a socket for the purposes of performing an accept
by selecting it for a read.
Related Functions
See also bind(), connect(), listen(), select(), and socket().
5.1.3 – Return Values
x A positive integer that is a descriptor for
the accepted socket.
-1 Error; errno is set to indicate the error.
5.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.
5.2 – bind()
Binds a name to a socket.
The $QIO equivalent is the IO$_SETMODE system service with the p3
argument.
Format
#include <types.h>
#include <socket.h>
int bind ( int s, struct sockaddr *name, int namelen );
(_DECC_V4_SOURCE)
int bind ( int s, const struct sockaddr *name, size_t namelen
); (not_DECC_V4_SOURCE)
5.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 or AF_INET6) socket
address.
namelen
The size, in bytes, of the structure pointed to by name.
5.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().
5.2.3 – Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
5.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.
5.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 );
5.3.1 – Argument
s
A socket descriptor.
5.3.2 – Description
This function deletes a descriptor from the per-process object
reference table. Associated TCP connections close first.
If a call to connect() fails for a socket in connection mode,
applications should use close() to deallocate the socket and
descriptor.
Related Functions
See also accept(), socket(), and write().
5.3.3 – Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
5.3.4 – Errors
EBADF The socket descriptor is invalid.
EINTR The close() function was interrupted by a
signal that was caught.
5.4 – connect()
Initiates a connection on a socket.
The $QIO equivalent is the IO$_ACCESS system service.
Format
#include <types.h>
#include <socket.h>
int connect ( int s, struct sockaddr *name, int namelen );
(_DECC_V4_SOURCE)
int connect ( int s, const struct sockaddr *name, size_t
namelen ); (not_DECC_V4_SOURCE)
5.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 or
AF_INET6).
namelen
The size, in bytes, of the structure pointed to by name.
5.4.2 – Description
This function initiates a connection on a socket.
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.
If a call to connect() fails for a connection-mode socket,
applications should use close() 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().
5.4.3 – Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
5.4.4 – Errors
EADDRINUSE Configuration problem. There are insufficient
ports available for the attempted connection.
The inet subsystem attribute ipport_
userreserved 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 member 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.5 – decc$get_sdc()
Returns the socket device's OpenVMS I/O channel (SDC) associated
with a socket descriptor.
Format
#include <socket.h>
short int decc$get_sdc ( int s );
5.5.1 – Argument
s
A socket descriptor.
5.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 device
sockets. This function returns the SDC used by a given socket
descriptor so you can directly access the TCP/IP facilities by
means of $QIO system services.
5.5.3 – Return Values
0 Indicates that s is not an open socket
descriptor.
x The SDC number.
5.6 – decc$socket_fd
Returns the socket descriptor associated with a Socket Device
Channel (SDC) for direct use with the OpenVMS C Run-Time Library.
Format
#include <socket.h>
int decc$socket_fd (int channel);
5.6.1 – Argument
channel
A valid SDC.
5.6.2 – Description
This function associates a valid socket channel with an HP
C run-time library file descriptor, and returns the file
descriptor. The file descriptor can then be used with any HP C
run-time library function that takes a file descriptor or socket
descriptor as an input parameter.
5.6.3 – Return Values
x The socket descriptor.
-1 Indicates an error; the socket descriptor
cannot be allocated.
5.7 – endhostent()
Closes hosts database file.
Format
#include <netdb.h>
void endhostent (void);
5.7.1 – Description
This function closes the hosts database file
(TCPIP$ETC:IPNODES.DAT), previously opened with a
gethostbyaddr(), gethostent(), or gethostbyname() function call.
If the most recent sethostent() function call is executed with
a nonzero stay_open parameter, the endhostent() function does
not close the hosts database file. You cannot close the hosts
database file until you make a call to exit(). A second call
to sethostent() is issued with a stay_open parameter equal
to 0 (zero). This ensures that a subsequent endhostent() call
succeeds.
Related Functions
See also gethostbyaddr(), gethostent(), and gethostbyname().
5.8 – endnetent()
Closes the networks database file.
Format
#include <netdb.h>
void endnetent (void);
5.8.1 – Description
This function closes the networks database file
(TCPIP$SYSTEM:NETWORKS.DAT), previously opened with the
getnetent(), setnetent(), getnetbyaddr(), or getnetbyname()
function.
Related Functions
See also getnetent(), getnetbyaddr(), getnetbyname(), and
setnetent().
5.9 – endprotoent()
Resets the index for the protocols table.
Format
#include <netdb.h>
void endprotoent (void);
5.9.1 – Description
This function resets the index for the protocols table
previously accessed with a getprotoent(), getprotobyname(), or
getprotobynumber() function call.
Related Functions
See also getprotobyname(), getprotoent(), and
getprotobynumber().
5.10 – endservent()
Closes the services database file.
Format
#include <netdb.h>
void endservent (void);
5.10.1 – Description
This function closes the services database file
(TCPIP$ETC:SERVICES.DAT), previously opened with the
getservent(), getservbyname(), or getservbyport() function.
Related Functions
See also getservent(), getservbyname(), and getservbyport().
5.11 – freeaddrinfo()
Frees system resources used by an address information structure.
Format
#include <netdb.h>
void freeaddrinfo ( struct addrinfo *ai );
5.11.1 – Arguments
ai
Points to an addrinfo structure to be freed. The NETDB.H header
file defines the addrinfo structure.
5.11.2 – Description
This function frees an addrinfo structure and any dynamic storage
pointed to by the structure. The process continues until the
function encounters a NULL ai_next pointer.
5.12 – gai_strerror()
Provides a descriptive text string that corresponds to an EAI_xxx
error value.
Format
#include <netdb.h>
const char *gai_strerror ( int ecode );
5.12.1 – Arguments
ecode
The ecode argument is one of the EAI_xxx values defined for the
getaddrinfo() and getnameinfo() functions.
The values for ecode are:
EAI_AGAIN The name could not be resolved at this time.
Future attempts may succeed.
EAI_BADFLAGS The flags parameter had an invalid value.
EAI_FAIL A nonrecoverable error occurred when attempting
to resolve the name.
EAI_FAMILY The address family was not recognized.
EAI_MEMORY There was a memory allocation failure when
trying to allocate storage for the return value.
EAI_NONAME The name does not resolve for the supplied
parameters. Neither nodename nor servname
were supplied. At least one of these must be
supplied.
EAI_SERVICE The service passed was not recognized for the
specified socket type.
EAI_SOCKTYPE The intended socket type was not recognized.
EAI_SYSTEM A system error occurred; the error code can be
found in errno.
5.12.2 – Description
This function returns a descriptive text string that corresponds
to an EAI_xxx error value. The return value points to a string
that describes the error. If the argument is not one of the EAI_
xxx values, the function returns a pointer to a string whose
contents indicate an unknown error.
For a complete list of error codes, see Error Codes.
5.12.3 – Return Values
x text string
-1 Failure
5.13 – getaddrinfo()
Takes a service location (nodename) or a service name (servname),
or both, and returns a pointer to a linked list of one or more
structures of type addrinfo.
Format
#include <socket.h>
#include <netdb.h>
int getaddrinfo ( const char *nodename, const char *servname,
const struct addrinfo *hints, struct addrinfo
**res );
5.13.1 – Arguments
nodename
Points to a network node name, alias, or numeric host address
(for example, an IPv4 dotted-decimal address or an IPv6
hexadecimal address). An IPv6 nonglobal address with an intended
scope zone may also be specified. This is a null-terminated
string or NULL. NULL means the service location is local to the
caller. The nodename and servname arguments must not both be
NULL.
servname
Points to a network service name or port number. This is a null-
terminated string or NULL; NULL returns network-level addresses
for the specified nodename. The nodename and servname arguments
must not both be NULL.
hints
Points to an addrinfo structure that contains information about
the type of socket, address family, or protocol the caller
supports. The NETDB.H header file defines the addrinfo structure.
If hints is a null pointer, the behavior is the same as if
addrinfo contained the value 0 for the ai_flags, ai_socktype
and ai_protocol members and AF_UNSPEC for the ai_family member.
res
Points to a linked list of one or more addrinfo structures.
5.13.2 – Description
This function takes a service location (nodename) or a service
name (servname), or both, and returns a pointer to a linked list
of one or more structures of type addrinfo. Its members specify
data obtained from the local hosts database TCPIP$ETC:IPNODES.DAT
file, the local TCPIP$HOSTS.DAT file, or one of the files
distributed by DNS/BIND.
The NETDB.H header file defines the addrinfo structure.
If the hints argument is non-NULL, all addrinfo structure members
other than the following members must be zero or a NULL pointer:
o ai_flags
Controls the processing behavior of getaddrinfo(). See Member
Values for a complete description of the flags.
o ai_family
Specifies to return addresses for use with a specific protocol
family.
- If you specify a value of AF_UNSPEC, getaddrinfo() returns
addresses for any protocol family that can be used with
nodename or servname.
- If the value is not AF_UNSPEC and ai_protocol is not zero,
getaddrinfo() returns addresses for use only with the
specified protocol family and protocol.
- If the application handles only IPv4, set this member of
the hints structure to PF_INET.
o ai_socktype
Specifies a socket type for the given service. If you
specify a value of 0, you will accept any socket type. This
resolves the service name for all socket types and returns all
successful results.
o ai_protocol
Specifies a network protocol. If you specify a value of 0, you
will accept any protocol. If the application handles only TCP,
set this member to IPPROTO_TCP.
Member Values describes the values for ai_flags members.
Table 4-1 ai_flags Member Values
Flag Value Description
AI_V4MAPPED If ai_family is AF_INET, the flag is ignored.
If ai_family is AF_INET6, getaddrinfo() searches
for AAAA records.
The lookup sequence is:
1. Local hosts database
2. TCPIP$ETC:IPNODES.DAT
3. BIND database
The lookup for a particular type of record,
for example an AAAA record, will be performed
in each database before moving on to perform a
lookup for the next type of record.
o If AAAA records are found, returns IPv6
addresses; no search for A records is
performed.
o If no AAAA records are found, searches for A
records.
o If A records found, returns IPv4-mapped IPv6
addresses.
o If no A records found, returns a NULL
pointer.
AI_ALL| If ai_family is AF_INET, the flag is ignored.
AI_V4MAPPED
If the ai_family is AF_INET6, getaddrinfo()
searches for AAAA records.
The lookup sequence is:
1. Local hosts database
2. TCPIP$ETC:IPNODES.DAT
3. BIND database
The lookup for a particular type of record,
for example an AAAA record, will be performed
in each database before moving on to perform a
lookup for the next type of record.
o If AAAA records are found, IPv6 addresses
will be included with the returned addresses.
o If A records are found, returns IPv4-mapped
IPv6 addresses and also any IPv6 addresses
that were found with the AAAA record search.
o If no A records found, returns a NULL
pointer.
AI_CANONNAME If the nodename argument is not NULL, the
function searches for the specified node's
canonical name.
Upon successful completion, the ai_canonname
member of the first addrinfo structure in the
linked list points to a null-terminated string
containing the canonical name of the specified
node name.
If the nodename argument is an address literal,
the ai_cannonname member will refer to the
nodename argument that has been converted to
its numeric binary form, in network byte order.
If the canonical name is not available, the ai_
canonname member refers to the nodename argument
or to a string with the same contents.
The ai_flags field contents are undefined.
AI_NUMERICHOST A non-NULL node name string must be a numeric
host address string.
Resolution of the service name is not performed.
AI_NUMERICSERV A non-NULL service name string must be a numeric
port string.
Resolution of the service name is not performed.
AI_PASSIVE Returns a socket address structure that your
application can use in a call to bind().
If the nodename parameter is a NULL pointer,
the IP address portion of the socket address
structure is set to INADDR_ANY (for an IPv4
address) or IN6ADDR_ANY_INIT (for an IPv6
address).
If not set, returns a socket address structure
that your application can use to call connect()
(for a connection-oriented protocol) or either
connect(), sendto(), or sendmsg() (for a
connectionless protocol). If the nodename
argument is a NULL pointer, the IP address
portion of the socket address structure is set
to the loopback address.
AI_ADDRCONFIG Used in combination with other flags, modifies
the search based on the source address or
addresses configured on the system.
You can use the flags in any combination to achieve finer control
of the translation process. Many applications use the combination
of the AI_ADDRCONFIG and AI_V4MAPPED flags to control their
search.
o If the value of ai_family is AF_INET, and an IPv4 source
address is configured on the system, getaddrinfo() searches
for A records only. If found, getaddrinfo() returns IPv4
addresses. If not, getaddrinfo() returns a NULL pointer.
o If the value of ai_family is AF_INET6 and an IPv6 source
address is configured on the system, getaddrinfo() searches
for AAAA records. If found, getaddrinfo() returns IPv6
addresses. If not, and if an IPv4 address is configured on
the system, getaddrinfo() searches for A records. If found,
getaddrinfo() returns IPv4-mapped IPv6 addresses. If not,
getaddrinfo() returns a NULL pointer.
These flags are defined in the NETDB.H header file.
addrinfo Structure Processing
Upon successful return, getaddrinfo() returns a pointer to a
linked list of one or more addrinfo structures. The application
can process each addrinfo structure in the list by following
the ai_next pointer until a NULL pointer is encountered. In each
returned addrinfo structure, the ai_family, ai_socktype, and ai_
protocol members are the corresponding arguments for a call to
the socket() function. The ai_addr member points to a filled-in
socket address structure whose length is specified by the ai_
addrlen member.
5.13.3 – Return Values
0 Indicates success
-1 Indicates an error
5.13.4 – Errors
EAI_AGAIN The name could not be resolved at this time.
Future attempts may succeed.
EAI_BADFLAGS The flags parameter had an invalid value.
EAI_FAIL A nonrecoverable error occurred when
attempting to resolve the name.
EAI_FAMILY The address family was not recognized.
EAI_MEMORY There was a memory allocation failure when
trying to allocate storage for the return
value.
EAI_NONAME The name does not resolve for the supplied
parameters. Neither nodename nor servname
were supplied. At least one of these must be
supplied.
EAI_SERVICE The service passed was not recognized for the
specified socket type.
EAI_SOCKTYPE The intended socket type was not recognized.
EAI_SYSTEM A system error occurred; the error code can be
found in errno.
5.14 – gethostaddr
Returns the standard host address for the processor.
Format
#include <socket.h>
int gethostaddr (char *addr);
5.14.1 – Argument
addr
A pointer to the buffer in which the standard host address for
the current processor is returned.
5.14.2 – Description
This function returns the standard host address for the current
processor. The returned address is null-terminated. The addr
parameter must point to at least 16 bytes of free space.
Host addresses are limited to 16 characters.
5.14.3 – Return Values
0 Indicates success.
-1 Indicates that an error has occurred and is
further specified in the global errno.
5.15 – gethostbyaddr()
Searches the hosts database that is referenced by the TCPIP$HOST
logical name for a host record with a given IPv4 address. If the
host record is not found there, the function may also invoke the
BIND resolver to query the appropriate name server.
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 );
5.15.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 (AF_INET).
5.15.2 – Description
This function finds the first host record with the specified
address in the hosts database or using DNS/BIND.
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.
5.15.3 – Return Values
x A pointer to an object having the hostent
structure.
NULL Indicates an error; errno is set to one of the
following values.
5.15.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.
5.16 – gethostbyname()
Searches the hosts database that is referenced by the TCPIP$HOST
logical name for a host record with the specified name or alias.
If the host record is not found, this function may also invoke
the BIND resolver to query the appropriate name server for the
information.
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 );
5.16.1 – Argument
name
A pointer to a null-terminated character string containing the
name or an alias of the host being sought.
5.16.2 – Description
This function finds the first host with the specified name or
alias in the hosts database, or using DNS/BIND.
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.
5.16.3 – Return Values
x A pointer to an object having the hostent
structure.
NULL Indicates an error. errno is set to one of the
following values.
5.16.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.
5.17 – gethostent()
Retrieves an entry from the hosts database file.
Format
#include <netdb.h>
struct hostent *gethostent (void);
5.17.1 – Description
The gethostent() function reads the next entry of the hosts
database file (TCPIP$ETC:IPNODES.DAT).
See the NETDB.H header file for a description of the hostent
structure.
The gethostent() function uses a common static area for its
return values. Therefore, subsequent calls to gethostent()
overwrite any existing host entry. You must make a copy of the
host entry, if you wish to save it.
5.17.2 – Return Values
x A pointer to an object having the hostent
structure.
NULL Indicates an error; errno is set to one of the
following values.
5.17.3 – 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.
5.18 – gethostname()
Returns the fully-qualified name of the local host.
Format
#include <types.h>
#include <socket.h>
int gethostname ( char *name, int namelen) ; (_DECC_V4_SOURCE)
int gethostname ( char *name, size_t namelen) ;
(not_DECC_V4_SOURCE)
5.18.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.
5.18.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.
5.18.3 – Return Values
0 Indicates successful completion.
-1 Indicates an error occurred. The value of
errno indicates the error.
5.18.4 – Errors
EFAULT The buffer described by name and namelen is
not a valid, writable part of the user address
space.
5.19 – getnameinfo()
Maps addresses to names in a protocol-independent way.
Format
#include <socket.h>
#include <netdb.h>
int getnameinfo ( const struct sockaddr *sa, size_t salen,
char *node, size_t nodelen, char *service,
size_t servicelen, int flags );
5.19.1 – Arguments
sa
Points either to a sockaddr_in structure (for IPv4) or to a
sockaddr_in6 structure (for IPv6) that holds the IP address and
port number.
salen
Specifies the length of either the sockaddr_in structure or the
sockaddr_in6 structure.
node
Points to a buffer in which to receive the null-terminated
network node name or alias corresponding to the address contained
in the sa. A NULL pointer instructs getnameinfo() to not return
a node name. The node argument and service argument must not both
be zero.
nodelen
Specifies the length of the node buffer. A value of zero
instructs getnameinfo() to not return a node name.
service
Points to a buffer in which to receive the null-terminated
network service name associated with the port number contained
in sa. A NULL pointer instructs getnameinfo() to not return a
service name. The node argument and service argument must not
both be 0.
servicelen
Specifies the length of the service buffer. A value of zero
instructs getnameinfo() to not return a service name.
flags
Specifies changes to the default actions of getnameinfo(). By
default, getnameinfo() searches for the fully-qualified domain
name of the node in the hosts database and returns it. See Flags
for a list of flags and their meanings.
5.19.2 – Description
This function looks up an IP address and port number in a
sockaddr structure specified by sa and returns node name and
service name text strings in the buffers pointed to by the node
and service arguments, respectively.
If the node name is not found, getnameinfo() returns the numeric
form of the node address, regardless of the value of the flags
argument. If the service name is not found, getnameinfo() returns
the numeric form of the service address (port number) regardless
of the value of the flags argument.
The application must provide buffers large enough to hold the
fully-qualified domain name and the service name, including the
terminating null characters.
Flags describes the flag bits and, if set, their meanings. The
flags are defined in the NETDB.H header file.
Table 4-2 getnameinfo() Flags
Flag Value Description
NI_DGRAM Specifies that the service is a datagram
service (SOCK_DGRAM). The default assumes
a stream service (SOCK_STREAM). This is
required for the few ports (512-514) that
have different services for UDP and TCP.
NI_NAMEREQD Returns an error if the host name cannot be
located in the hosts database.
NI_NOFQDN Searches the hosts database and returns the
node name portion of the fully-qualified
domain name for local hosts.
NI_NUMERICHOST Returns the numeric form of the host's address
instead of its name. Resolution of the host
name is not performed.
NI_NUMERICSERV Returns the numeric form (port number) of the
service address instead of its name. The host
name is not resolved.
5.19.3 – Return Values
0 Indicates success.
x Indicates an error occurred. The value of
errno indicates the error.
5.19.4 – Errors
EAI_AGAIN The name could not be resolved at this time.
Future attempts may succeed.
EAI_BADFLAGS The flags argument had an invalid value.
EAI_FAIL A nonrecoverable error occurred when
attempting to resolve the name.
EAI_FAMILY The address family was not recognized.
EAI_MEMORY There was a memory allocation failure when
trying to allocate storage for the return
value.
EAI_NONAME The name does not resolve for the supplied
parameters. Neither the node name nor the
service name were supplied. At least one of
these must be supplied.
EAI_SYSTEM A system error occurred; the error code can be
found in errno.
5.20 – getnetbyaddr()
Searches the network database that is referenced by the
TCPIP$NETWORK logical name for a network record with the
specified address. If the network record is not found,
this function may invoke the BIND resolver to search
TCPIP$SYSTEM:NETWORKS.DAT.
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) ;
5.20.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 or AF_INET6).
5.20.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.
5.20.3 – Return Values
x A pointer to an object having the netent
structure.
NULL Indicates end of file or an error.
5.20.4 – Errors
EINVAL The net argument is invalid.
ESRCH The search failed.
5.21 – getnetbyname()
Searches the networks database for a network record with
a specified name or alias. If the network record is not
found, this function may invoke the BIND resolver to search
TCPIP$SYSTEM:NETWORKS.DAT.
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 );
5.21.1 – Argument
name
A pointer to a null-terminated character string containing either
the network name or an alias for the network name.
5.21.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.
5.21.3 – Return Values
NULL Indicates end of file or an error.
x A pointer to an object having the netent
structure.
5.21.4 – Errors
EFAULT The buffer described by name is not a valid,
writable part of the user address space.
EINVAL The name argument is invalid.
ESRCH The search failed.
5.22 – getnetent()
Retrieves an entry from the networks database file.
Format
#include <netdb.h>
struct netent *getnetnet (void);
5.22.1 – Description
This function opens and sequentially reads the networks database
file (TCPIP$SYSTEM:NETWORKS.DAT) to retrieve network information.
Returns a pointer to a netent structure that contains the
equivalent fields for a network description line in the networks
database file. The netent structure is defined in the NETDB.H
header file.
The networks database file remains open after a call by the
getservent() function. Use the endnetent() function to close the
networks database file. Use the setnetent() function to open the
networks database file and reset the file marker to the beginning
of the file.
The getnetent() function uses a common static area for its
return values, so subsequent calls to this function overwrite
any existing network entry. To save the network entry, you must
make a copy of it.
Related Functions
See also setnetent and endnetent.
5.22.2 – Return Values
x A pointer to a netent structure.
0 Indicates an error or end of file.
5.23 – 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
); (_DECC_V4_SOURCE)
int getpeername ( int s, struct sockaddr *name, size_t
*namelen ); (not_DECC_V4_SOURCE)
5.23.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.
5.23.2 – Description
This function returns the name of the peer connected to the
specified socket descriptor.
Related Functions
See also bind(), socket(), and getsockname().
5.23.3 – Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
5.23.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.
5.24 – getprotobyname()
Searches the protocols table until a matching protocol name is
found or until the end of the table is encountered.
Format
#include <netdb.h>
struct protoent *getprotobyname ( char *name );
5.24.1 – Argument
name
A pointer to a string containing the desired protocol name.
5.24.2 – Description
This function returns a pointer to a protoent structure
containing data from the protocols table. For information about
the protoent structure, refer to protoent Structure.
All information is contained in a static area, so it must be
copied to be saved.
Related Functions
See also getprotoent() and getprotobynumber().
5.24.3 – Return Values
NULL Indicates the end of the table or an error.
x A pointer to a protoent structure.
5.25 – getprotobynumber()
Searches the protocols table until a matching protocol number is
found or until the end of the table is encountered.
Format
#include <netdb.h>
struct protoent *getprotobynumber ( int *proto ) ;
5.25.1 – Argument
proto
A pointer to a string containing the desired protocol number.
5.25.2 – Description
This function returns a pointer to a protoent structure
containing the data from the protocols table. For information
about the protoent structure, refer to protoent Structure.
All information is contained in a static area, so it must be
copied to be saved.
Related Functions
See also getprotoent() and getprotobyname().
5.25.3 – Return Values
NULL Indicates end of table or an error.
x A pointer to a protoent structure.
5.26 – getprotoent()
Reads the next entry from the protocols table.
Format
#include <netdb.h>
struct protoent *getprotoent();
5.26.1 – Description
This function returns a pointer to a protoent structure
containing the data from the protocols table. For information
about the protoent structure, refer to protoent Structure.
The getprotoent() function keeps an index to the table, allowing
successive calls to be used to search the entire table.
All information is contained in a static area, so it must be
copied to be saved.
Related Functions
See also getprotobyname() and getprotobynumber().
5.26.2 – Return Values
NULL Indicates the end of the table or an error.
x A pointer to a protoent structure.
5.27 – getservbyname()
Gets information on the specified service from the services
database that is referenced by the TCPIP$SERVICE logical name.
If not found there, this function may invoke the BIND resolver to
search TCPIP$ETC:SERVICES.DAT.
Format
#include <netdb.h>
struct servent *getservbyname ( char *name, char *proto );
5.27.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.
5.27.2 – Description
This function searches the services database until a matching
service name is found or the 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. For information
about the servent structure, refer to servent Structure.
All information is contained in a static area, so it must be
copied to be saved.
Related Functions
See also getservbyport().
5.27.3 – Return Values
NULL Indicates end of file or an error.
x A pointer to a servent structure.
5.28 – getservbyport()
Gets information on the specified port from the services database
that is referenced by the TCPIP$SERVICE logical name. If the
specified port is not found, this function may invoke the BIND
resolver to search TCPIP$ETC:SERVICES.DAT.
Format
#include <netdb.h>
struct servent *getservbyport ( int port, char *proto );
5.28.1 – Arguments
port
The port number for which to search. This port number should be
specified in network byte order. You can use the htons() function
to convert the port number to network byte order.
proto
A pointer to a string containing the name of the protocol (TCP or
UDP) for which to search.
5.28.2 – Description
This function searches the services database 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. For information about the servent structure,
refer to servent Structure.
All information is contained in a static area, so it must be
copied to be saved.
Related Functions
See also getservbyname().
5.28.3 – Return Values
NULL Indicates end of file or an error.
x A pointer to a servent structure.
5.28.4 – Errors
EPERM Not owner. Indicates that the wrong port
number was specified.
5.29 – getservent()
Retrieves an entry from the services database file.
Format
#include <netdb.h>
struct servent *getservent (void);
5.29.1 – Description
This function reads the next line of the services database file
(TCPIP$ETC:SERVICES.DAT).
An application program can use the getservent() function to
retrieve information about a service (such as the protocol or
the ports it uses) from the services database.
The getservent() function returns a servent structure that
contains information from the services database file. See servent
Structure for a description of the servent structure. The servent
structure is defined in the NETDB.H header file.
The ASCII text services database file remains open after a call
by the getservent() function. Use the endservent() function to
close the services database file. Use the setservent() function
to open the services database file and reset the file marker to
the beginning of the file.
The getservent function uses a common static area for its return
values, so subsequent calls to this function overwrite any
existing service entry. To save the services entry, you must
make a copy of it.
Related Functions
See also setservent and endservent.
5.29.2 – Return Values
x A pointer to a servent structure.
NULL Indicates an error or end of file.
5.30 – 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
); (_DECC_V4_SOURCE)
int getsockname ( int s, struct sockaddr *name, size_t
*namelen ); (not_DECC_V4_SOURCE)
5.30.1 – Arguments
s
A socket descriptor created with the 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 indicates the actual size, in
bytes, of the name returned.
5.30.2 – Description
This function returns the current name for the specified socket
descriptor. The name is in a format specific to the address
family assigned to the socket (AF_INET, or AF_INET6 with BSD
4.4 when _SOCKADDR_LEN is defined).
The bind() function, not the getsockname() function, makes the
association of the name to the socket.
Related Functions
See also bind() and socket().
5.30.3 – Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
5.30.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.
5.31 – 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,
int *optlen ); (_DECC_V4_SOURCE)
int getsockopt ( int s, int level, int optname, void *optval,
size_t *optlen ); (not_DECC_V4_SOURCE)
5.31.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. The IPPROTO
values are defined in the IN.H header file
(for IPv4), or the IN6.H header file (for
IPv6).
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 indicate the
actual size of the option value returned.
5.31.2 – Description
This function gets information on socket options. See the
appropriate protocol for information about available options
at each protocol level.
5.31.3 – Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
5.31.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.
5.32 – herror()
Writes a message to standard error explaining h_error.
Format
#include <netdb.h>
void herror (const char *string);
5.32.1 – Argument
string
A user-printable string.
5.32.2 – Description
This function maps the error number in the external variable h_
errno to a locale-dependent error message.
5.33 – hostalias()
Searches for host aliases associated with a name.
Format
#include <resolv.h>
char *hostalias (const char *name);
5.33.1 – Argument
name
Points to the name of the host that you want to retrieve aliases
from.
5.33.2 – Description
This function searches for the alias associated with the name
argument. The HOSTALIASES logical name can be used to define the
name of a file that lists the host aliases, in the form:
host alias
5.33.3 – Return Values
x The host alias.
NULL Indicates an error.
5.34 – hstrerror()
Returns an error message string.
Format
#include <string.h>
char *hstrerror (int errnum);
5.34.1 – Arguments
errnum
An error number specifying a value of h_errno.
5.34.2 – Description
This function maps the error number specified by the errnum
argument to a location-dependent error message string and returns
a pointer to the string. The string pointed to by the return
value cannot be modified by the program, but could be overwritten
by subsequent calls to this function.
5.34.3 – Return Values
x A pointer to the generated message string.
-1 On error, errno might be set, but no return
value is reserved to indicate an error.
5.34.4 – Errors
If the hstrerror() function fails, errno is
set to EINVAL, indicating the value of the
errnum argument is an invalid error number.
5.35 – htonl()
Converts longwords from host byte order to network byte order.
Format
#include <in.h>
unsigned long int htonl ( unsigned long int hostlong );
5.35.1 – Argument
hostlong
A longword in host byte order (OpenVMS systems).
5.35.2 – Description
This function converts 32-bit unsigned integers from host byte
order to network byte order.
Data bytes transmitted over the network are expected to be
in network byte order. Some hosts, like OpenVMS, have an
internal data representation format that is different from the
network byte order; this is called the host byte order. Network
byte order places the byte with the most significant bits at
lower addresses, but OpenVMS host byte order places the most
significant bits at the highest address.
This function can be used to convert IP addresses from host byte
order to network byte order.
NOTE
The 64-bit return from OpenVMS Alpha and I64 systems has
zero-extended bits in the high 32 bits of R0.
5.35.3 – Return Value
x A longword in network byte order.
5.36 – htons()
Converts short integers from host byte order to network byte
order.
Format
#include <in.h>
unsigned short int htons ( unsigned short int hostshort );
5.36.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.
5.36.2 – Description
This function converts 16-bit unsigned integers from host byte
order to network byte order.
Data bytes transmitted over the network are expected to be
in network byte order. Some hosts, like OpenVMS, have an
internal data representation format that is different from the
network byte order; this is called the host byte order. Network
byte order places the byte with the most significant bits at
lower addresses, but OpenVMS host byte order places the most
significant bits at the highest address.
This function is most often used with ports returned by the
getservent() function. To convert port numbers from OpenVMS host
byte order to network byte order, use the htons() function.
NOTE
The 64-bit return from OpenVMS Alpha and I64 systems has
zero-extended bits in the high 32 bits of R0.
5.36.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.
5.37 – if_freenameindex()
Frees dynamic memory allocated by if_nameindex() to the array of
interface names and indexes
Format
#include <if.h>
void if_freenameindex ( struct if_nameindex *ptr );
5.37.1 – Arguments
ptr
Points to an array of structures returned by the if_nameindex()
function.
5.37.2 – Description
The if_freenameindex() function frees dynamic memory allocated to
the array of interface names and indexes that the if_nameindex()
function returned.
5.38 – if_indextoname()
Maps an interface index to its corresponding name.
Format
#include <if.h>
char *if_indextoname ( unsigned int ifindex, char *ifname );
5.38.1 – Arguments
ifindex
The interface index.
ifname
Points to a buffer that is IFNAMSIZ bytes in length. (IFNAMSIZ is
defined in the IF.H header file.) If an interface name is found,
it is returned in the buffer.
5.38.2 – Description
This function maps an interface index to its corresponding name.
5.38.3 – Return Values
Interface name If interface name is found, it is returned to
the buffer.
NULL If no interface name corresponds to the
specified index, the function returns NULL
and sets errno to ENXIO.
5.38.4 – Errors
ENXIO No interface name corresponds to the specified
index.
System error A system error.
5.39 – if_nameindex()
Returns an array of all interface names and indexes.
Format
#include <if.h>
struct if_nameindex *if_nameindex ( void );
5.39.1 – Description
This function dynamically allocates memory for an array of
if_nameindex structures, one structure for each interface. A
structure with an if_index value of 0 and a NULL if_name value
indicates the end of the array.
The following if_nameindex structure must also be defined
by including the IF.H header file prior to the call to if_
nameindex():
struct if_nameindex {
unsigned int if_index;
char *if_name;
};
To free the memory allocated by this function, use the if_
freenameindex() function. If an error occurs, the function
returns a NULL pointer and sets errno to an appropriate value.
5.39.2 – Return Values
NULL Indicates an error; errno is set to an
appropriate value.
5.40 – if_nametoindex()
Maps an interface name to its corresponding index.
Format
#include <if.h>
unsigned int if_nametoindex ( const char *ifname );
5.40.1 – Arguments
ifname
Points to a buffer that contains the interface name.
5.40.2 – Description
This function maps an interface name to its corresponding
interface index number.
5.40.3 – Return Values
0 (zero) Interface does not exist.
x Upon successful conversion, the if_
nametoindex() function returns an interface
index number.
5.41 – inet6_opt_append()
Returns the length of an IPv6 extension header with a new option
and appends the option.
Format
#include <in6.h>
int inet6_opt_append ( void *extbuf, size_t extlen, int
offset, uint8_t type, size_t len, uint_t
align, void **databufp );
5.41.1 – Arguments
extbuf
Points to a buffer that contains an extension header. This is
either a valid pointer or a NULL pointer.
extlen
Specifies the length of the extension header to initialize. Valid
values are 0 if extbuf equals 0, a value returned by inet6_opt_
finish(), or any number that is a multiple of 8.
offset
Specifies the length of the existing extension header. Obtain
this value from a prior call to inet6_opt_init() or inet6_opt_
append().
type
Specifies the type of option. Specify a value from 2 to 255,
inclusive, excluding 194.
len
Specifies the length of the option data, excluding the option
type and option length fields. Specify a value from 0 to 255,
inclusive.
align
Specifies the alignment of the option. Specify one of the
following values: 1, 2, 4, or 8.
databufp
Points to a buffer that contains the option data.
5.41.2 – Description
This function, when called with extbuf as a NULL pointer and
extlen as 0, returns the updated number of bytes in an extension
header.
If you specify extbuf as a valid pointer and valid extlen and
align arguments, the function returns the same information as in
the previous case, but also inserts the pad option, initializes
the type and len fields, and returns a pointer to the location
for the option content.
After you call inet6_opt_append(), you can then use the data
buffer directly or call inet6_opt_set_val() to specify the option
contents.
5.41.3 – Return Values
x Upon successful completion, the inet6_opt_
append() function returns the updated number
of bytes in an extension header.
-1 Failure
5.41.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.
5.42 – inet6_opt_find()
Finds a specific option in an extension header.
Format
#include <in6.h>
int inet6_opt_find ( void *extbuf, size_t extlen, int offset,
uint8_t type, size_t *lenp, void **databufp
);
5.42.1 – Arguments
extbuf
Points to a buffer that contains an extension header.
extlen
Specifies the length, in bytes, of the extension header.
offset
Specifies the location in the extension header of an option.
Valid values are either 0 (zero) for the first option or the
length returned from a previous call to either inet6_opt_next()
or inet6_opt_find().
type
Specifies the type of option to find.
lenp
Points to the length of the option found.
databufp
Points to the option data.
5.42.2 – Description
This function searches a received option extension header for an
option specified by type. If it finds the specified option, it
returns the option length and a pointer to the option data. It
also returns an offset to the next option, which you can specify
in the offset argument to subsequent calls to inet6_opt_next()
in order to search for additional occurrences of the same option
type.
5.42.3 – Return Values
x Upon successful completion, the inet6_opt_
find() function returns an offset from which
you can begin the next search in the data
buffer.
-1 Failure
5.43 – inet6_opt_finish()
Returns the total length of an IPv6 extension header, including
padding, and initializes the option.
Format
#include <in6.h>
int inet6_opt_finish ( void *extbuf, size_t extlen, int offset
);
5.43.1 – Arguments
extbuf
Points to a buffer that contains an extension header. This is
either a valid pointer or a NULL pointer.
extlen
Specifies the length of the extension header to finish
initializing. A valid value is any number greater than or equal
to 0.
offset
Specifies the length of the existing extension header. Obtain
this value from a prior call to inet6_opt_init() or inet6_opt_
append().
5.43.2 – Description
This function, when called with extbuf as a NULL pointer and
extlen as 0, returns the total number of bytes in an extension
header, including final padding.
If you specify extbuf as a valid pointer and a valid extlen
argument, the function returns the same information as in the
previous case, increments the buffer pointer, and verifies that
the buffer is large enough to hold the header.
5.43.3 – Return Values
x Upon successful completion, the inet6_opt_
finish() function returns the total number
of bytes in an extension header, including
padding.
-1 Failure
5.44 – inet6_opt_get_val()
Extracts data items from the data portion of an IPv6 option.
Format
#include <in6.h>
int inet6_opt_get_val ( void *databuf, size_t offset, void
*val, int vallen );
5.44.1 – Arguments
databuf
Points to a buffer that contains an extension header. This is
a pointer returned by a call to inet6_opt_find() or inet6_opt_
next().
offset
Specifies the location in the data portion of the option from
which to extract the data. You can access the first byte after
the option type and length by specifying the offset of 0.
val
Points to a destination for the extracted data.
vallen
Specifies the length of the data, in bytes, to be extracted.
5.44.2 – Description
This function copies data items from data buffer databuf
beginning at offset to the location val. In addition, it returns
the offset for the next data field to assist you in extracting
option content that has multiple fields.
Make sure that each field is aligned on its natural boundaries.
5.44.3 – Return Values
x Upon successful completion, the inet6_opt_get_
val() function returns the offset for the next
field in the data buffer.
-1 Failure
5.45 – inet6_opt_init()
Returns the length of an IPv6 extension header with no options
and initializes the header.
Format
#include <in6.h>
int inet6_opt_init ( void *extbuf, size_t extlen );
5.45.1 – Arguments
extbuf
Points to a buffer that contains an extension header. This is
either a valid pointer or a NULL pointer.
extlen
Specifies the length of the extension header to initialize. Valid
values are 0 and any number that is a multiple of 8.
5.45.2 – Description
This function, when called with extbuf as a NULL pointer and
extlen as 0, returns the number of bytes in an extension header
that has no options.
If you specify extbuf as a valid pointer and extlen as a
number that is a multiple of 8, the function returns the same
information as in the previous case, initializes the extension
header, and sets the length field.
5.45.3 – Return Values
x Upon successful completion, the inet6_opt_
init() function returns the number of bytes in
an extension header with no options.
-1 Failure
5.46 – inet6_opt_next()
Parses received option extension headers.
Format
#include <in6.h>
int inet6_opt_next ( void *extbuf, size_t extlen, int
offset, uint8_t *typep, size_t *lenp, void
**databufp );
5.46.1 – Arguments
extbuf
Points to a buffer that contains an extension header.
extlen
Specifies the length, in bytes, of the extension header.
offset
Specifies the location in the extension header of an option.
Valid values are either 0 for the first option or the length
returned from a previous call to either inet6_opt_next() or
inet6_opt_find().
typep
Points to the type of the option found.
lenp
Points to the length of the option found.
databufp
Points to the option data.
5.46.2 – Description
This function parses a received option extension header and
returns the next option. In addition, it returns an offset to
the next option that you specify in the offset parameter to
subsequent calls to inet6_opt_next().
This function does not return any PAD1 or PADN options.
5.46.3 – Return Values
x Upon successful completion, the inet6_opt_
next() function returns the offset for the
next option in the data buffer.
-1 Failure
5.47 – inet6_opt_set_val()
Adds one component of the option content to the options header.
Format
#include <in6.h>
int inet6_opt_set_val ( void *databuf, size_t offset, void
*val int vallen );
5.47.1 – Arguments
databuf
Points to a buffer that contains an extension header. This is a
pointer returned by a call to inet6_opt_append().
offset
Specifies the location in the data portion of the option into
which to insert the data. You can access the first byte after the
option type and length by specifying the offset of 0 (zero).
val
Points to the data to be inserted.
vallen
Specifies the length of the data, in bytes, to be inserted.
5.47.2 – Description
This function copies data items at the location val into a data
buffer databuf beginning at offset. In addition, it returns the
offset for the next data field to assist you in composing content
that has multiple fields.
Make sure that each field is aligned on its natural boundaries.
5.47.3 – Return Values
x Upon successful completion, the inet6_opt_set_
val() function returns the offset for the next
field in the data buffer.
-1 Failure
5.48 – inet6_rth_add()
Adds an IPv6 address to the routing header under construction.
Format
#include <in6.h>
int inet6_rth_add ( void *bp, const struct in6_addr *addr );
5.48.1 – Arguments
bp
Points to a buffer that is to contain an IPv6 routing header.
addr
Points to an IPv6 address to add to the routing header.
5.48.2 – Description
This function adds an IPv6 address to the end of the routing
header under construction. The address pointed to by addr cannot
be an IPv6 V4-mapped address or an IPv6 multicast address.
The function increments the ip6r0_segleft member in the ip6_
rthdr0 structure. The ip6_rthdr0 structure is defined in the
IP6.H header file.
Only routing header type 0 is supported.
5.48.3 – Return Values
x Upon successful completion, the inet6_rth_
add() function returns 0 (zero).
-1 Failure
5.49 – inet6_rth_getaddr()
Retrieves an address for an index from an IPv6 routing header.
Format
#include <in6.h>
struct in6_addr *inet6_rth_getaddr ( const void *bp, int index
);
5.49.1 – Arguments
bp
Points to a buffer that contains an IPv6 routing header.
index
Specifies a value that identifies a position in a routing header
for a specific address. Valid values range from 0 to the return
value from inet6_rth_segments() minus 1.
5.49.2 – Description
This function uses a specified index value and retrieves a
pointer to an address in a routing header specified by bp. Call
inet6_rth_segments() before calling this function in order to
determine the number of segments (addresses) in the routing
header.
5.49.3 – Return Values
x Upon successful completion, the inet6_rth_
getaddr() function returns a pointer to an
address.
NULL pointer Failure
5.50 – inet6_rth_init()
Initializes an IPv6 routing header buffer.
Format
#include <in6.h>
void *inet6_rth_init ( void *bp, int bp_len, int type, int
segments );
5.50.1 – Arguments
bp
Points to a buffer that is to contain an IPv6 routing header.
bp_len
Specifies the length, in bytes, of the buffer.
type
Specifies the type of routing header. The valid value is IPV6_
RTHDR_TYPE_0 for IPv6 routing header type 0.
segments
Specifies the number of segments or addresses that are to be
included in the routing header. The valid value is from 0 to 127,
inclusive.
5.50.2 – Description
This function initializes a buffer and buffer data for an IPv6
routing header. The function sets the ip6r0_segleft, ip6r0_nxt,
and ip6r0_reserved members in the ip6_rthdr0 structure to zero.
In addition, it sets the ip6r0_type member to type and sets the
ip6r0_len member based on the segments argument. The ip6_rthdr0
structure is defined in the IP6.H header file.
The application must allocate the buffer. Use the inet6_rth_
space() function to determine the buffer size.
Use the returned pointer as the first argument to the inet6_rth_
add() function.
5.50.3 – Return Values
x Upon successful completion, the inet6_rth_
init() function returns a pointer to the
buffer that is to contain the routing header.
NULL pointer Failure. If the type is not supported, the bp
is a null, or the number of bp_len is invalid.
5.51 – inet6_rth_reverse()
Reverses the order of addresses in an IPv6 routing header.
Format
#include <in6.h>
int inet6_rth_reverse ( const void *in, void *out );
5.51.1 – Arguments
in
Points to a buffer that contains an IPv6 routing header.
out
Points to a buffer that is to contain the routing header with the
reversed addresses. This parameter can point to the same buffer
specified by the in parameter.
5.51.2 – Description
This function reads an IPv6 routing header and writes a new
routing header, reversing the order of addresses in the new
header. The in and out parameters can point to the same buffer.
The function sets the ip6r0_segleft member in the ip6_rthdr0
structure to the number of segments (addresses) in the new
header.
The ip6_rthdr0 structure is defined in the IP6.H header file.
5.51.3 – Return Values
0 (zero) Success
-1 Failure
5.52 – inet6_rth_segments()
Returns the number of segments (addresses) in an IPv6 routing
header.
Format
#include <in6.h>
int inet6_rth_segments ( const void *bp );
5.52.1 – Arguments
bp
Points to a buffer that contains an IPv6 routing header.
5.52.2 – Description
This function returns the number of segments (or addresses) in an
IPv6 routing header.
5.52.3 – Return Values
x Upon successful completion, the inet6_rth_
segments() function returns the number of
segments, 0 (zero) or greater than 0.
-1 Failure
5.53 – inet6_rth_space()
Returns the number of bytes required for an IPv6 routing header.
Format
#include <in6.h>
size_t inet6_rth_space ( int type, int segments );
5.53.1 – Arguments
type
Specifies the type of routing header. The valid value is IPV6_
RTHDR_TYPE_0 for IPv6 routing header type 0.
segments
Specifies the number of segments or addresses that are to be
included in the routing header. The valid value is from 0 to 127,
inclusive.
5.53.2 – Description
This function determines the amount of space, in bytes, required
for a routing header. Although the function returns the amount of
space required, it does not allocate buffer space. This enables
the application to allocate a larger buffer.
If the application uses ancillary data, it must pass the returned
length to CMSG_LEN() to determine the amount of memory required
for the ancillary data object, including the cmsghdr structure.
NOTE
If an application wants to send other ancillary data
objects, it must specify them to sendmsg() as a single msg_
control buffer.
5.53.3 – Return Values
x Upon successful completion, the inet6_rth_
space() function returns the length, in bytes,
of the routing header and the specified number
of segments.
0 (zero) Failure, if the type is not supported or the
number of segments is invalid for the type of
routing header.
5.54 – inet_aton()
Converts an IP address in the standard dotted-decimal format
to its numeric binary form, in network byte order. Replaces the
inet_addr() function.
Format
#include <inet.h>
int inet_aton ( const char *cp, struct in_addr *in);
5.54.1 – Argument
cp
A pointer to a null-terminated character string containing an
internet address in the standard internet dotted-decimal format.
in
A pointer to a buffer that is to contain the numeric internet
address in network byte order.
5.54.2 – Description
This function returns a numeric internet address in network byte
order that represents the internet address supplied in 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 and I64 systems has
zero-extended bits in the high 32 bits of R0.
5.54.3 – Return Value
1 Indicates success.
0 Indicates failure.
5.55 – inet_lnaof()
Returns the local network address portion of an IP address.
Format
#include <in.h>
#include <inet.h>
int inet_lnaof ( struct in_addr in );
5.55.1 – Argument
in
An IP address.
5.55.2 – Description
This function returns the local network address portion of a full
IP address.
NOTE
The 64-bit return from OpenVMS Alpha and I64 systems has
zero-extended bits in the high 32 bits of R0.
5.55.3 – Return Value
x The local network address portion of an IP
address, in host byte order.
5.56 – inet_makeaddr()
Returns an IP 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 );
5.56.1 – Arguments
net
An IP network address in host byte order.
lna
A local network address on network net in host byte order.
5.56.2 – Description
This function combines the net and lna arguments into a single IP
address.
NOTE
The 64-bit return from OpenVMS Alpha and I64 systems has
zero-extended bits in the high 32 bits of R0.
5.56.3 – Return Value
x An IP address in network byte order.
5.57 – inet_netof()
Returns the internet network address portion of an IP address.
Format
#include <in.h>
#include <inet.h>
int inet_netof ( struct in_addr in );
5.57.1 – Argument
in
An IP address.
5.57.2 – Description
This function returns the internet network address (NET) portion
of a full IP address.
NOTE
The 64-bit return from OpenVMS Alpha and I64 systems has
zero-extended bits in the high 32 bits of R0.
5.57.3 – Return Value
x The internet network portion of an IP address,
in host byte order.
5.58 – inet_network()
Converts a null-terminated text string representing an IP address
into a network address in local host format.
Format
#include <in.h>
#include <inet.h>
int inet_network ( const char *cp );
5.58.1 – Argument
cp
A pointer to an ASCII (null-terminated) character string
containing a network address in the dotted-decimal format.
5.58.2 – Description
This function returns an internet network address as a 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 and I64 systems has
zero-extended bits in the high 32 bits of R0.
5.58.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.
5.59 – inet_ntoa()
Converts an IP 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 );
5.59.1 – Argument
in
An IP address in network byte order.
5.59.2 – Description
This function converts an IP address into an ASCII (null-
terminated) string that represents the address in standard
internet dotted-decimal format.
The string is returned in a static buffer that is overwritten by
subsequent calls to inet_ntoa(). If you want to save the text
string, you should copy it.
5.59.3 – Return Value
x A pointer to a string containing the IP
address in dotted-decimal format.
5.60 – inet_ntop()
Converts a numeric address to a text string suitable for
presentation.
Format
#include <inet.h>
const char *inet_ntop ( int af, const void *src, char *dst,
size_t size );
5.60.1 – Arguments
af
Specifies the address family. Valid values are AF_INET for an
IPv4 address and AF_INET6 for an IPv6 address.
src
Points to a buffer that contains the numeric IP address.
dst
Points to a buffer that is to contain the text string.
size
Specifies the size of the buffer pointed to by the dst parameter.
For IPv4 addresses, the minimum buffer size is 16 bytes. For IPv6
addresses, the minimum buffer size is 46 bytes. INET_ADDRSTRLEN
constants are defined in the IN.H header file. INET6_ADDRSTRLEN
constants are defined in IN6.H.
5.60.2 – Description
This function converts a numeric IP address value to a text
string.
5.60.3 – Return Values
Pointer to the Success
buffer containing
the text string
Pointer to the Failure
buffer containing
NULL
5.61 – inet_pton()
Converts an address in its standard text presentation form into
its numeric binary form, in network byte order.
Format
#include <inet.h>
int inet_pton ( int af, const char *src, void *dst );
5.61.1 – Arguments
af
Specifies the address family. Valid values are AF_INET for an
IPv4 address and AF_INET6 for an IPv6 address.
src
Points to the address text string to be converted.
dst
Points to a buffer that is to contain the numeric address.
5.61.2 – Description
This function converts a text string to a numeric value in
network byte order.
o If the af parameter is AF_INET, the function accepts a string
in the standard IPv4 dotted-decimal format:
ddd.ddd.ddd.ddd
In this format, ddd is a one- to three-digit decimal number
between 0 and 255.
o If the af parameter is AF_INET6, the function accepts a string
in the following format:
x:x:x:x:x:x:x:x
In this format, x is the hexadecimal value of a 16-bit piece
of the address.
IPv6 addresses can contain long strings of zero (0) bits. To
make it easier to write these addresses, you can use double-
colon characters (::) one time in an address to represent 1 or
more 16-bit groups of zeros.
o For mixed IPv4 and IPv6 environments, the following format is
also accepted:
x:x:x:x:x:x:ddd.ddd.ddd.ddd
In this format, x is the hexadecimal value of a 16-bit piece
of the address, and ddd is a one- to three-digit decimal value
between 0 and 255 that represents the IPv4 address.
The calling application is responsible for ensuring that the
buffer referred to by the dst parameter is large enough to hold
the numeric address. AF_INET addresses require 4 bytes and AF_
INET6 addresses require 16 bytes.
5.61.3 – Return Values
1 Indicates success.
0 Indicates that the input string is neither a
valid IPv4 dotted-decimal string nor a valid
IPv6 address string.
-1 Indicates a failure. errno is set to the
following value.
5.61.4 – Errors
EAFNOSUPPORT The address family specified in the af
parameter is unknown.
5.62 – ioctl()
Controls I/O requests to obtain network information.
Format
#include <ioctl.h>
int ioctl ( int s, int request, ... /* arg */ );
5.62.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 IOCTL Requests for a complete list of supported 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.
5.62.2 – Description
This function performs a variety of device-specific functions.
The request and arg arguments are passed to the file designated
by the s argument 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.
5.62.3 – Return Values
-1 Error; errno is set to indicate the error.
5.62.4 – Errors
EBADF The s argument is not a valid socket
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 HP use. The s argument is not
associated with a network device, or the
specified request does not apply to the
specific network device.
ENXIO The request and arg arguments are valid for
this device driver, but the service requested
cannot be performed on the device.
5.63 – listen()
Converts an unconnected socket into a passive socket and
indicates that the TCP/IP kernel should accept incoming
connection requests directed to the socket.
The $QIO equivalent is the IO$_SETMODE service.
Format
int listen ( int s, int backlog );
5.63.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 by specifying the value of the
socket subsystem attribute somaxconn. (Refer to the HP TCP/IP
Services for OpenVMS Tuning and Troubleshooting guide for more
information.) The default value for the maximum number of pending
connections is 1024.
5.63.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().
5.63.3 – Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
5.63.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().
5.64 – ntohl()
Converts longwords from network byte order to host byte order.
Format
#include <in.h>
unsigned long ntohl ( unsigned long netlong );
5.64.1 – Argument
netlong
A longword in network byte order. Integers in network byte order
cannot be used for arithmetic computation on OpenVMS systems.
5.64.2 – Description
This function converts 32-bit unsigned integers from network byte
order to host byte order.
Data bytes transmitted over the network are expected to be
in network byte order. Some hosts, like OpenVMS, have an
internal data representation format that is different from the
network byte order; this is called the host byte order. Network
byte order places the byte with the most significant bits at
lower addresses, but OpenVMS host byte order places the most
significant bits at the highest address.
This function can be used to convert IP addresses from network
byte order to host byte order.
5.64.3 – Return Value
x A longword in host byte order.
5.65 – ntohs()
Converts short integers from network byte order to host byte
order.
Format
#include <in.h>
unsigned short ntohs ( unsigned short netshort );
5.65.1 – Argument
netshort
A short integer in network byte order. Integers in network
byte order cannot be used for arithmetic computation on OpenVMS
systems.
5.65.2 – Description
This function converts 16-bit unsigned integers from network byte
order to host byte order.
Data bytes transmitted over the network are expected to be
in network byte order. Some hosts, like OpenVMS, have an
internal data representation format that is different from the
network byte order; this is called the host byte order. Network
byte order places the byte with the most significant bits at
lower addresses, but OpenVMS host byte order places the most
significant bits at the highest address.
This function can be used to convert port numbers returned by
getservent() from network byte order to host byte order.
5.65.3 – Return Value
x A short integer in host byte order (OpenVMS
systems).
5.66 – poll()
Monitors conditions on multiple file descriptors.
Format
#include <poll.h>
int poll (struct pollfd fds[], nfds_t nfds, int timeout);
5.66.1 – Arguments
fds
An array of pollfd structures, one for each file descriptor of
interest. Each pollfd structure includes the following members:
int fd The file descriptor
int events The requested conditions
int revents The reported conditions
nfds
The number of pollfd structures in the fds array.
timeout
The maximum length of time (in milliseconds) to wait for one of
the specified events to occur.
5.66.2 – Description
This function provides applications with a mechanism for
multiplexing input/output over a set of file descriptors. For
each member of the array pointed to by fds, poll() examines the
given file descriptor for the events specified in events. The
number of pollfd structures in the fds array is specified by
nfds. The poll() function identifies those file descriptors on
which an application can read or write data, or on which certain
events have occurred.
The fds argument specifies the file descriptors to be examined
and the events of interest for each file descriptor. It is a
pointer to an array with one member for each open file descriptor
of interest. The array's members are pollfd structures within
which fd specifies an open file descriptor, and events and
revents are bitmasks constructed by OR-ing a combination of the
following event flags:
o POLLIN
Normal data may be received without blocking.
o POLLRDNORM
Same as POLLIN.
o POLLRDBAND
Out-of-band data may be received without blocking.
o POLLPRI
Same as POLLRDBAND
o POLLOUT
Normal data may be written without blocking.
o POLLWRNORM
Same as POLLOUT.
o POLLWRBAND
Out-of-band data may be written without blocking.
If the value of fd is less than 0, events is ignored and revents
is set to 0 in that entry on return from poll(). In each pollfd
structure, poll() clears the revents member except that where the
application requested a report on a condition by setting one of
the bits of events listed above, poll() sets the corresponding
bit in revents if the requested condition is true.
If none of the defined events have occurred on any selected file
descriptor, poll() waits at least timeout milliseconds for an
event to occur on any of the selected file descriptors. If the
value of timeout is 0, poll() returns immediately. If the value
of timeout is -1, poll() blocks until a specified event occurs or
until the call is interrupted.
The poll() function is not affected by the O_NONBLOCK flag.
On OpenVMS, the poll() function supports sockets only.
NOTE
HP recommends using the select() function for optimal
performance. The poll() function is provided to ease the
porting of existing applications from other platforms.
5.66.3 – Return Values
positive value Upon successful completion, the total number
of file descriptors selected (that is, file
descriptors for which the revents member is
nonzero).
0 Successful completion. The call timed out and
no file descriptors were selected.
-1 The poll() function failed. The errno is set
to indicate the error.
5.66.4 – Errors
EAGAIN The allocation of internal data structures
failed but a subsequent request may succeed.
EINTR A signal was caught during the poll()
function.
5.67 – read()
Reads data from a socket or file.
The $QIO equivalent is the IO$_READVBLK function.
Format
#include <unixio.h>
int read ( int d, void *buffer, int nbytes );
5.67.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.
5.67.2 – Description
This function reads bytes from a socket or file and places them
in a user-defined buffer.
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().
5.67.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.
5.67.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 read() 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.
5.68 – 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 );
(_DECC_V4_SOURCE)
size_t recv ( int s, void *buf, ssize_t len, int flags );
(not_DECC_V4_SOURCE)
5.68.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.
5.68.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 recv() 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().
5.68.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.
5.68.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.
5.69 – 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) ;
(_DECC_V4_SOURCE)
ssize_t recvfrom ( int s, void *buf, size_t len, int flags,
struct sockaddr *from, size_t *fromlen) ;
(not_DECC_V4_SOURCE)
5.69.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.
5.69.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().
5.69.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.
5.69.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.
5.70 – 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)
5.70.1 – Arguments
s
A socket descriptor created with the socket() function.
msg
A pointer to a msghdr structure for receiving the data.
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.
5.70.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().
5.70.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.
5.70.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
msghdr 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.
5.71 – 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 );
(_DECC_V4_SOURCE)
int select ( int nfds, fd_set *readfds, fd_set *writefds,
int *execptfds, struct timeval *timeout );
(not_DECC_V4_SOURCE)
5.71.1 – Arguments
nfds
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, which is defined in the SOCKET.H
header file. Note that a single process can have a maximum of
65535 simultaneous channels (including sockets) on OpenVMS Alpha
and I64 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.
5.71.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().
5.71.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.
5.71.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.
5.72 – 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 );
(_DECC_V4_SOURCE)
ssize_t send ( int s, const void *msg, size_t len, int flags
); (not_DECC_V4_SOURCE)
5.72.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.
5.72.2 – Description
This function sends data to a connected peer.
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.
Normally the send() function blocks if there is no space for
the incoming data in the buffer. It waits until the buffer space
becomes available. If the socket is set to nonblocking and there
is no space for the data, the send() function fails with the
EWOULDBLOCK error.
If the message is too large to be sent in one piece, and the
socket type is SOCK_DGRAM, which requires that messages be sent
in one piece, send() fails with the EMSGSIZE error.
If the address specified is an 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.
A success return from the send() does not guarantee that the data
has been received by the peer. All errors (except EWOULDBLOCK)
are detected locally. To determine when it is possible to send
more data, use the select() function.
Related Functions
See also read(), recv(), recvmsg(), recvfrom(), getsockopt(),
and socket().
5.72.3 – Return Values
n The number of bytes sent. This value normally
equals len.
-1 Error; errno is set to indicate the error.
5.72.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.
5.73 – 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)
5.73.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.
5.73.2 – Description
This function sends the data in a msghdr structure to any other
socket.
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.
Normally the sendmsg() function blocks if there is no space for
the incoming data in the buffer. It waits until the buffer space
becomes available. If the socket is set to nonblocking and there
is no space for the data, the sendmsg() function fails with the
EWOULDBLOCK error.
If the message is too large to be sent in one piece, and the
socket type is SOCK_DGRAM, which requires that messages be sent
in one piece, sendmsg() fails with the EMSGSIZE error.
If the address specified is an INADDR_BROADCAST address, the
SO_BROADCAST socket option must be set and the process must
have OPER, SYSPRV, or BYPASS privilege for the I/O operation
to succeed.
A success return from sendmsg() does not guarantee that the data
has been received by the peer. All errors (except EWOULDBLOCK)
are detected locally. To determine when it is possible to send
more data, use the select() function.
Related Functions
See also read(), recv(), recvfrom(), recvmsg(), socket(), and
getsockopt().
5.73.3 – Return Values
n The number of bytes sent.
-1 Error; errno is set to indicate the error.
5.73.4 – Errors
ENOTSOCK The socket descriptor is invalid.
EFAULT An invalid user space address is specified for
an 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.
5.74 – 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 ); (_DECC_V4_SOURCE)
ssize_t sendto ( int s, const void *msg, size_t len, int
flags, const struct sockaddr *to, size_t tolen
); (not_DECC_V4_SOURCE)
5.74.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 the
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.
5.74.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.
Normally the sendto() function blocks if there is no space for
the incoming data in the buffer. It waits until the buffer space
becomes available. If the socket is set to nonblocking and there
is no space for the data, the sendto() function fails with the
EWOULDBLOCK error.
If the message is too large to be sent in one piece, and the
socket type is SOCK_DGRAM, which requires that messages be sent
in one piece, sendto() fails with the EMSGSIZE error.
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.
A success return from the sendto() does not guarantee that
the data has been received by the peer. All errors (except
EWOULDBLOCK) are detected locally. To determine when it is
possible to send more data, use the select() function.
Related Functions
See also read(), recv(), recvfrom(), recvmsg(), socket(), and
getsockopt().
5.74.3 – Return Values
n The number of bytes sent. This value normally
equals len.
-1 Error; errno is set to indicate the error.
5.74.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
an argument.
EHOSTUNREACH The destination host is unreachable.
EINTR A signal interrupted sendto() before any data
was transmitted.
EINVAL The tolen 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 resources 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.
5.75 – sethostent()
Opens the hosts database file.
Format
#include <netdb.h>
void sethostent (int stay_open);
5.75.1 – Argument
stay_open
Specifies a value used to indicate when to close the hosts
database file (TCPIP$ETC:IPNODES.DAT):
o A value of 0 closes the hosts database file after each call
to the gethostbyname(), gethostbyaddr(), or gethostent()
function.
o A nonzero value keeps the hosts database file open after each
call.
5.75.2 – Description
This function opens the hosts database file and resets the file
marker to the beginning of the file.
Passing a nonzero value to the stay_open argument keeps the
connection open until the endhostent() or exit() function is
called.
Related Functions
See also endhostent().
5.76 – setnetent()
Opens the networks database file.
Format
#include <netdb.h>
void setnetent (int stay_open);
5.76.1 – Argument
stay_open
Specifies a value used to indicate when to close the networks
database file (TCPIP$SYSTEM:NETWORKS.DAT):
o A value of 0 closes the networks database file after each call
to the getnetent() function.
o A nonzero value keeps the networks database file open after
each call.
5.76.2 – Description
This function opens the networks database file and resets the
file marker to the beginning of the file.
Passing a nonzero stay_open argument keeps the connection open
until you call the endnetent() or exit() function.
Related Functions
See also endnetent(), getnetent(), and exit().
5.77 – setprotoent()
Sets the state of the protocols table.
Format
#include <netdb.h>
void setprotoent (int stay_open);
5.77.1 – Argument
stay_open
Specifies a value used to indicate when to reset the protocols
table index:
o A value of 0 resets the protocols table index after each call
to the getprotoent function.
o A nonzero value does not reset the protocols table index after
each call.
5.77.2 – Description
This function sets the index marker to the beginning of the
protocols table.
Passing a nonzero stay_open argument will allow the index to
advance until you call the endprotoent() or exit() function.
Related Functions
See also endprotoent(), exit(), and getprotoent().
5.77.3 – Return Values
1 Indicates success.
0 Indicates an error; unable to access the
protocols table.
5.78 – setservent()
Opens the services database file.
Format
#include <netdb.h>
void setservent (int stay_open);
5.78.1 – Argument
stay_open
Specifies a value used to indicate when to close the services
database file (TCPIP$ETC:SERVICES.DAT):
o A value of 0 closes the services database file after each call
to the setservent() function.
o A nonzero value keeps the services database file open after
each call to setservent().
5.78.2 – Description
This function opens the services database file and resets the
file marker to the beginning of the file.
Passing a nonzero stay_open argument keeps the connection
open until you call the endservent() function or the exit()
function.
Related Functions
See also endservent(), exit(), and getservent().
5.79 – 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 ); (_DECC_V4_SOURCE)
int setsockopt ( int s, int level, int optname, const void
*optval, size_t optlen ); (not_DECC_V4_SOURCE)
5.79.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. For IPv4, see the IN.H
header file for the IPPROTO values. For IPv6,
see the IN6.H header file for the IPPROTO_IPV6
values.
optname
Interpreted by the protocol specified in level. Options at each
protocol level are documented with the protocol.
Refer to:
o Socket Options for a list of socket options
o TCP Protocol Options for a list of TCP options
o IP Protocol Options 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 is type SOCK_STREAM, which 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.
5.79.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 the level argument to the protocol number (IPPROTO_TCP)
of TCP.
For IPv4, see the IN.H header file for the various IPPROTO
values. For IPv6, see the IN6.H header file for the various
IPPROTO_IPV6 values.
5.79.3 – Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
5.79.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.
5.80 – 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) ;
5.80.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().
5.80.2 – Description
This function allows communications on a socket to be shut down
one direction at a time rather than all at once. You can use the
shutdown() function to shut down one direction in a full-duplex
(bidirectional) connection.
Related Functions
See also connect() and socket().
5.80.3 – Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
5.80.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.
5.81 – 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 );
5.81.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. Use one of the following:
o AF_INET for the IPv4 address family
o AF_INET6 for the IPv6 address family
o TCPIP$C_AUXS
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.
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 - Provides datagram transmissions. A datagram is a
connectionless, unreliable data transmission mechanism.
o SOCK_RAW - Provides access to internal network interfaces.
Available only to users with 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 address family.
5.81.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 (see linger
Structure).
Related Functions
See also accept(), bind(), connect(), getsockname(),
getsockopt(), socketpair(), listen(), read(), recv(),
recvfrom(), recvmsg(), select(), send(), sendmsg(), sendto(),
shutdown(), and write().
5.81.3 – Return Values
x A file descriptor that refers to the socket
descriptor.
-1 Error; errno is set to indicate the error.
5.81.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.
5.82 – socketpair()
Creates a pair of connected sockets.
Format
#include <sys/socket.h>
int socketpair (int domain, int type, int protocol, int
socket_vector[2]);
5.82.1 – Arguments
af
The address family in which the sockets are to be created. Use
one of the following:
o AF_INET for the IPv4 address family
o AF_INET6 for the IPv6 address family
o TCPIP$C_AUXS or a network application server with the LISTEN
flag enabled. Specify the TCPIP$C_AUXS address family to
obtain the connected device socket created by the auxiliary
server in response to incoming network traffic.
type
Specifies the type of sockets to be created. 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_SEQPACKET - Provides sequenced, reliable, bidirectional,
connection-mode transmission paths for records. A record can
be sent using one or more output operations and received using
one or more input operations, but a single operation never
transfers part of more than one record.
Use the MSG_EOR flag to determine the record boundaries.
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 address family.
If the protocol argument is 0, the function uses the default
protocol for the specified socket type.
If the protocol argument is non-zero, the function uses the
default protocol for the address family.
socket_vector
A 2-integer array to hold the file descriptors of the created
socket pair.
5.82.2 – Description
This function creates an unbound pair of connected sockets in a
specified address family, of a specified type, under the protocol
optionally specified by the protocol argument. The two sockets
will be identical. The file descriptors used in referencing the
created sockets are returned in socket_vector[0] and socket_
vector[1].
Appropriate privileges are required to use the socketpair()
function or to create some sockets.
Related Functions
See also socket().
5.82.3 – Return Values
0 Successful completion
-1 Error; errno is set to indicate the error.
5.82.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.
5.83 – 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 );
5.83.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.
5.83.2 – Description
This function attempts to write a buffer of data to a socket or
file.
Related Functions
See also socket().
5.83.3 – Return Values
x The number of bytes written to the socket or
file.
-1 Error; errno is set to indicate the error.
5.83.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() 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 file position pointer associated with
the d argument was a negative value.
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 the value of nbytes is outside
the specified minimum and maximum range, and
the minimum value is nonzero.
6 – System Services
System services routines let you write network applications. The
$QIO system service uses network pseudodevice and TELNET port
driver I/O function codes.
6.1 – $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 and I64 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.
6.1.1 – Arguments
devnam
OpenVMS usage:device_name
type: character-coded text string
access: read only
mechanism: (Alpha and I64) by 32- or 64-bit
descriptor-fixed-length string descriptor
(VAX) by 32-bit descriptor-fixed-length string
descriptor
Name of the device to which $ASSIGN is to assign a channel. The
devnam argument is the address 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: (Alpha and I64) by 32- or 64-bit reference
(VAX) by 32-bit reference
Number of the channel that is assigned. The chan argument is the
address 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 or 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: (Alpha and I64) by 32-bit or 64-bit
descriptor-fixed-length string descriptor
(VAX) by 32-bit descriptor-fixed-length string
descriptor
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.
6.1.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: network
pseudodevice, 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.
6.1.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$_NOPRIV The specified channel is not assigned or was
assigned from a more privileged access mode.
SS$_NOSUCHDEV The specified device does not exist.
6.2 – $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.
6.2.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.
6.2.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.
6.2.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.
6.3 – $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.
6.3.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.
6.3.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.
6.3.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.
6.4 – $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 and I64 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.
6.4.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 TELNET Port Driver I/O Function Codes.
iosb
OpenVMS usage:io_status_block
type: quadword (unsigned)
access: write only
mechanism: (Alpha and I64) by 32-bit reference or 64-bit
reference
(VAX) by 32-bit reference
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, HP 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
determine 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: (Alpha and I64) by 32- or 64-bit reference
(VAX) by 32-bit reference
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 and I64); longword
unsigned (VAX)
access: read only
mechanism: (Alpha and I64) by 32- or 64-bit value
(VAX) by 32-bit value
AST parameter to be passed to the AST service routine. On
Alpha and I64 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 and I64); longword
unsigned (VAX)
access: read only
mechanism: (Alpha and I64) by 32- or 64-bit reference or by
64-bit value depending on the I/O function
(VAX) by 32-bit reference or by 32-bit value
depending on the I/O function
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 Functions for descriptions of the network pseudodevice
driver I/O function codes.
6.4.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.)
6.4.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 I/O
function code in the remainder of this chapter.
6.4.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. See the following table for a list of the
basic I/O functions and their modifiers. The sections that follow
describe in greater detail the operation of these I/O functions.
The following table describes the 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
6.4.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 IP address. When using a connectionless protocol,
such as UDP, the IO$_ACCESS function sets the remote port number
and IP address.
For TCP, a connection request times out at a specified interval
(75 seconds is the default). This interval can be changed by
setting the inet subsystem parameter tcp_keepinit. The program
can also set a specific timeout interval for a socket that it has
created, as described in TCP Protocol Options.
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().
6.4.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 IP 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 IP address.
6.4.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.
6.4.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
HP 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 a process quota.
SS$_FILALRACC The specified socket name is already in use by
one of the following:
o On a raw socket, the remote IP address was
already specified on a previous IO$_ACCESS
call.
o On a datagram, the remote IP 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 IP address was not found, or an
invalid port number and IP 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.
6.4.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() .
6.4.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 IP 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 IP address of the new connection is written.
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.
6.4.4.2.2 – Function Modifiers
IO$M_EXTEND Allows the usage of BSD Version 4.4 formatted
socket address structures. Use this modifier
to operate in the IPv6 environment.
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.
6.4.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
HP 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 a process quota.
SS$_FILALRACC The specified socket name is already in use by
one of the following:
o On a raw socket, the remote IP address was
already specified on a previous IO$_ACCESS
call.
o On a datagram, the remote IP 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 IP address was not found, or an
invalid port number and IP 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.
6.4.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().
6.4.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 the first table below and a call code from
the second table.
The following table defines subfunction codes for network ACP
operations.
.
Subfunction Code Description
INETACP_FUNC$C_ Get the host name of the specified IP
GETHOSTBYADDR address from the hosts database.
INETACP_FUNC$C_ Get the IP address of the specified
GETHOSTBYNAME host from the hosts database.
INETACP_FUNC$C_ Get the network name of the specified
GETNETBYADDR IP address from the network database.
INETACP_FUNC$C_ Get the IP address of the specified
GETNETBYNAME network from the network database.
The following table defines call codes for network ACP
operations.
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 IP 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 hosts database for the host's
name. If a matching host name is not found in the local hosts
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 IP address, host name, network IP address,
or network name. The p2 argument is the address of a string
descriptor pointing to the input string. The input string must
be in an area of memory that is capable of being read and written
to.
All IP 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 of one of the following: host IP
address, host name, network IP address, or network name. All
IP 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 IP addresses returned by IO$_ACPCONTROL with a call code of
INETACP$C_TRANS are 32-bit values 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.
6.4.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 the call.
SS$_BUFFEROVF Programming error. There was not enough space
for returning all alias names in the call.
SS$_ENDOFFILE The information requested is not in the
database.
SS$_ILLCNTRFUNC Illegal function.
SS$_NOPRIV The privilege level was insufficient 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.
6.4.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 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 UNIX, 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().
6.4.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.
6.4.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.
6.4.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.
6.4.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 when one of the following occurs:
o There is no more data buffered in system space for this
socket.
o 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 when one of the
following occurs:
o All data from a record is transferred to the user buffer.
o 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 TCP/IP 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().
6.4.4.5.1 – Arguments
p1
OpenVMS usage:buffer
type: vector byte (unsigned)
access: read only
mechanism: (Alpha and I64) by 32- or 64-bit reference
(VAX) by 32-bit reference
The address 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:
access: quadword unsigned (Alpha and I64); longword
unsigned (VAX)
mechanism: read only
(Alpha and I64) by 64-bit value
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 IP 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 IP
address of the message source is written.
p4
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Longword of flags to specify attributes for the read operations.
The following table lists the available 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: (Alpha and I64) by 32- or 64-bit
descriptor-fixed-length descriptor
(VAX) by 32-bit descriptor-fixed-length descriptor
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 and I64 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.
6.4.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.
To operate in an IPv6 environment, you must
set the IO$M_EXTEND modifier.
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 an 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
character.
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 character 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.
6.4.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 TCP/IP
Services 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). For more information, see TCP
Protocol Options.
SS$_UNREACHABLE Communication status. The remote host or
network is unreachable.
6.4.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 I/O status block (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.
6.4.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 IP 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.
The equivalent Sockets API 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 IP address of the remote name associated with
the socket's peer. The p4 argument is the address of an item_
list_3 descriptor that points to the socket address structure
into which the peer name is written.
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 equivalent Sockets API functions are getsockopt() and
ioctl().
6.4.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.
Specify the IO$M_EXTEND modifier to operate in
an IPv6 environment.
6.4.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.
6.4.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 I/O status block (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.
6.4.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 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 IP protocol
The following table lists the valid 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_INET IPv4 Internet domain (default).
TCPIP$C_AF_ IPv6 Internet domain.
INET6
TCPIP$C_AUXS Accept hand-off of a socket already created and
initialized by the auxiliary server.
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 IP 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.
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.
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 equivalent Sockets API functions are setsockopt() and
ioctl().
6.4.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$_FILALRACC Programming error. The IP address is already
in use. An attempt to bind the socket to an
address and port failed.
SS$_ILLCNTRFUNC Programming error. 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 IP address you
specified using the IO$_SETMODE function was
not placed into the system. This resulted
in an invalid port number or IP address
combination. The IP address was invalid for
one of the following reasons:
o An attempt was made to exceed the limit
of allowable permanent entries in the ARP
table.
o An attempt was made to bind a raw IP socket
when there are no interfaces defined in the
system.
o An attempt was made to bind a raw IP socket
to a null Internet address.
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 was made to execute an I/O function
that needs the OPER privilege.
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 was made to broadcast an IP
datagram on a process without SYSPRV,
BYPASS, or OPER privilege.
o An attempt was made to use a reserved port
number lower than 1024.
o An attempt was made to access a process
that requires SYSPRV or BYPASS privilege.
o An attempt was made to use raw IP on a
privileged socket that requires the SYSPRV
or BYPASS privilege.
SS$_NOSUCHDEV Programming error or INET management error.
An attempt was made to show or delete an ARP
table entry failed because the IP address is
not found.
SS$_NOSUCHNODE Programming error or INET management error.
An attempt was made 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 The address family is unsupported for one
of the following reasons:
- An unsupported address family was
specified. Instead, specify the
address family (TCPIP$C_AF_INET,
TCPIP$C_AF_INET6, or TCPIP$C_UNSPEC).
- An unsupported address family for
the local IP address was specified.
Instead, specify the address family
(TCPIP$C_AF_INET or TCPIP$C_AF_INET6).
- An unsupported address family for
the IP address of the routing module
was specified. Instead, specify the
address family (TCPIP$C_AF_INET or
TCPIP$C_AF_INET6).
SS$_SHUT The local or remote node is no longer
accepting connections.
6.4.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.
6.4.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.
6.4.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 was made to execute an IO$_
SETMODE function (all functions except
socket creation) without specifying a
device socket. Instead, create a device
socket by issuing a $QIO with the IO$_
SETMODE function and correct parameters.
o A socket option was specified incorrectly.
SS$_DEVACTIVE INET management error. An attempt to change
the static parameters occurred. If new
parameters are needed, restart TCP/IP
Services.
SS$_DEVINTACT The network driver was not started.
SS$_DEVNOTMOUNT The network driver is loaded but the INET_ACP
is not currently available for use.
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$_FILALRACC Programming error. IP 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 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 The specified IP address was not found, or an
invalid port number and IP address combination
was specified. Port 0 is not allowed with this
function.
SS$_IVBUFLEN Programming error. The socket option buffer
has an invalid size.
SS$_NOLICENSE Programming or system management error. The
TCP/IP Services license is 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 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 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. The specified protocol type
is not supported.
SS$_SHUT The local or remote node is no longer
accepting connections.
6.4.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 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.
6.4.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 in which the AST is delivered.
6.4.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
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. An attempt to change a
static parameter was unsuccessful. If you need
new parameters, restart TCP/IP Services.
SS$_DEVINTACT The network driver was not started.
SS$_DEVNOTMOUNT The network driver is loaded but the INET_ACP
is not currently available for use.
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$_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 IP address
is not in the system, and an invalid port
number or an invalid IP address combination
was specified with an IO$_SETMODE function (a
bind).
o An attempt to bind the address failed
because the IP address is not in the
system, Port 0 and IP address 0 are not
allowed, or Port 0 is not allowed when
using an IO$_ACCESS function.
o An attempt was made 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. The
TCP/IP Services license is 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 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 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
Internet 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. The specified protocol type
is not supported.
SS$_SHUT The local or remote node is no longer
accepting connections.
6.4.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 TCP/IP management command SHOW DEVICE_SOCKET to
display information about the socket's characteristics, options,
and state.
6.4.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 in which the AST is delivered.
6.4.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 was made to execute the IO$_
SETMODE functions 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. You attempted to
change the static parameters. If you need
new parameters, restart TCP/IP Services.
SS$_DEVINTACT The network driver was not started.
SS$_DEVNOTMOUNT The network driver is loaded but the INET_ACP
is not currently available for use.
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$_FILALRACC Programming error. Because the IP 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. An attempt was made 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
IP 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 0 and IP
address 0 was specified.
o An attempt was made to make a permanent
entry in the ARP table and the operation
failed because of lack of space. There are
too many permanent entries.
o An attempt was made to bind a raw IP socket
when there were no interfaces defined in
the system.
o An attempt was made to bind a raw IP socket
to a null IP address.
SS$_IVBUFLEN Programming error. An invalid size was
specified for the socket option buffer.
SS$_NOLICENSE Programming or system management error. The
TCP/IP Services license is 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. The
operation failed for one of the following
reasons:
o An attempt was made to broadcast an IP
datagram for a process without having
SYSPRV, BYPASS, or OPER privilege.
o An attempt was made to use a reserved port
number lower than 1024.
o An attempt was made to access a process
without having SYSPRV or BYPASS privilege.
o An attempt was made to use raw IP on a
socket that is not a privileged socket. To
do this, the process must have SYSPRV or
BYPASS privilege.
SS$_NOSUCHDEV Programming error or INET management error.
An attempt was made to show or delete an
entry in the ARP table. However, because
the IP address was not in the ARP table, the
operation failed.
SS$_NOSUCHNODE Programming error or INET management error.
An attempt was made to delete a route from
the routing information table (RIT). However,
because the route was not found in the RIT,
the operation failed.
SS$_PROTOCOL Programming error. The specified protocol is
not supported.
SS$_SHUT The local or remote node is no longer
accepting connections.
6.4.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 connectionless-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().
6.4.4.11.1 – Arguments
p1
OpenVMS usage:buffer
type: vector byte (unsigned)
access: read only
mechanism: (Alpha and I64) by 32- or 64-bit reference
(VAX) by 32-bit reference
The address 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 and I64); longword
unsigned (VAX)
access: read only
mechanism: (Alpha and I64) by 64-bit value
(VAX) by 32-bit value
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 IP 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 IP 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: (Alpha and I64) by 32- or 64-bit
descriptor-fixed-length descriptor
(VAX) by 32-bit descriptor-fixed-length descriptor
Input buffer list describing one or more buffers containing
the data to be transmitted. The p5 argument is the address
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.
6.4.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.
6.4.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. An I/O operation 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
is 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 IP 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 socket address
with an IO$_WRITEVBLK function, while an
IP address was already specified with an
IO$_ACCESS function.
o UDP/IP protocol. An attempt was made to
specify a remote socket address with an
IO$_WRITEVBLK function, while an IP address
was already specified with the IO$_ACCESS
function.
SS$_ILLCNTRFUNC Programming error. Unsupported operation on
the protocol (UDP or TCP).
SS$_INSFMEM Insufficient system dynamic memory to complete
the operation.
SS$_IVADDR Programming error. The specified IP address is
not in the system, and an invalid port number
or an IP 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 0 and IP address 0 are not
allowed, or Port 0 is not allowed with an
IO$_WRITEVBLK function.
o An attempt to get an interface IP 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 address specified with an IO$_WRITEVBLK
function is not supported (UDP or TCP).
The address family should be either the
TCPIP$C_AF_INET or the TCPIP$C_AF_INET6
address family.
SS$_NOLINKS Programming error. The socket was not
connected (TCP), or an INET port and address
were not specified with an IO$_ACCESS (UDP).
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).
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).
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 or raw IP
socket is larger than the socket buffer
high water allows. For more information,
see IOCTL Requests.
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.
This indicates a 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.
6.4.5 – TELNET Port Driver $QIO Interface
The TELNET port driver (TNDRIVER) provides terminal session
support for TCP streaming 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.
6.4.5.1 – Interface Definition
The following definitions are used by the interface. The symbols
are defined in SYS$LIBRARY:TNIODEF.H.
6.4.5.1.1 – Item List Codes
The following table describes the symbols used with the p5
parameter.
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 for a table that describes the
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 the table in
Protocol Types.)
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 the
table in Service Types.)
TN$_STATUS 4 Current device and session status.
This item is read only.
6.4.5.1.2 – Characteristic Mask Bits
The following table describes the characteristic mask bits used
with the p5 parameter.
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.
6.4.5.1.3 – Protocol Types
The following table describes the protocol types used with the p5
parameter.
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.
6.4.5.1.4 – Service Types
The following table describes the service type codes used with
the p5 parameter.
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
6.4.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.
6.4.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.
6.4.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 the table in Item List Codes under
Interface Definition help for possible values.
6.4.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.
6.4.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 network is not
available.
6.4.7 – IO$_TTY_PORT|IO$M_TN_SHUTDOWN
Unbind socket from a TELNET terminal.
This subfunction will unbind a previously bound socket-terminal
connection.
6.4.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.
6.4.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.
6.4.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.
6.4.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.
6.4.7.5 – IO$_TTY_PORT_BUFIO|IO$M_TN_SENSEMODE
Read device parameters.
6.4.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.
6.4.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.
6.4.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.
6.4.7.6 – IO$_TTY_PORT_BUFIO|IO$M_TN_SETMODE
Write device parameters.
6.4.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.
6.4.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.
6.4.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.