HP-UX Reference (11i v3 07/02) - 3 Library Functions N-Z (vol 7)

p
prcmd(3N) prcmd(3N)
due to failure on the local system.
prc_errno is set to the errno value from a
failed system call.
PRC_CONN_REFUSED •
Connection refused. Per errno(2): "This usually results from trying to connect to a
service that is inactive on the foreign host." It can also be due to any other remote
(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 cal-
ling program. Therefore prcmd() always calls select() with a timeout value of zero (immediate pol-
ling). 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,orPRC_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 problems
(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.
130 Hewlett-Packard Company − 6 − HP-UX 11i Version 3: February 2007