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

p
prcmd(3N) prcmd(3N)
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 connection
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 performs a
non-blocking
connect() of the socket descriptor to the remote host’s "shell" ser-
vice. The socket’s send and receive buffer sizes are the default; the calling 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 connection. 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],
[EAFNOSUPPORT], [ESOCKTNOSUPPORT], [EPROTONOSUPPORT], [EPROTO-
TYPE], or [EINVAL], 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 "blocking",
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 Common Error Handling section.
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 the
152 Hewlett-Packard Company − 3 − HP-UX 11i Version 2: December 2007 Update