Series 300 and 800 Only

NAME

ipcselect() − determines the status of a call socket or VC socket

SYNOPSIS

#include <sys/ns_ipc.h>

void ipcselect (sdbound,readmap,writemap,exceptionmap,timeout,
                result);
ns_int_t *sdbound,timeout,*result;
int readmap[2],writemap[2],exceptionmap[2];

DESCRIPTION

ipcselect permits a process to detect, and/or wait for, the occurrence of any of several events across any of several sockets.  Compared to the telephone system, invoking ipcselect is analogous to performing powerful "switchboard-like" operations because it enables a process to act as a "switchboard operator" by monitoring the sockets, or "telephones," that it owns.  A process should call ipcselect with map elements set for descriptors that it owns.  If a process attempts to perform a select on a closed or invalid descriptor, an error will be returned.  Performing a select on a destination descriptor is meaningless. 
 
ipcselect reports three types of information:
 
(1) Whether any of the referenced VC sockets are readable.  A VC socket is considered readable if it can immediately satisfy an ipcrecv request for a number of bytes greater than or equal to its read threshold.  Each VC socket has an associated read threshold which, when the socket is first created, is set to one byte.  This value can be modified by calling ipccontrol.  Read selecting on call sockets has no meaning.  Although doing so will not produce an error, this practice should be avoided. 
 
(2) Whether any of the referenced call or VC sockets are writeable. A VC socket is considered writeable if it can immediately accommodate an ipcsend request that involves a number of bytes greater than or equal to the socket’s write threshold.  Each VC socket has an associated write threshold which, when the socket is first created, is set to one byte.  This value may be modified by calling ipccontrol. 
 
(3) Whether any of the referenced call or VC sockets are exceptional. A VC socket is considered exceptional if it has a problem associated with it (for example, the connection it references was aborted).  A call socket is considered exceptional if it has a connection request queued on it or if it can no longer be supported by NetIPC.
 
When a socket is shared (i.e., more than one process has a descriptor for the same socket), an ipcsend call may return an NSR_WOULD_BLOCK error (code 56) even if a previous ipcselect call indicated that the socket was writeable.  For example, this would occur if another process (with a descriptor for the same socket) called ipcsend after the original process called ipcselect and before it called ipcsend. 
 
The following are examples of read selecting, write selecting, and exception selecting using ipcselect. 
 
Detecting Connection Requests.  By setting bits in the exceptionmap parameter, a process can determine if incoming connection requests are queued to certain call sockets.  Consider the following example:  Process A must determine whether certain call sockets have received connection requests.  To do this, Process A calls ipcselect with the exceptionmap map elements set to correspond to these sockets.  Assuming that the time-out interval is long enough (set by the timeout parameter), ipcselect will complete after at least one connection request has arrived and has been queued on one of the sockets specified in exceptionmap.  When the call completes, only those elements that correspond to sockets that have queued connection requests remain set; the other elements will have been cleared. 
 
Performing a Read Select.  By setting elements in the readmap parameter, a process can determine whether certain VC sockets are readable.  Consider the following example: Process A must determine which of its VC sockets have data queued to them.  To do this Process A performs a read select on those sockets by setting elements in the readmap parameter to correspond with the desired VC sockets.  Upon completion of the call, only the elements that represent readable sockets will remain set; the other elements will have been cleared.  Process A can call ipcselect with a zero-length time-out to determine the status of a socket immediately, or with a non-zero timeout if it is willing to wait for some data to arrive. 
 
Performing a Write Select.  By setting bits in the writemap parameter, a process can determine whether certain VC sockets are writeable.  Consider the following example: Process A must determine which of its VC sockets can accommodate a new ipcsend request, and which of its call sockets can accommodate a new ipcconnect request.  To do this, it can perform a write select on these sockets by setting elements in the writemap parameter to correspond with the desired VC and call sockets.  Upon completion of the call, only the elements that represent writeable sockets will remain set; the other elements will have been cleared.  Process A can call ipcselect with a zero-length timeout to determine the status of a socket immediately, or with a non-zero timeout if it is willing to wait before sending data on the connection. 
 
