ipcselect(2)

Requires Optional LAN/X.25 Software

NAME

ipcselect − determine status of NetIPC socket

SYNOPSIS

#include <sys/ns_ipc.h>

void ipcselect(

ns_int_t ∗sdbound,
int readmap[],
int writemap[],
int exceptionmap[],
ns_int_t timeout,
ns_int_t ∗result);

DESCRIPTION

ipcselect enables a process to detect and/or wait for the occurrence of any of several events across any of several sockets. 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 is returned. Performing a select on a destination descriptor has no meaning and should be avoided.

ipcselect reports three types of information:

• Whether any of the referenced sockets are readable. A VC socket is considered readable if it can immediately satisfy an ipcrecv(2) request for a number of bytes greater than or equal to its read threshold. The read threshold is one byte by default and can be modified by calling ipccontrol(2). Read selecting on a call socket has no meaning and should be avoided.

• Whether any of the referenced sockets are writeable. A VC socket is considered writeable if it can immediately accommodate an ipcsend(2) request that involves a number of bytes greater than or equal to the socket’s write threshold. The write threshold is one byte by default and can be modified by calling ipccontrol(2). Write selecting on a call socket has no meaning and should be avoided.

• Whether any of the referenced sockets are exceptional. A VC socket is exceptional if it is not connected. A call socket is exceptional if it has a connection queued on it (i.e., if a subsequent call to ipcrecvcn(2) can succeed).

When a socket is shared (i.e., more than one process has a descriptor for the same socket), an ipcsend(2) call may return an NSR_WOULD_BLOCK error 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(2) after the original process called ipcselect and before it called ipcsend(2).

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 whether incoming connection requests are queued to certain call sockets. For 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 timeout parameter), ipcselect completes after at least one connection has been established and has been queued on one of the sockets specified in exceptionmap. When the call completes, only those elements remain set that correspond to sockets which have queued connections; 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. For 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 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 for data to arrive.

Performing a Write Select
By setting bits in the writemap parameter, a process can determine whether certain VC sockets are writeable. For example: Process A must determine which of its VC sockets can accommodate a new ipcsend(2) request, and which of its call sockets can accommodate a new ipcconnect(2) 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 always exception select as "true" (their elements are 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. For example: Process B has successfully created a VC socket via a call to ipcconnect(2), but cannot know whether the connection associated with the socket is established until it calls ipcrecv(2). If Process calls ipcrecv(2) 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 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 selects as true if the connection has become "established" but ipcrecv(2) has not yet been called or if the attempt to connect has failed.

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 is most efficient if sdbound is set to the ordinal value of the highest-numbered socket descriptor specified in the map parameters. As an output parameter, sdbound contains the upper ordinal boundary of all of the descriptors that met the select criteria. The maximum number of file and socket descriptors that a process can open at a time is a system-defined number (see getrlimit(2)).

readmap (input/output parameter) A bit map indexed with NetIPC socket descriptors. On input, this parameter specifies the socket descriptors to be examined for readability. If zero is passed, no sockets are examined. On output, readmap describes all readable sockets. Readability is described above.

writemap (input/output parameter) A bit map indexed with NetIPC socket descriptors. On input, this parameter specifies the socket descriptors to be examined for writeability. If zero is passed, no sockets will be examined. On output, writemap describes all writeable sockets. Writeablity is described above.

exceptionmap (input/output parameter) A bit map indexed with NetIPC sockets descriptors. On input, this parameter specifies the socket descriptors to be examined for exceptions. If zero is passed, no sockets will be examined. On output, exceptionmap describes all exceptional sockets. Exception conditions are described above.

timeout (input parameter) The number of tenths of seconds to wait. If no sockets are selectable, ipcselect blocks for this amount of time. 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 blocks until some event occurs. NOTE: If timeout is set to −1 and no bits are set in any of the bit maps, ipcselect blocks indefinitely.

result (output parameter) The error code returned. Refer to DIAGNOSTICS below for more information.

EXAMPLES

In the C programming language, the readmap, writemap, and exceptionmap parameters can be declared as int arrays. The size of the map arrays must be large enough to accommodate sdbound+1 bits. Thus, each map array must contain at least the following number of elements (where BITS_PER_INT is the number of bits in an int variable):

(sdbound + BITS_PER_INT) / BITS_PER_INT

The bits can be set to correspond to specific call or VC socket descriptors in the appropriate map parameter. The following example can be used to set a bit in the array. (The socket descriptor is represented by the variable sd, and the number of bits in an int variable is 32.)

readmap[sd/32] |= (unsigned)0x80000000 >> (sd % 32);

The next example can be used after an ipcselect call completes to check whether or not a certain bit is set:

readmap[sd/32] & ((unsigned)0x80000000 >> (sd % 32))

RETURN VALUE

None. Errors are returned in the result parameter.

DIAGNOSTICS

[NSR_BOUNDS_VIO] One of the pointer arguments is invalid.

[NSR_DESC] A socket descriptor specified in a bitmap is not valid.

[NSR_NO_ERROR] No error occured.

[NSR_SIGNAL_INDICATION] A signal caused the call to abort.

[NSR_SOCKET_TIMEOUT] The timer expired before an exception was detected.

[NSR_TIMEOUT_VALUE] The value specified in the timeout parameter is invalid.

AUTHOR

ipcselect was developed by HP.

Museum

Related Articles