prcmd.3n (2010 09)

ManualsBrandsHP ManualsSoftwareHP-UX Manpages

prcmd(3N) prcmd(3N)

NAME

prcmd - return streams to parallel remote commands

SYNOPSIS

#include <prcmd.h>

void prcmd_init (

struct prc_host *hostp,

int num_hosts,

int caller_status,

char *command,

time_t timeout

);

int prcmd (

struct prc_host *hostp,

int num_hosts

);

Remarks

These functions reside in libdc, and are linked using the

-ldc option to the ld or cc command.

DESCRIPTION

prcmd() is an interface similar to rcmd() that allows a client-side calling program to use an existing

rcmd() server side daemon. prcmd(), however, performs in parallel across multiple systems, the time

consuming steps associated with executing commands remotely (connection, command invocation, and

command execution/interaction). With

rcmd(), only command execution and interaction is under the

control of the calling program, and it requires the calling program to perform its own

select()

calls in

order to manage multiple (parallel) connections.

Features of the existing server-side remote-shell daemon (

remshd) include: well known service, access

control, and shell processing of the command line.

The calling program passes

prcmd() a pointer (hostp ) to the ﬁrst node in a list of hosts for which to ini-

tiate, or continue, remote command processing via Internet socket connections. It also supplies the

number of hosts in the list (num_hosts ).

The calling program makes repeated calls to

prcmd() to advance the status of the host connections.

Each call to prcmd() causes a single call of select() to check the status of all connections that

require checking (if there are any). Once a connection (to a remote command) is ready for reading, the

calling program can read data from it, optionally write data to it, and then wait for more data to be ready

to read back from it.

Header File

The

<prcmd.h> header ﬁle deﬁnes a prc_host structure containing the following ﬁelds of interest:

char *prc_hostid; /* host name or IP address */

int prc_prev_status; /* previous connection status */

int prc_conn_status; /* connection status */

time_t prc_conn_time; /* time of connection */

int prc_errno; /* for failed connections */

char *prc_errmsg; /* string from remshd */

FILE *prc_fp; /* file ptr to stdin/stdout */

FILE *prc_fp2; /* file pointer to stderr */

int prc_conn_close; /* flag: close connection */

int prc_caller_status; /* caller’s info about conn */

The calling program should change only the

prc_hostid, prc_conn_close,

prc_caller_status, and possibly prc_conn_time ﬁelds, as explained below. The other ﬁelds

should be considered read-only.

The header ﬁle also deﬁnes the following macros of interest:

PRC_OK /* function succeeded, check entries */

PRC_ERR_NETWORKING /* no networking on calling program’s system */

PRC_ERR_NOFILE /* cannot get even one file descriptor */

PRC_ERR_RCMD /* cannot get ‘‘shell’’ service num/etc. */

HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1

Summary of content (8 pages)

PAGE 1
prcmd(3N) prcmd(3N) NAME prcmd - return streams to parallel remote commands SYNOPSIS #include void prcmd_init ( struct prc_host *hostp, int num_hosts, int caller_status, char *command, time_t timeout ); int prcmd ( struct prc_host *hostp, int num_hosts ); Remarks These functions reside in libdc, and are linked using the -ldc option to the ld or cc command.
PAGE 2
prcmd(3N) prcmd(3N) PRC_ERR_SELECT /* select() failed */ PRC_CSBIT_ERR /* connection has errored out */ PRC_CONN_NONE PRC_CONN1_WAIT PRC_CONN2_WAIT PRC_CONN3_WAIT PRC_READ_WAIT PRC_READ_READY PRC_CONN_DONE PRC_CONN_NO_IPS PRC_CONN_FAILED PRC_CONN_REFUSED PRC_CONN_TIMEOUT /* /* /* /* /* /* /* /* /* /* /* */ */ */ */ */ */ */ */ */ */ */ needs connection waiting for stdio connect() waiting for stderr connect() waiting for remshd reply waiting for data data is ready to read connection closed can’t g
PAGE 3
prcmd(3N) prcmd(3N) precision, to the second, using time(). In this case, prcmd() sets the prc_conn_status field for the host to PRC_CONN_TIMEOUT, and closes the files specified by the host’s prc_fp and prc_fp2 fields. A host specified by name can be listed with multiple IP addresses in the hosts database.
PAGE 4
prcmd(3N) prcmd(3N) prc_conn_status field is left unchanged. When the standard error connection is ready for reading, prcmd() does an accept() on it, closes the old prc_fp2 and revises the value to a new file prc_conn_status pointer for the new socket/fd, changes to PRC_CONN3_WAIT, and sets prc_conn_time to the current system clock in seconds. If only the stdout connection is ready for reading, this indicates a remshd failure.
PAGE 5
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.
PAGE 6
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 calling program must free() the pointer when done using the value. PRC_CONN_TIMEOUT • Connection timed out.
PAGE 7
prcmd(3N) prcmd(3N) DIAGNOSTICS Unlike rcmd(), prcmd() does not copy messages from remshd to the local standard error when remshd fails. It just puts the host in PRC_CONN_REFUSED state. EXAMPLES The following code fragment illustrates how to allocate and initialize an array of hosts, and call prcmd() once for the entire list of hosts: int index; struct prc_host prc_host [MAXHOSTS]; prcmd_init (prc_host, argc, 0, REMCMD, TIMEOUT); for (index = 0; index < argc; ++index) (prc_host[index].
PAGE 8
prcmd(3N) prcmd(3N) to complete increases accordingly. To improve performance, it might be necessary to increase the limit on open files if there are a lot of hosts; see setrlimit (2). AUTHOR prcmd() was developed by Hewlett-Packard. SEE ALSO remshd(1M), accept(2), bind(2), connect(2), errno(2), fcntl(2), read(2), select(2), setsockopt(2), socket(2), time(2), fdopen(3S), fileno(3S), gethostbyname(3N), inet_addr(3N), malloc(3C), rcmd(3N), sleep(3C).