prcmd.3n (2010 09)

p
prcmd(3N) prcmd(3N)
(remshd) failure, including access denial; and to an improper connection attempt
on the standard error port.
The calling program should check the host’s
prc_errmsg field. If it is not a null
pointer, message text is available from the remote
remshd command; and the cal-
ling program must
free() the pointer when done using the value.
PRC_CONN_TIMEOUT •
Connection timed out. The connection has remained in one of the
PRC_CONN1_WAIT
, PRC_CONN2_WAIT
,orPRC_CONN3_WAIT
states for more
than timeout seconds without becoming ready for I/O.
If the calling program performs unbuffered I/O using socket (file) descriptors instead of streams, it can
refer to
fileno(prc_fp)
(see fileno (3S)).
If the calling program needs to send a signal to a remote command, it can write the signal number to the
file specified by
prc_fp2 (see rcmd(3N)).
There is no way to tell
prcmd()
to close down all connections, except by setting prc_conn_close
for
all hosts, and calling
prcmd() once more. This causes
prc_conn_status to be set to
PRC_CONN_DONE
.
Regarding Timeouts
prcmd() is designed to maximize the number of parallel connections, and to maximize control by the
calling program. Therefore prcmd() always calls select() with a timeout value of zero (immediate
polling). It is the responsibility of the calling program to avoid calling
prcmd() more frequently than is
necessary (therefore consuming excessive CPU time). For example, the calling program might call
sleep(1) (see sleep (3C)) between prcmd() calls. Note: This is unnecessary if the calling program is
itself periodically invoked by timer interrupts, or if it performs other (time-consuming) tasks between
prcmd() calls.
A timeout will occur if the host’s connection remains in one of the wait states,
PRC_CONN1_WAIT,
PRC_CONN2_WAIT,or
PRC_CONN3_WAIT, for more than timeout seconds without becoming ready for
I/O, and no untried IP addresses for this host remain. When a host’s connection reaches
PRC_READ_WAIT state the first time,
prcmd() resets the host’s prc_conn_time field but does not
check the host again for timeout. The calling program can do this if desired. The calling program is also
permitted to reset (update) the
prc_conn_time
field as the communications proceed (for example,
each time it writes data to the remote command).
RETURN VALUE
PRC_OK Call succeeded; check the host list for prc_prev_status
and
prc_conn_status field values. If
select() fails with [EINTR] (due to a
signal arriving),
prcmd() returns control to the calling program with
PRC_OK. In this case some connections might have been started (entered the
PRC_CONN1_WAIT state) or stopped (entered the
PRC_CONN_DONE state),
under the calling program’s control, but none has advanced due to I/O status;
call
prcmd() again as usual.
PRC_ERR_NETWORKING A socket() call failed due to any of a number of serious networking prob-
lems (see earlier list), indicating the local host’s networking is not enabled,
and prcmd() is useless; errno is set on return from prcmd().
PRC_ERR_NOFILE A socket() call failed with [EMFILE] or [ENFILE], or there were no more
available reserved ports, at a time when prcmd() had no open connections
(sockets). This means further attempts to open connections are futile until the
calling program, or the system, frees some file descriptors, or reserved ports.
PRC_ERR_RCMD Unable to get the "shell" service port number or the username for the effective
user ID. It’s not useful to call prcmd() again unless this condition is
corrected.
PRC_ERR_SELECT A select() call failed (other than with [EINTR]); errno is set on return
from prcmd(). The data in the host list is valid but no hosts are read-ready
or write-ready, even if marked PRC_READ_READY from a previous successful
call.
6 Hewlett-Packard Company − 6 − HP-UX 11i Version 3: September 2010