Exception Selecting.  By setting bits in the exceptionmap parameter, a process can determine whether certain connections have been aborted.  VC sockets that reference aborted connections will always exception select as "true" (their elements will be set when the call completes).  Exception selecting on VC sockets can also be useful when the connection associated with the socket is not fully established.  Consider the following example: Process B has successfully created a VC socket via a call to ipcconnect, but will not know whether the connection associated with the socket is established until it calls ipcrecv.  If Process B calls ipcrecv before the connection is established, or before it becomes known that the connection cannot be established, it will block if the VC socket is in synchronous mode, or return a NSR_WOULD_BLOCK (code 56) error if the VC socket is in asynchronous mode.  Process B can avoid blocking, in the synchronous case, or polling, in the asynchronous case, by performing an exception select on the new VC socket.  The socket will select as true if the connection has been established (a call to ipcrecv will be successful), or if there is a problem associated with it (a call to ipcrecv will be unsuccessful). 
 
This routine can be linked into a program by giving the -lnsipc option to cc(1) or ld(1). 

PARAMETERS

sdbound (input/output parameter) Specifies the upper ordinal bound on the range of descriptors specified in the readmap, writemap and exceptionmap parameters.  An ipcselect call will be most efficient if this parameter is set to the maximum ordinal value of the sockets specified in these parameters.  Because a NetIPC process may have concurrent access to a maximum of 60 descriptors (descriptors 0 through 59), sdbound may be given a maximum value of 60.  As an output parameter, sdbound contains the upper ordinal boundary of all of the descriptors that met the select criteria. 

readmap (input/output parameter) A bit map indexed by VC socket descriptors.  When readmap is an input parameter, this map should have elements set for all of the VC sockets from which you would like to receive data.  As an output parameter, readmap is a map describing all of the read-selected VC sockets that are readable. 

writemap (input/output parameter) A bit map indexed by VC socket descriptors.  When writemap is an input parameter, this map should have elements set for all of the VC sockets to which you would like to send data.  As an output parameter, writemap is a map describing all of the write-selected sockets that are writeable. 

exceptionmap (input/output parameter) A bit map indexed by either call socket descriptors or VC socket descriptors.  When exceptionmap is an input parameter, this map should have elements set for all of the sockets for which notification of exceptional conditions is desired.  As an output parameter, exceptionmap is a map describing all of the exception-selected sockets that are exceptional.  For call sockets, an exceptional condition is present if a connection request is queued to the socket; for VC sockets, an exceptional condition is present if the connection referenced by the socket has been aborted. 

timeout (input parameter) The number of tenths of seconds the calling process will wait for some event to occur which would cause ipcselect’s report to change.  This time-out is put into effect only when none of the sockets referenced can immediately satisfy the select criteria (i.e., none are readable, writeable or exceptional).  Valid values are zero, -1, or any positive integer.  If timeout is set to zero, the call will not block.  If timeout is set to -1, the call will block until some event occurs.  NOTE: Do not set timeout to -1 if no bits are set in any of the bit maps as ipcselect will block indefinitely. 

result (output parameter) The error code returned; zero or NSR_NO_ERROR if no error.  Refer to "Diagnostics" below for more information. 

AUTHOR

HP. 

EXAMPLES

In the C programming language, the readmap, writemap and exceptionmap parameters can be declared as integer arrays with two elements.  This creates parameters with 62 bits, 60 of which can be set to correspond to specific call or VC socket descriptors.  The following algorithm can be used to set bits in the array.  (The socket descriptor is represented by the variable vcdesc.) 
 
    read_map [vcdesc/32] |= ((unsigned int) 0x80000000 >> (vcdesc % 32));
 
The next algorithm can be used after an ipcselect call completes to check whether or not a certain bit is set:
 
    read_map [vcdesc/32] & ((unsigned int) 0x80000000 >> (vcdesc % 32));
 
Refer to the NetIPC programming manual for your system for examples of these parameters in the Pascal and Fortran programming languages.

RETURN VALUE

None.  Errors are returned in the result parameter. 

SEE ALSO

ipcsend(2), ipcrecv(2), ipcconnect(2). 

DIAGNOSTICS

[NSR_NO_ERROR] The call was successful. 

[NSR_xxxx] Refer to the errors listed in the NetIPC programmer’s manual for your system. 

Hewlett-Packard Company  —  May 11, 2021