friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
14ed2849c6
ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/rexec_r.htm

475 lines
13 KiB
HTML
Raw Blame History

<!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_r()--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_r()--Issue a Command on a Remote Host</h2>
<div class="box" style="width: 60%;">
<br>
&nbsp;&nbsp;Syntax
<pre>
#include &lt;arpa/rexec.h&gt;
int rexec_r(char **<em>host</em>,
int <em>port</em>,
char *<em>user</em>,
char *<em>password</em>,
char *<em>command</em>,
int *<em>errorDescriptor</em>,
struct hostent_data *<em>hostEntData</em>);
</pre>
<br>
&nbsp;&nbsp;Service Program Name: QSOSRV2<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The <strong>rexec_r()</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 will
be issued after the user ID and password are validated.</p>
<br>
<h3>Parameters</h3>
<dl>
<dt><strong>host</strong>&nbsp;(Input)&nbsp;</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>&nbsp;(Input)&nbsp;</dt>
<dd>The well-known Internet <em>port</em> to use for the connection. A pointer
to the structure that contains the necessary <em>port</em> can be obtained by
issuing the following call:<br>
<br>
<pre>
struct servent servEnt;
struct servent_data servEntData;
memset(&amp;servEntData.serve_control_blk, 0x00, sizeof(struct netdb_control_block));
getservbyname_r("exec", "tcp", &amp;servEnt, &amp;servEntData);
</pre>
<p>The <em>port</em> returned by <em>getservbyname_r()</em> is the port that
the remote <em>host</em> is listening on for incoming <em>rexec_r()</em>
connections.</p>
</dd>
<dt><strong>user</strong>&nbsp;(Input)&nbsp;</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>&nbsp;(Input)&nbsp;</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>&nbsp;(Input)&nbsp;</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>&nbsp;(Input/Output)&nbsp;</dt>
<dd>One of the following values:<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 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 will also include remote authorization failure if <em>rexec()</em>
is unsuccessful.<br>
<br>
</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> is the same as the standard output return value.</td>
</tr>
</table>
<br>
<br>
</dd>
<dt><strong>hostEntData</strong>&nbsp;(Input/Output)&nbsp;</dt>
<dd>A pointer to the hostent_data structure, which is used to pass and preserve
results between function calls. <em>rexec_r()</em> performs a
<em>gethostbyname_r()</em> and each thread needs its own host data. The field
<em>host_control_block</em> in the <em>hostent_data</em> structure must be
initialized to hexadecimal zeros before its initial use. If compatibility with
other platforms is required, then the entire <em>hostent_data</em> structure
must be initialized to hexadecimal zeros before its initial use. The
<em>hostent_data</em> structure is defined in &lt;netdb.h&gt;&gt;.</dd>
</dl>
<br>
<h3>Return Value</h3>
<p><strong>rexec_r()</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 along with the standard output results by
using the return value from rexec_r().</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_r()</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.
<p>This error code occurs when the hostEntData structure has not been
initialized to hexadecimal zeros. For corrective action, see the description
for structure hostent_data.</p>
</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_r() 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_r() 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_r() 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.htm">rexec()</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_r()</strong> is used:</p>
<pre>
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;sys/types.h&gt;
#include &lt;sys/socket.h&gt;
#include &lt;qtqiconv.h&gt;
#include &lt;arpa/rexec.h&gt;
#include &lt;errno.h&gt;
#define BufLen 256
void main()
{
int sd = -1, rc;
int responseLen = BufLen;
int outbytesleft = BufLen;
int bytesRead, saveBytesRead;
struct hostent_data host_ent_data;
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] = &quot;remoteHost&quot;;
char user[32] = &quot;userName&quot;;
char password[32] = &quot;myPassword&quot;;
char cmd[256] = &quot;commandToRun&quot;;
int *errordesc = NULL;
/* Must zero this out before call or results will be unpredictable. */
memset(&amp;serv_ent_data.serve_control_blk, 0x00, sizeof(struct netdb_control_block));
/* retrieve the rexec server port number */
rc = getservbyname_r(&quot;exec&quot;, &quot;tcp&quot;, &amp;serv_ent, &amp;serv_ent_data);
if (rc &lt; 0)
printf("getservbyname_r() failed with errno = %d\n",errno);
/* must zero this out before call or results will be unpredictable. */
memset((void *)&amp;host_ent_data.host_control_blk, 0x00, sizeof(struct netdb_control_block));
host = remoteHost;
errno = 0;
/* issue the rexec_r api */
sd = rexec_r(&amp;host, serv_ent.s_port, user, password, cmd, errordesc, &amp;host_ent_data);
if (sd == -1) /* check if rexec_r() failed */
{
if (errno)
printf("rexec_r() failed with errno = %d\n",errno);
else
printf("Either the host does not exist or remote authentication failed.\n");
}
else /* rexec_r() was successful */
{
bytesRead = recv(sd, inbuf, responseLen, 0);
if (bytesRead &gt; 0)
{
saveBytesRead = bytesRead;
inbuf[bytesRead-1] = 0; /* Null terminate */
/* translate from ASCII to EBCDIC */
cd = QtqIconvOpen(&amp;toCode, &amp;fromCode);
iconv(cd,
(unsigned char **)&amp;inbufPtr,
(unsigned int *)&amp;bytesRead,
(unsigned char **)&amp;outbufPtr,
(unsigned int *)&amp;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>
Reference in New Issue View Git Blame Copy Permalink