prcmd.3n (2010 09)

p
prcmd(3N) prcmd(3N)
1. calling program communicates first
2. remote command communicates first
If the calling program communicates first, it must use the
prc_caller_status
field, or other means,
to remember whether or not it has sent initial data to the command; and it must send that data upon the
host entering the
PRC_READ_WAIT
state the first time. If the command communicates first, or in any
conversation after the calling program sends initial data, the calling program must "track" the conversa-
tion to know when to send more data, if any, and when to close the conversation by setting
prc_conn_close
.
Before the calling program can send the next input, or close the connection, it might have to wait through
a series of
PRC_READ_WAIT
and PRC_READ_READY
states (until all bytes of a single response from a
command are received).
After each
prcmd() call, the calling program should check the return value for a serious error. If the
return value is PRC_OK, the calling program should next scan the hostp array and check
prc_prev_status
(if desired) and prc_conn_status
fields for each host. The calling program
only needs to take action for certain status values (marked with • below).
PRC_CONN_NONE
After the first prcmd() call: Indicates the process ran out of socket (file) descrip-
tors, or reserved ports, after making at least one (still open) connection (in this call,
or in a previous call). Connection to this host is attempted again on the next call.
The calling program can increase the number of available file descriptors (by closing
files or calling
rlimit()), or wait for existing connections to finish their communi-
cations.
PRC_CONN1_WAIT
PRC_CONN2_WAIT
PRC_CONN3_WAIT These are internal states of little interest to the calling program. No action is
needed except to call prcmd() again later. If (prc_prev_status !=
prc_conn_status)
, the calling program might log/display the host’s new status.
PRC_READ_WAIT •
Command is running but has not yet produced output. If the calling program com-
municates first, meaning the command needs some initial input, write it to the file
specified by prc_fp and remember that this was done, probably by using the
prc_caller_status
field. Otherwise no action is required, except maybe to
log/display the connection’s status.
PRC_READ_READY •
Command produced output that is ready for reading. After reading the output, if
the command needs more input, write it now to the file specified by
prc_fp.If
instead the conversation is done, set the
prc_conn_close
field non-zero.
PRC_CONN_DONE Command is done; connection was closed in response to the calling program setting
the
prc_conn_close field. No action is required.
The calling program can use
(prc_conn_status & PRC_CSBIT_ERR)
to quickly detect any error
status. It can use
(prc_prev_status != prc_conn_status)
to detect that any failure condition
is new so it is only handled once, or use
prc_caller_status to record that it was processed the first
time it appears in a return from prcmd(). In each case the calling program should handle or report the
error as desired.
PRC_CONN_NO_IPS •
The prc_hostid field appears to be a name, not an address, and gethost-
byname() fails for it, or inet_addr() fails on a numeric prc_hostid value.
The remaining conditions only refer to the cause of failure on the last of the host’s IP addresses, if it has
more than one.
PRC_CONN_FAILED •
Connection could not be initiated for some reason (on any of the host’s IP addresses)
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
HP-UX 11i Version 3: September 2010 − 5 − Hewlett-Packard Company 5