449 lines
11 KiB
HTML
449 lines
11 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
|
||
|
|
<title>rexec()--Issue a Command on a Remote Host</title>
|
||
|
|
<!-- Begin Header Records ========================================== -->
|
||
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
||
|
|
<!-- US Government Users Restricted Rights -->
|
||
|
|
<!-- Use, duplication or disclosure restricted by -->
|
||
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
||
|
|
<!-- Created for V5R1 by Gary Hareldson -->
|
||
|
|
<!-- Edited by Kersten Feb 02 -->
|
||
|
|
<!--End Header Records -->
|
||
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<a name="Top_Of_Page"></a>
|
||
|
|
<!-- Java sync-link -->
|
||
|
|
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
||
|
|
</script>
|
||
|
|
|
||
|
|
<h2>rexec()--Issue a Command on a Remote Host</h2>
|
||
|
|
|
||
|
|
<div class="box" style="width: 60%;">
|
||
|
|
<br>
|
||
|
|
Syntax
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
#include <arpa/rexec.h>
|
||
|
|
|
||
|
|
int rexec(char **<em>host</em>,
|
||
|
|
int <em>port</em>,
|
||
|
|
char *<em>user</em>,
|
||
|
|
char *<em>password</em>,
|
||
|
|
char *<em>command</em>,
|
||
|
|
int *<em>errorDescriptor</em>);
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
Service Program Name: QSOSRV2<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Default Public Authority: *USE<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Threadsafe: Yes<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<p>The <strong>rexec()</strong> function is used to open a connection to a
|
||
|
|
remote host and send a user ID, password, and command to the remote host. The
|
||
|
|
remote host verifies that the user ID and password are valid. The command is
|
||
|
|
issued after the user ID and password are validated.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Parameters</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>host</strong> (Input) </dt>
|
||
|
|
|
||
|
|
<dd>A pointer to a character string that identifies the name of a remote
|
||
|
|
<em>host</em>.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>port</strong> (Input) </dt>
|
||
|
|
|
||
|
|
<dd>The well-known Internet <em>port</em> to use for the connection. A pointer
|
||
|
|
to the structure containing the necessary <em>port</em> can be obtained by
|
||
|
|
issuing the following call:<br>
|
||
|
|
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
getservbyname("exec", "tcp");
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p>The <em>port</em> returned by <em>getservbyname()</em> is the port on which
|
||
|
|
the remote <em>host</em> is listening for incoming <em>rexec()</em>
|
||
|
|
connections.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>user</strong> (Input) </dt>
|
||
|
|
|
||
|
|
<dd>A character string that identifies a valid <em>user</em> on the remote
|
||
|
|
<em>host</em>.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>password</strong> (Input) </dt>
|
||
|
|
|
||
|
|
<dd>A character string that identifies the <em>password</em> for the
|
||
|
|
<em>user</em> on the remote <em>host</em>. Specify a value of NULL if password
|
||
|
|
security is not active on the remote host.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>command</strong> (Input) </dt>
|
||
|
|
|
||
|
|
<dd>A character string that identifies the <em>command</em> to be issued on the
|
||
|
|
remote <em>host</em>.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>errorDescriptor</strong> (Input/Output) </dt>
|
||
|
|
|
||
|
|
<dd>One of the following values:<br>
|
||
|
|
<br>
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="10 90" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" nowrap><em>non-NULL</em></td>
|
||
|
|
<td align="left" valign="top">A second connection is set up and that a
|
||
|
|
descriptor for it is placed in the <em>errorDescriptor</em> parameter. This
|
||
|
|
connection provides standard error results of the remote <em>command</em>. This
|
||
|
|
information also includes remote authorization failure if <em>rexec()</em> is
|
||
|
|
unsuccessful.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>NULL</em></td>
|
||
|
|
<td align="left" valign="top">The standard error results of the remote
|
||
|
|
<em>command</em> are the same as the standard output return value.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Return Value</h3>
|
||
|
|
|
||
|
|
<p><strong>rexec()</strong> returns an integer. Possible values are:</p>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><em>Non-negative</em></dt>
|
||
|
|
|
||
|
|
<dd>(successful) A socket to the remote command is returned and can be used to
|
||
|
|
receive results of running the command on the remote host.
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>If errorDescriptor is non-NULL, standard error results of running the
|
||
|
|
command on the remote host can be received by using the errorDescriptor.</li>
|
||
|
|
|
||
|
|
<li>If errorDescriptor is NULL, standard error results of running the command
|
||
|
|
on the remote host can be received with the standard output results by using
|
||
|
|
the return value from rexec().</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[-1]</em></dt>
|
||
|
|
|
||
|
|
<dd>(unsuccessful) Refer to errno for a description of the failure.
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>If errno is 0 and errorDescriptor is NULL, the host does not exist or
|
||
|
|
remote authorization failed.</li>
|
||
|
|
|
||
|
|
<li>If errno is 0 and errorDescriptor is -1, the host does not exist.</li>
|
||
|
|
|
||
|
|
<li>If errno is 0 and errorDescriptor is non-negative, remote authorization
|
||
|
|
failed.</li>
|
||
|
|
</ul>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Authorities</h3>
|
||
|
|
|
||
|
|
<p>No authorization is required.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Error Conditions</h3>
|
||
|
|
|
||
|
|
<p>When the <strong>rexec()</strong> API fails, errno can be set to one of
|
||
|
|
following:</p>
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="20 80" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">[ECONNABORTED]</td>
|
||
|
|
<td align="left" valign="top">Connection ended abnormally.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">[ECONNREFUSED]</td>
|
||
|
|
<td align="left" valign="top">The destination socket refused an attempted
|
||
|
|
connect operation.
|
||
|
|
|
||
|
|
<p>This error occurs when the rexec server on the remote system is not
|
||
|
|
active.</p>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">[ECONNRESET]</td>
|
||
|
|
<td align="left" valign="top">A connection with a remote socket was reset by
|
||
|
|
that socket.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">[EFAULT]</td>
|
||
|
|
<td align="left" valign="top">Bad address.
|
||
|
|
|
||
|
|
<p>System detected an address which was not valid while attempting to access
|
||
|
|
the address parameters.</p>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">[EHOSTUNREACH]</td>
|
||
|
|
<td align="left" valign="top">A route to the remote host is not available.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">[EINTR]</td>
|
||
|
|
<td align="left" valign="top">Interrupted function call.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">[EINVAL]</td>
|
||
|
|
<td align="left" valign="top">Parameter not valid.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">[EMFILE]</td>
|
||
|
|
<td align="left" valign="top">Too many descriptors for this process.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">[ENFILE]</td>
|
||
|
|
<td align="left" valign="top">Too many descriptors in system.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">[EPIPE]</td>
|
||
|
|
<td align="left" valign="top">Broken pipe.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">[ETIMEDOUT]</td>
|
||
|
|
<td align="left" valign="top">A remote host did not respond within the timeout
|
||
|
|
period.
|
||
|
|
|
||
|
|
<p>This error code is returned when connection establishment times out. No
|
||
|
|
connection is established. A possible cause may be that the partner application
|
||
|
|
is bound, but the partner application has not yet issued a listen().</p>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">[EUNATCH]</td>
|
||
|
|
<td align="left" valign="top">The protocol required to support address family
|
||
|
|
AF_INET, is not available at this time.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">[EUNKNOWN]</td>
|
||
|
|
<td align="left" valign="top">Unknown system state.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Usage Notes</h3>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The password does not get encrypted while sent to the rexec server.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Any results of the command received by the caller of rexec() are not
|
||
|
|
converted from CCSID 819. Conversion from ASCII ccsid 819 to the CCSID of the
|
||
|
|
process or thread is the caller's responsibility.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>If a remote authorization failure occurs, the return value will be -1 and
|
||
|
|
if errorDescriptor is non-null a message indicating the authorization failure
|
||
|
|
can be received with the socket descriptor from errorDescriptor.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Any socket descriptor returned to the caller of rexec() must be explicitly
|
||
|
|
closed by the caller.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The user, password, and command will be translated from the job ccsid to
|
||
|
|
ASCII ccsid 819 to be sent to the remote host.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Issuing rexec() to a remote host that is configured to set up a SOCKSified
|
||
|
|
connection is not supported.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Related Information</h3>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li><a href="rexec_r.htm">rexec_r()</a>--Issue a Command on a Remote Host</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Example</h3>
|
||
|
|
|
||
|
|
<p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a>
|
||
|
|
for information pertaining to code examples.</p>
|
||
|
|
|
||
|
|
<p>The following example shows how <strong>rexec()</strong> is used:</p>
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
#include <stdio.h>
|
||
|
|
#include <stdlib.h>
|
||
|
|
#include <sys/types.h>
|
||
|
|
#include <sys/socket.h>
|
||
|
|
#include <qtqiconv.h>
|
||
|
|
#include <arpa/rexec.h>
|
||
|
|
#include <errno.h>
|
||
|
|
|
||
|
|
#define BufLen 256
|
||
|
|
|
||
|
|
void main()
|
||
|
|
{
|
||
|
|
int sd = -1, rc;
|
||
|
|
int responseLen = BufLen;
|
||
|
|
int outbytesleft = BufLen;
|
||
|
|
int bytesRead, saveBytesRead;
|
||
|
|
struct servent serv_ent;
|
||
|
|
struct servent_data serv_ent_data;
|
||
|
|
char inbuf[BufLen];
|
||
|
|
char outbuf[BufLen];
|
||
|
|
char *inbufPtr = (char *)inbuf;
|
||
|
|
char *outbufPtr = (char *)outbuf;
|
||
|
|
iconv_t cd;
|
||
|
|
QtqCode_T toCode = {0,0,0,0,0,0}; /* Convert to job CCSID */
|
||
|
|
QtqCode_T fromCode = {819,0,0,1,0,0}; /* ASCII CCSID */
|
||
|
|
char *host;
|
||
|
|
char remoteHost[256] = "remoteHost";
|
||
|
|
char user[32] = "userName";
|
||
|
|
char password[32] = "myPassword";
|
||
|
|
char cmd[256] = "commandToRun";
|
||
|
|
int *errordesc = NULL;
|
||
|
|
|
||
|
|
/* Must zero this out before call or results will be unpredictable. */
|
||
|
|
memset(&serv_ent_data.serve_control_blk, 0x00, sizeof(struct netdb_control_block));
|
||
|
|
|
||
|
|
/* retrieve the rexec server port number */
|
||
|
|
rc = getservbyname_r("exec", "tcp", &serv_ent, &serv_ent_data);
|
||
|
|
if (rc < 0)
|
||
|
|
printf("getservbyname_r() failed with errno = %d\n",errno);
|
||
|
|
|
||
|
|
host = remoteHost;
|
||
|
|
errno = 0;
|
||
|
|
|
||
|
|
/* Issue the rexec API */
|
||
|
|
sd = rexec(&host, serv_ent.s_port, user, password, cmd, errordesc);
|
||
|
|
if (sd == -1) /* check if rexec() failed */
|
||
|
|
{
|
||
|
|
if (errno)
|
||
|
|
printf("rexec() failed with errno = %d\n",errno);
|
||
|
|
else
|
||
|
|
printf("Either the host does not exist or remote authentication failed.\n");
|
||
|
|
}
|
||
|
|
else /* rexec() was successful */
|
||
|
|
{
|
||
|
|
bytesRead = recv(sd, inbuf, responseLen, 0);
|
||
|
|
if (bytesRead > 0)
|
||
|
|
{
|
||
|
|
saveBytesRead = bytesRead;
|
||
|
|
inbuf[bytesRead-1] = 0; /* Null terminate */
|
||
|
|
/* translate from ASCII to EBCDIC */
|
||
|
|
cd = QtqIconvOpen(&toCode, &fromCode);
|
||
|
|
iconv(cd,
|
||
|
|
(unsigned char **)&inbufPtr,
|
||
|
|
(unsigned int *)&bytesRead,
|
||
|
|
(unsigned char **)&outbufPtr,
|
||
|
|
(unsigned int *)&outbytesleft);
|
||
|
|
iconv_close(cd);
|
||
|
|
outbufPtr -= saveBytesRead; /* Reset the buffer pointers */
|
||
|
|
printf("%s\n",outbufPtr);
|
||
|
|
}
|
||
|
|
else if (bytesRead == 0)
|
||
|
|
printf("The remote host closed the connection.\n");
|
||
|
|
else
|
||
|
|
printf("recv() failed with errno = %d\n",errno);
|
||
|
|
}
|
||
|
|
if (sd != -1)
|
||
|
|
close(sd); /* close the connection. */
|
||
|
|
return;
|
||
|
|
}
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
API introduced: V5R1
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
<center>
|
||
|
|
<table cellpadding="2" cellspacing="2">
|
||
|
|
<tr align="center">
|
||
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> |
|
||
|
|
<a href="unix.htm">UNIX-Type APIs</a> |
|
||
|
|
<a href="aplist.htm">APIs by category</a> </td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</center>
|
||
|
|
</body>
|
||
|
|
</html>
|
||
|
|
|