HP-UX Reference (11i v2 04/09) - 3 Library Functions N-Z (vol 7)

p
prcmd(3N) prcmd(3N)
PRC_ERR_SELECT /* select() failed */
PRC_CSBIT_ERR /* connection has errored out */
PRC_CONN_NONE /* needs connection */
PRC_CONN1_WAIT /* waiting for stdio connect() */
PRC_CONN2_WAIT /* waiting for stderr connect() */
PRC_CONN3_WAIT /* waiting for remshd reply */
PRC_READ_WAIT /* waiting for data */
PRC_READ_READY /* data is ready to read */
PRC_CONN_DONE /* connection closed */
PRC_CONN_NO_IPS /* can’t get IP addresses */
PRC_CONN_FAILED /* various causes */
PRC_CONN_REFUSED /* by remote system */
PRC_CONN_TIMEOUT /* during connection attempt */
typedef struct prc_host *prcp_t;
#define PRC_NULLP ((prcp_t) 0)
#define PRC_SIZE (sizeof (struct prc_host))
Data Initialization
The program calling
prcmd() should create an array of prc_host structures with one node for each
target system. It should then call prcmd_init() using that array (hostp ) and its size (num_hosts ), a
desired initial value (caller_status) for each host’s
prc_caller_status field, a command to be exe-
cuted when initiating a remote connection to a host, and a timeout value to apply to each host during
setup of its connection. This call sets the values of most fields for each host. The calling program can
change each host’s value for
prc_caller_status
, but normally they are all initialized to the same
value.
Finally, initialize the following field in each array element before the first call to
prcmd():
prc_hostid
Either a system name (with or without domain suffix) or an Internet address in dot notation.
This value differs for each host; it’s easier for the calling program to set the values directly
than to pass a list into prcmd_init().
This value is a pointer to memory allocated by the calling program. Avoid destroying the
underlying data until
prcmd() establishes a connection to the host. After that, it no
longer needs prc_hostid.
Like
rcmd(), prcmd() does name lookup on host names to get internet addresses; but
unlike rcmd(), it does not modify the calling program’s
prc_hostid values.
Common Error Handling
Each time
prcmd() is called, it scans the host list looking for actions to take based on each host’s
prc_conn_close field and its prc_conn_status field, as described below. Errors are generally
handled as follows:
Failure If any system call fails while working on a given host’s connection, except as noted below,
prcmd() sets that host’s prc_conn_status field to PRC_CONN_FAILED
, sets its
prc_errno to the returned errno value from the failed call, and closes all file (socket)
descriptors, and stream pointers (if any), that are associated with the host.
Refusal If any failure occurs on the remote (
remshd) side of a connection, as described below, or if an
invalid attempt is made to connect back to a host’s standard error port, prcmd() sets
prc_conn_status to PRC_CONN_REFUSED and closes the files specified by the host’s
prc_fp and prc_fp2 fields. If any message is available from the remote remshd (up to a
limit of BUFSIZ-1 characters) and malloc() succeeds, prcmd() saves the message text in
a location pointed to by the prc_errmsg field; otherwise that field remains a null pointer. If
instead the refusal occurs for "local" reasons and an errno value is available, prcmd() sets
prc_errno to that value, otherwise to 0.
Timeout A connection times out when it is in
PRC_CONN1_WAIT, PRC_CONN2_WAIT,or
PRC_CONN3_WAIT state (see below), select() reports that the host is not ready for I/O,
and at least timeout seconds have elapsed since the host entered that state. The test is low-
HP-UX 11i Version 2: September 2004 − 2 − Hewlett-Packard Company Section 3−−729