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

p
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. In that case,
when a connection to one of that host’s
IP addresses fails, is refused, or times out before reaching the
PRC_READ_WAIT
state, prcmd() attempts to open a new connection on the host’s next
IP address (up
to a limit of five
IP addresses per host). A failure is not returned for a given host until all of its
IP
addresses have been tried.
Host/Connection Status
See ‘‘Usage Notes’’ for additional information on how calling programs should handle the following con-
nection status conditions.
PRC_CONN_NONE prcmd()
maps the prc_hostid value from a name to one or more
IP addresses
(if it does not appear to already be an address), maps the
IP addresses to binary,
gets an Internet socket bound to a reserved port number for communicating with
the host, maps the socket descriptor to a stream pointer using
fdopen(), and per-
forms a non-blocking
connect() of the socket descriptor to the remote host’s
‘‘shell’’ service. The socket’s send and receive buffer sizes are the default; the cal-
ling program can change the sizes with setsockopt (fileno (hostp
prc_fp))
at any time, subject to the restrictions documented in setsockopt (2).
If
gethostbyname() (see gethostbyname(3N)) or
inet_addr() (see
inet_addr (3N)) fails,
prcmd() sets the prc_conn_status
field to
PRC_CONN_NO_IPS.
Information needed for an
rcmd() connection includes the port number for the
‘‘shell’’ service and the user name of the effective user ID as the local and remote
user names. prcmd() looks up this information the first time it makes a connec-
tion. If prcmd() cannot obtain this information it returns PRC_ERR_RCMD (and
tries again each time it’s called).
If
socket() fails with any of the following local-host errors: EHOSTDOWN, EAF-
NOSUPPORT, ESOCKTNOSUPPORT
, EPROTONOSUPPORT, EPROTOTYPE,orEIN-
VAL, prcmd() returns PRC_ERR_NETWORKING
and the status of the host list is
unspecified.
If
socket() fails with EMFILE or ENFILE, which means the process or the sys-
tem is out of file descriptors, or if there are no available reserved ports, the
prc_conn_status field is left as
PRC_CONN_NONE for later retries. After
checking all host entries, if
prcmd() has no open files (sockets) for any host, and
it didn’t close any files during this call, it returns
PRC_ERR_NOFILE that is, all
file descriptors are in use for this process, but none by
prcmd().
If
connect() succeeds, or if it fails with EINPROGRESS, which is normal for a
non-blocking connect request, prcmd() sets prc_conn_status to
PRC_CONN1_WAIT, prc_conn_time to the current system clock in seconds, and
prc_fp to the stream pointer for this socket. This host is then included in the
select() list per PRC_CONN1_WAIT (see below).
PRC_CONN1_WAIT prcmd() includes this host in the select() list for write-readiness. If the con-
nection is not ready for writing, the prc_conn_status field is left unchanged.
When the connection is ready for writing,
prcmd() returns the socket to ‘‘block-
ing’’, starts a connection for standard error back from the remote command, sets
prc_fp2 to the file pointer for this connection, writes standard remsh connection
information (see remshd(1M) and also above) to the remote process with SIGPIPE
temporarily ignored using sigvector(), changes prc_conn_status to
PRC_CONN2_WAIT, and sets prc_conn_time to the current system clock in
seconds.
If a connection is refused,
prcmd() gets ECONNREFUSED or EPIPE on attempt
to write remsh connection information, and handles the error as previously
described in the section called ‘‘Common Error Handling’’.
PRC_CONN2_WAIT prcmd() includes this host in the select() list for read-readiness for both
prc_fp (in case of error) and prc_fp2 (in case of successful connection back to
HP-UX 11i Version 2: August 2003 3 Hewlett-Packard Company Section 3713