<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.3.1"/>
<title>libssh: Chapter 4: Passing a remote command</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">libssh
 <span id="projectnumber">0.5.5</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.3.1 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
<div id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="index.html">index</a></li><li class="navelem"><a class="el" href="libssh_tutorial.html">The Tutorial</a></li> </ul>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Chapter 4: Passing a remote command </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="remote_command"></a>
Passing a remote command</h1>
<p>Previous chapter has shown how to open a full shell session, with an attached terminal or not. If you only need to execute a command on the remote end, you don't need all that complexity.</p>
<p>The method described here is suited for executing only one remote command. If you need to issue several commands in a row, you should consider using a non-interactive remote shell, as explained in previous chapter.</p>
<dl class="section see"><dt>See Also</dt><dd>shell</dd></dl>
<h2><a class="anchor" id="exec_remote"></a>
Executing a remote command</h2>
<p>The first steps for executing a remote command are identical to those for opening remote shells. You first need a SSH channel, and then a SSH session that uses this channel:</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> show_remote_files(ssh_session session)</div>
<div class="line">{</div>
<div class="line"> ssh_channel channel;</div>
<div class="line"> <span class="keywordtype">int</span> rc;</div>
<div class="line"></div>
<div class="line"> channel = <a class="code" href="group__libssh__channel.html#gada8ccda7bf65165fe145d3096a252dcc" title="Allocate a new channel.">ssh_channel_new</a>(session);</div>
<div class="line"> <span class="keywordflow">if</span> (channel == NULL) <span class="keywordflow">return</span> SSH_ERROR;</div>
<div class="line"></div>
<div class="line"> rc = <a class="code" href="group__libssh__channel.html#gaf051dd30d75bf6dc45d1a5088cf970bd" title="Open a session channel (suited for a shell, not TCP forwarding).">ssh_channel_open_session</a>(channel);</div>
<div class="line"> <span class="keywordflow">if</span> (rc != SSH_OK)</div>
<div class="line"> {</div>
<div class="line"> <a class="code" href="group__libssh__channel.html#gad1417f9eae8928fed20faafe2d9dbfff" title="Close and free a channel.">ssh_channel_free</a>(channel);</div>
<div class="line"> <span class="keywordflow">return</span> rc;</div>
<div class="line"> }</div>
</div><!-- fragment --><p>Once a session is open, you can start the remote command with <a class="el" href="group__libssh__channel.html#ga567d509183ade0a77190f390e2b5747d" title="Run a shell command without an interactive shell.">ssh_channel_request_exec()</a>:</p>
<div class="fragment"><div class="line">rc = <a class="code" href="group__libssh__channel.html#ga567d509183ade0a77190f390e2b5747d" title="Run a shell command without an interactive shell.">ssh_channel_request_exec</a>(channel, <span class="stringliteral">"ls -l"</span>);</div>
<div class="line"><span class="keywordflow">if</span> (rc != SSH_OK)</div>
<div class="line">{</div>
<div class="line"> <a class="code" href="group__libssh__channel.html#ga238f07e0455456a5bfd8a49ead917732" title="Close a channel.">ssh_channel_close</a>(channel);</div>
<div class="line"> <a class="code" href="group__libssh__channel.html#gad1417f9eae8928fed20faafe2d9dbfff" title="Close and free a channel.">ssh_channel_free</a>(channel);</div>
<div class="line"> <span class="keywordflow">return</span> rc;</div>
<div class="line">}</div>
</div><!-- fragment --><p>If the remote command displays data, you get them with <a class="el" href="group__libssh__channel.html#gac92381c4c5d4a7eab35f6e84686f033d" title="Reads data from a channel.">ssh_channel_read()</a>. This function returns the number of bytes read. If there is no more data to read on the channel, this function returns 0, and you can go to next step. If an error has been encountered, it returns a negative value:</p>
<div class="fragment"><div class="line"><span class="keywordtype">char</span> buffer[256];</div>
<div class="line"><span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> nbytes;</div>
<div class="line"></div>
<div class="line">nbytes = <a class="code" href="group__libssh__channel.html#gac92381c4c5d4a7eab35f6e84686f033d" title="Reads data from a channel.">ssh_channel_read</a>(channel, buffer, <span class="keyword">sizeof</span>(buffer), 0);</div>
<div class="line"><span class="keywordflow">while</span> (nbytes > 0)</div>
<div class="line">{</div>
<div class="line"> <span class="keywordflow">if</span> (fwrite(buffer, 1, nbytes, stdout) != nbytes)</div>
<div class="line"> {</div>
<div class="line"> <a class="code" href="group__libssh__channel.html#ga238f07e0455456a5bfd8a49ead917732" title="Close a channel.">ssh_channel_close</a>(channel);</div>
<div class="line"> <a class="code" href="group__libssh__channel.html#gad1417f9eae8928fed20faafe2d9dbfff" title="Close and free a channel.">ssh_channel_free</a>(channel);</div>
<div class="line"> <span class="keywordflow">return</span> SSH_ERROR;</div>
<div class="line"> }</div>
<div class="line"> nbytes = <a class="code" href="group__libssh__channel.html#gac92381c4c5d4a7eab35f6e84686f033d" title="Reads data from a channel.">ssh_channel_read</a>(channel, buffer, <span class="keyword">sizeof</span>(buffer), 0);</div>
<div class="line">}</div>
<div class="line"></div>
<div class="line"><span class="keywordflow">if</span> (nbytes < 0)</div>
<div class="line">{</div>
<div class="line"> <a class="code" href="group__libssh__channel.html#ga238f07e0455456a5bfd8a49ead917732" title="Close a channel.">ssh_channel_close</a>(channel);</div>
<div class="line"> <a class="code" href="group__libssh__channel.html#gad1417f9eae8928fed20faafe2d9dbfff" title="Close and free a channel.">ssh_channel_free</a>(channel);</div>
<div class="line"> <span class="keywordflow">return</span> SSH_ERROR;</div>
<div class="line">}</div>
</div><!-- fragment --><p>Once you read the result of the remote command, you send an end-of-file to the channel, close it, and free the memory that it used:</p>
<div class="fragment"><div class="line"> <a class="code" href="group__libssh__channel.html#ga072f82fdf3e50514f747653af2c99004" title="Send an end of file on the channel.">ssh_channel_send_eof</a>(channel);</div>
<div class="line"> <a class="code" href="group__libssh__channel.html#ga238f07e0455456a5bfd8a49ead917732" title="Close a channel.">ssh_channel_close</a>(channel);</div>
<div class="line"> <a class="code" href="group__libssh__channel.html#gad1417f9eae8928fed20faafe2d9dbfff" title="Close and free a channel.">ssh_channel_free</a>(channel);</div>
<div class="line"></div>
<div class="line"> <span class="keywordflow">return</span> SSH_OK;</div>
<div class="line">}</div>
</div><!-- fragment --> </div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.3.1
</small></address>
</body>
</html>
