HPUX ipcselect[2]
ipcselect(2) ipcselect(2)
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:
o Whether any of the referenced sockets are readable. A VC
socket is considered readable if it can immediately satisfy an
ipcrecv() (see 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() (see ipccontrol(2)). Read selecting on a
call socket has no meaning and should be avoided.
o Whether any of the referenced sockets are writeable. A VC
socket is considered writeable if it can immediately
accommodate an ipcsend() (see 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(). Write
selecting on a call socket has no meaning and should be
avoided.
o 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() can succeed).
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 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
Hewlett-Packard Company - 1 - HP-UX Release 9.0: August 1992
ipcselect(2) ipcselect(2)
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 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
timeout 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() request, and which of its call sockets can
accommodate a new ipcconnect() request (see ipcsend(2) and
ipcconnect(2)). 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
Hewlett-Packard Company - 2 - HP-UX Release 9.0: August 1992
ipcselect(2) ipcselect(2)
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(), but cannot 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 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() 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
Hewlett-Packard Company - 3 - HP-UX Release 9.0: August 1992
ipcselect(2) ipcselect(2)
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 ERRORS 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.
ERRORS
[NSR_BOUNDS_VIO] One of the pointer arguments is invalid.
[NSR_DESC] A socket descriptor specified in a
bitmap is not valid.
Hewlett-Packard Company - 4 - HP-UX Release 9.0: August 1992
ipcselect(2) ipcselect(2)
[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.
SEE ALSO
getrlimit(2), ipcconnect(2), ipccontrol(2), ipccreate(2), ipcdest(2),
ipcgetnodename(2), ipclookup(2), ipcname(2), ipcnamerase(2),
ipcrecv(2), ipcrecvcn(2), ipcsend(2), ipcsetnodename(2),
ipcshutdown(2), addopt(3N), initopt(3N), ipcerrmsg(3N),
optoverhead(3N), readopt(3N).
Hewlett-Packard Company - 5 - HP-UX Release 9.0: August 1992