<!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 5: The SFTP subsystem</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 5: The SFTP subsystem </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="sftp_subsystem"></a>
The SFTP subsystem</h1>
<p>SFTP stands for "Secure File Transfer Protocol". It enables you to safely transfer files between the local and the remote computer. It reminds a lot of the old FTP protocol.</p>
<p>SFTP is a rich protocol. It lets you do over the network almost everything that you can do with local files:</p>
<ul>
<li>send files</li>
<li>modify only a portion of a file</li>
<li>receive files</li>
<li>receive only a portion of a file</li>
<li>get file owner and group</li>
<li>get file permissions</li>
<li>set file owner and group</li>
<li>set file permissions</li>
<li>remove files</li>
<li>rename files</li>
<li>create a directory</li>
<li>remove a directory</li>
<li>retrieve the list of files in a directory</li>
<li>get the target of a symbolic link</li>
<li>create symbolic links</li>
<li>get information about mounted filesystems.</li>
</ul>
<p>The current implemented version of the SFTP protocol is version 3. All functions aren't implemented yet, but the most important are.</p>
<h2><a class="anchor" id="sftp_session"></a>
Opening and closing a SFTP session</h2>
<p>Unlike with remote shells and remote commands, when you use the SFTP subsystem, you don't handle directly the SSH channels. Instead, you open a "SFTP session".</p>
<p>The function <a class="el" href="group__libssh__sftp.html#ga32c8e182e97352e1aa8a20443c320d7f" title="Start a new sftp session.">sftp_new()</a> creates a new SFTP session. The function <a class="el" href="group__libssh__sftp.html#ga6eb5a92e33493ec3d9a3576e1617da0d" title="Initialize the sftp session with the server.">sftp_init()</a> initializes it. The function <a class="el" href="group__libssh__sftp.html#ga155c66639cb3342c7e02a96c8dbf7501" title="Close and deallocate a sftp session.">sftp_free()</a> deletes it.</p>
<p>As you see, all the SFTP-related functions start with the "sftp_" prefix instead of the usual "ssh_" prefix.</p>
<p>The example below shows how to use these functions:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include <<a class="code" href="sftp_8h.html" title="SFTP handling functions.">libssh/sftp.h</a>></span></div>
<div class="line"></div>
<div class="line"><span class="keywordtype">int</span> sftp_helloworld(ssh_session session)</div>
<div class="line">{</div>
<div class="line"> sftp_session sftp;</div>
<div class="line"> <span class="keywordtype">int</span> rc;</div>
<div class="line"></div>
<div class="line"> sftp = <a class="code" href="group__libssh__sftp.html#ga32c8e182e97352e1aa8a20443c320d7f" title="Start a new sftp session.">sftp_new</a>(session);</div>
<div class="line"> <span class="keywordflow">if</span> (sftp == NULL)</div>
<div class="line"> {</div>
<div class="line"> fprintf(stderr, <span class="stringliteral">"Error allocating SFTP session: %s\n"</span>, <a class="code" href="group__libssh__error.html#ga9241586665bf21f823806473fc386258" title="Retrieve the error text message from the last error.">ssh_get_error</a>(session));</div>
<div class="line"> <span class="keywordflow">return</span> SSH_ERROR;</div>
<div class="line"> }</div>
<div class="line"></div>
<div class="line"> rc = <a class="code" href="group__libssh__sftp.html#ga6eb5a92e33493ec3d9a3576e1617da0d" title="Initialize the sftp session with the server.">sftp_init</a>(sftp);</div>
<div class="line"> <span class="keywordflow">if</span> (rc != SSH_OK)</div>
<div class="line"> {</div>
<div class="line"> fprintf(stderr, <span class="stringliteral">"Error initializing SFTP session: %s.\n"</span>, <a class="code" href="group__libssh__sftp.html#ga1f7fca4091a0075d9e69e47c928f7494" title="Get the last sftp error.">sftp_get_error</a>(sftp));</div>
<div class="line"> <a class="code" href="group__libssh__sftp.html#ga155c66639cb3342c7e02a96c8dbf7501" title="Close and deallocate a sftp session.">sftp_free</a>(sftp);</div>
<div class="line"> <span class="keywordflow">return</span> rc;</div>
<div class="line"> }</div>
<div class="line"></div>
<div class="line"> ...</div>
<div class="line"></div>
<div class="line"> <a class="code" href="group__libssh__sftp.html#ga155c66639cb3342c7e02a96c8dbf7501" title="Close and deallocate a sftp session.">sftp_free</a>(sftp);</div>
<div class="line"> <span class="keywordflow">return</span> SSH_OK;</div>
<div class="line">}</div>
</div><!-- fragment --><h2><a class="anchor" id="sftp_errors"></a>
Analyzing SFTP errors</h2>
<p>In case of a problem, the function <a class="el" href="group__libssh__sftp.html#ga1f7fca4091a0075d9e69e47c928f7494" title="Get the last sftp error.">sftp_get_error()</a> returns a SFTP-specific error number, in addition to the regular SSH error number returned by ssh_get_error_number().</p>
<p>Possible errors are:</p>
<ul>
<li>SSH_FX_OK: no error</li>
<li>SSH_FX_EOF: end-of-file encountered</li>
<li>SSH_FX_NO_SUCH_FILE: file does not exist</li>
<li>SSH_FX_PERMISSION_DENIED: permission denied</li>
<li>SSH_FX_FAILURE: generic failure</li>
<li>SSH_FX_BAD_MESSAGE: garbage received from server</li>
<li>SSH_FX_NO_CONNECTION: no connection has been set up</li>
<li>SSH_FX_CONNECTION_LOST: there was a connection, but we lost it</li>
<li>SSH_FX_OP_UNSUPPORTED: operation not supported by libssh yet</li>
<li>SSH_FX_INVALID_HANDLE: invalid file handle</li>
<li>SSH_FX_NO_SUCH_PATH: no such file or directory path exists</li>
<li>SSH_FX_FILE_ALREADY_EXISTS: an attempt to create an already existing file or directory has been made</li>
<li>SSH_FX_WRITE_PROTECT: write-protected filesystem</li>
<li>SSH_FX_NO_MEDIA: no media was in remote drive</li>
</ul>
<h2><a class="anchor" id="sftp_mkdir"></a>
Creating a directory</h2>
<p>The function <a class="el" href="group__libssh__sftp.html#ga9cc63cd3efe83edfa3f6a4c5314383cb" title="Create a directory.">sftp_mkdir()</a> tahes the "SFTP session" we juste created as its first argument. It also needs the name of the file to create, and the desired permissions. The permissions are the same as for the usual mkdir() function. To get a comprehensive list of the available permissions, use the "man 2 stat" command. The desired permissions are combined with the remote user's mask to determine the effective permissions.</p>
<p>The code below creates a directory named "helloworld" in the current directory that can be read and written only by its owner:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include <<a class="code" href="sftp_8h.html" title="SFTP handling functions.">libssh/sftp.h</a>></span></div>
<div class="line"><span class="preprocessor">#include <sys/stat.h></span></div>
<div class="line"></div>
<div class="line"><span class="keywordtype">int</span> sftp_helloworld(ssh_session session, sftp_session sftp)</div>
<div class="line">{</div>
<div class="line"> <span class="keywordtype">int</span> rc;</div>
<div class="line"></div>
<div class="line"> rc = <a class="code" href="group__libssh__sftp.html#ga9cc63cd3efe83edfa3f6a4c5314383cb" title="Create a directory.">sftp_mkdir</a>(sftp, <span class="stringliteral">"helloworld"</span>, S_IRWXU);</div>
<div class="line"> <span class="keywordflow">if</span> (rc != SSH_OK)</div>
<div class="line"> {</div>
<div class="line"> <span class="keywordflow">if</span> (<a class="code" href="group__libssh__sftp.html#ga1f7fca4091a0075d9e69e47c928f7494" title="Get the last sftp error.">sftp_get_error</a>(sftp) != <a class="code" href="group__libssh__sftp.html#gabae8a18fd96320cc78ea052eb269ed38" title="An attempt to create an already existing file or directory has been made.">SSH_FX_FILE_ALREADY_EXISTS</a>)</div>
<div class="line"> {</div>
<div class="line"> fprintf(stderr, <span class="stringliteral">"Can't create directory: %s\n"</span>, <a class="code" href="group__libssh__error.html#ga9241586665bf21f823806473fc386258" title="Retrieve the error text message from the last error.">ssh_get_error</a>(session));</div>
<div class="line"> <span class="keywordflow">return</span> rc;</div>
<div class="line"> }</div>
<div class="line"> }</div>
<div class="line"></div>
<div class="line"> ...</div>
<div class="line"></div>
<div class="line"> <span class="keywordflow">return</span> SSH_OK;</div>
<div class="line">}</div>
</div><!-- fragment --><p>Unlike its equivalent in the SCP subsystem, this function does NOT change the current directory to the newly created subdirectory.</p>
<h2><a class="anchor" id="sftp_write"></a>
Copying a file to the remote computer</h2>
<p>You handle the contents of a remote file just like you would do with a local file: you open the file in a given mode, move the file pointer in it, read or write data, and close the file.</p>
<p>The <a class="el" href="group__libssh__sftp.html#gab95cb5fe091efcc49dfa7729e4d48010" title="Open a file on the server.">sftp_open()</a> function is very similar to the regular open() function, excepted that it returns a file handle of type sftp_file. This file handle is then used by the other file manipulation functions and remains valid until you close the remote file with <a class="el" href="group__libssh__sftp.html#ga5878919249d4e8abe59b0ec699eed293" title="Close an open file handle.">sftp_close()</a>.</p>
<p>The example below creates a new file named "helloworld.txt" in the newly created "helloworld" directory. If the file already exists, it will be truncated. It then writes the famous "Hello, World!" sentence to the file, followed by a new line character. Finally, the file is closed:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include <<a class="code" href="sftp_8h.html" title="SFTP handling functions.">libssh/sftp.h</a>></span></div>
<div class="line"><span class="preprocessor">#include <sys/stat.h></span></div>
<div class="line"><span class="preprocessor">#include <fcntl.h></span></div>
<div class="line"></div>
<div class="line"><span class="keywordtype">int</span> sftp_helloworld(ssh_session session, sftp_session sftp)</div>
<div class="line">{</div>
<div class="line"> <span class="keywordtype">int</span> access_type = O_WRONLY | O_CREAT | O_TRUNC;</div>
<div class="line"> sftp_file file;</div>
<div class="line"> <span class="keyword">const</span> <span class="keywordtype">char</span> *helloworld = <span class="stringliteral">"Hello, World!\n"</span>;</div>
<div class="line"> <span class="keywordtype">int</span> length = strlen(helloworld);</div>
<div class="line"> <span class="keywordtype">int</span> rc, nwritten;</div>
<div class="line"></div>
<div class="line"> ...</div>
<div class="line"></div>
<div class="line"> file = <a class="code" href="group__libssh__sftp.html#gab95cb5fe091efcc49dfa7729e4d48010" title="Open a file on the server.">sftp_open</a>(sftp, <span class="stringliteral">"helloworld/helloworld.txt"</span>, access_type, S_IRWXU);</div>
<div class="line"> <span class="keywordflow">if</span> (file == NULL)</div>
<div class="line"> {</div>
<div class="line"> fprintf(stderr, <span class="stringliteral">"Can't open file for writing: %s\n"</span>, <a class="code" href="group__libssh__error.html#ga9241586665bf21f823806473fc386258" title="Retrieve the error text message from the last error.">ssh_get_error</a>(session));</div>
<div class="line"> <span class="keywordflow">return</span> SSH_ERROR;</div>
<div class="line"> }</div>
<div class="line"></div>
<div class="line"> nwritten = <a class="code" href="group__libssh__sftp.html#ga744054eb0dcfb0feed5ba81ed01ad3c0" title="Write to a file using an opened sftp file handle.">sftp_write</a>(file, helloworld, length);</div>
<div class="line"> <span class="keywordflow">if</span> (nwritten != length)</div>
<div class="line"> {</div>
<div class="line"> fprintf(stderr, <span class="stringliteral">"Can't write data to file: %s\n"</span>, <a class="code" href="group__libssh__error.html#ga9241586665bf21f823806473fc386258" title="Retrieve the error text message from the last error.">ssh_get_error</a>(session));</div>
<div class="line"> <a class="code" href="group__libssh__sftp.html#ga5878919249d4e8abe59b0ec699eed293" title="Close an open file handle.">sftp_close</a>(file);</div>
<div class="line"> <span class="keywordflow">return</span> SSH_ERROR;</div>
<div class="line"> }</div>
<div class="line"></div>
<div class="line"> rc = <a class="code" href="group__libssh__sftp.html#ga5878919249d4e8abe59b0ec699eed293" title="Close an open file handle.">sftp_close</a>(file);</div>
<div class="line"> <span class="keywordflow">if</span> (rc != SSH_OK)</div>
<div class="line"> {</div>
<div class="line"> fprintf(stderr, <span class="stringliteral">"Can't close the written file: %s\n"</span>, <a class="code" href="group__libssh__error.html#ga9241586665bf21f823806473fc386258" title="Retrieve the error text message from the last error.">ssh_get_error</a>(session));</div>
<div class="line"> <span class="keywordflow">return</span> rc;</div>
<div class="line"> }</div>
<div class="line"></div>
<div class="line"> <span class="keywordflow">return</span> SSH_OK;</div>
<div class="line">}</div>
</div><!-- fragment --><h2><a class="anchor" id="sftp_read"></a>
Reading a file from the remote computer</h2>
<p>The nice thing with reading a file over the network through SFTP is that it can be done both in a synchronous way or an asynchronous way. If you read the file asynchronously, your program can do something else while it waits for the results to come.</p>
<p>Synchronous read is done with <a class="el" href="group__libssh__sftp.html#ga6c2bfeb2e089f54c04afe1e484a7fff2" title="Read from a file using an opened sftp file handle.">sftp_read()</a>.</p>
<p>The following example prints the contents of remote file "/etc/profile". For each 1024 bytes of information read, it waits until the end of the read operation:</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> sftp_read_sync(ssh_session session, sftp_session sftp)</div>
<div class="line">{</div>
<div class="line"> <span class="keywordtype">int</span> access_type;</div>
<div class="line"> sftp_file file;</div>
<div class="line"> <span class="keywordtype">char</span> buffer[1024];</div>
<div class="line"> <span class="keywordtype">int</span> nbytes, rc;</div>
<div class="line"></div>
<div class="line"> access_type = O_RDONLY;</div>
<div class="line"> file = <a class="code" href="group__libssh__sftp.html#gab95cb5fe091efcc49dfa7729e4d48010" title="Open a file on the server.">sftp_open</a>(sftp, <span class="stringliteral">"/etc/profile"</span>, access_type, 0);</div>
<div class="line"> <span class="keywordflow">if</span> (file == NULL)</div>
<div class="line"> {</div>
<div class="line"> fprintf(stderr, <span class="stringliteral">"Can't open file for reading: %s\n"</span>, <a class="code" href="group__libssh__error.html#ga9241586665bf21f823806473fc386258" title="Retrieve the error text message from the last error.">ssh_get_error</a>(session));</div>
<div class="line"> <span class="keywordflow">return</span> SSH_ERROR;</div>
<div class="line"> }</div>
<div class="line"></div>
<div class="line"> nbytes = <a class="code" href="group__libssh__sftp.html#ga6c2bfeb2e089f54c04afe1e484a7fff2" title="Read from a file using an opened sftp file handle.">sftp_read</a>(file, buffer, <span class="keyword">sizeof</span>(buffer));</div>
<div class="line"> <span class="keywordflow">while</span> (nbytes > 0)</div>
<div class="line"> {</div>
<div class="line"> <span class="keywordflow">if</span> (write(1, buffer, nbytes) != nbytes)</div>
<div class="line"> {</div>
<div class="line"> <a class="code" href="group__libssh__sftp.html#ga5878919249d4e8abe59b0ec699eed293" title="Close an open file handle.">sftp_close</a>(file);</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__sftp.html#ga6c2bfeb2e089f54c04afe1e484a7fff2" title="Read from a file using an opened sftp file handle.">sftp_read</a>(file, buffer, <span class="keyword">sizeof</span>(buffer));</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"> fprintf(stderr, <span class="stringliteral">"Error while reading file: %s\n"</span>, <a class="code" href="group__libssh__error.html#ga9241586665bf21f823806473fc386258" title="Retrieve the error text message from the last error.">ssh_get_error</a>(session));</div>
<div class="line"> <a class="code" href="group__libssh__sftp.html#ga5878919249d4e8abe59b0ec699eed293" title="Close an open file handle.">sftp_close</a>(file);</div>
<div class="line"> <span class="keywordflow">return</span> SSH_ERROR;</div>
<div class="line"> }</div>
<div class="line"></div>
<div class="line"> rc = <a class="code" href="group__libssh__sftp.html#ga5878919249d4e8abe59b0ec699eed293" title="Close an open file handle.">sftp_close</a>(file);</div>
<div class="line"> <span class="keywordflow">if</span> (rc != SSH_OK)</div>
<div class="line"> {</div>
<div class="line"> fprintf(stderr, <span class="stringliteral">"Can't close the read file: %s\n"</span>, <a class="code" href="group__libssh__error.html#ga9241586665bf21f823806473fc386258" title="Retrieve the error text message from the last error.">ssh_get_error</a>(session));</div>
<div class="line"> <span class="keywordflow">return</span> rc;</div>
<div class="line"> }</div>
<div class="line"></div>
<div class="line"> <span class="keywordflow">return</span> SSH_OK;</div>
<div class="line">}</div>
</div><!-- fragment --><p>Asynchronous read is done in two steps, first <a class="el" href="group__libssh__sftp.html#ga4c2cca19b38c54d4b04bb3584b0517cd" title="Start an asynchronous read from a file using an opened sftp file handle.">sftp_async_read_begin()</a>, which returns a "request handle", and then <a class="el" href="group__libssh__sftp.html#ga4399c7ccd8b39a460265047f9d7bc9b1" title="Wait for an asynchronous read to complete and save the data.">sftp_async_read()</a>, which uses that request handle. If the file has been opened in nonblocking mode, then <a class="el" href="group__libssh__sftp.html#ga4399c7ccd8b39a460265047f9d7bc9b1" title="Wait for an asynchronous read to complete and save the data.">sftp_async_read()</a> might return SSH_AGAIN, which means that the request hasn't completed yet and that the function should be called again later on. Otherwise, <a class="el" href="group__libssh__sftp.html#ga4399c7ccd8b39a460265047f9d7bc9b1" title="Wait for an asynchronous read to complete and save the data.">sftp_async_read()</a> waits for the data to come. To open a file in nonblocking mode, call sftp_file_set_nonblocking() right after you opened it. Default is blocking mode.</p>
<p>The example below reads a very big file in asynchronous, nonblocking, mode. Each time the data are not ready yet, a counter is incrementer.</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> sftp_read_async(ssh_session session, sftp_session sftp)</div>
<div class="line">{</div>
<div class="line"> <span class="keywordtype">int</span> access_type;</div>
<div class="line"> sftp_file file;</div>
<div class="line"> <span class="keywordtype">char</span> buffer[1024];</div>
<div class="line"> <span class="keywordtype">int</span> async_request;</div>
<div class="line"> <span class="keywordtype">int</span> nbytes;</div>
<div class="line"> <span class="keywordtype">long</span> counter;</div>
<div class="line"> <span class="keywordtype">int</span> rc;</div>
<div class="line"></div>
<div class="line"> access_type = O_RDONLY;</div>
<div class="line"> file = <a class="code" href="group__libssh__sftp.html#gab95cb5fe091efcc49dfa7729e4d48010" title="Open a file on the server.">sftp_open</a>(sftp, <span class="stringliteral">"some_very_big_file"</span>, access_type, 0);</div>
<div class="line"> <span class="keywordflow">if</span> (file == NULL)</div>
<div class="line"> {</div>
<div class="line"> fprintf(stderr, <span class="stringliteral">"Can't open file for reading: %s\n"</span>, <a class="code" href="group__libssh__error.html#ga9241586665bf21f823806473fc386258" title="Retrieve the error text message from the last error.">ssh_get_error</a>(session));</div>
<div class="line"> <span class="keywordflow">return</span> SSH_ERROR;</div>
<div class="line"> }</div>
<div class="line"> sftp_file_set_nonblocking(file);</div>
<div class="line"></div>
<div class="line"> async_request = <a class="code" href="group__libssh__sftp.html#ga4c2cca19b38c54d4b04bb3584b0517cd" title="Start an asynchronous read from a file using an opened sftp file handle.">sftp_async_read_begin</a>(file, <span class="keyword">sizeof</span>(buffer));</div>
<div class="line"> counter = 0L;</div>
<div class="line"> usleep(10000);</div>
<div class="line"> <span class="keywordflow">if</span> (async_request >= 0)</div>
<div class="line"> nbytes = <a class="code" href="group__libssh__sftp.html#ga4399c7ccd8b39a460265047f9d7bc9b1" title="Wait for an asynchronous read to complete and save the data.">sftp_async_read</a>(file, buffer, <span class="keyword">sizeof</span>(buffer), async_request);</div>
<div class="line"> <span class="keywordflow">else</span> nbytes = -1;</div>
<div class="line"> <span class="keywordflow">while</span> (nbytes > 0 || nbytes == SSH_AGAIN)</div>
<div class="line"> {</div>
<div class="line"> <span class="keywordflow">if</span> (nbytes > 0)</div>
<div class="line"> {</div>
<div class="line"> write(1, buffer, nbytes);</div>
<div class="line"> async_request = <a class="code" href="group__libssh__sftp.html#ga4c2cca19b38c54d4b04bb3584b0517cd" title="Start an asynchronous read from a file using an opened sftp file handle.">sftp_async_read_begin</a>(file, <span class="keyword">sizeof</span>(buffer));</div>
<div class="line"> }</div>
<div class="line"> <span class="keywordflow">else</span> counter++;</div>
<div class="line"> usleep(10000);</div>
<div class="line"> <span class="keywordflow">if</span> (async_request >= 0)</div>
<div class="line"> nbytes = <a class="code" href="group__libssh__sftp.html#ga4399c7ccd8b39a460265047f9d7bc9b1" title="Wait for an asynchronous read to complete and save the data.">sftp_async_read</a>(file, buffer, <span class="keyword">sizeof</span>(buffer), async_request);</div>
<div class="line"> <span class="keywordflow">else</span> nbytes = -1;</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"> fprintf(stderr, <span class="stringliteral">"Error while reading file: %s\n"</span>, <a class="code" href="group__libssh__error.html#ga9241586665bf21f823806473fc386258" title="Retrieve the error text message from the last error.">ssh_get_error</a>(session));</div>
<div class="line"> <a class="code" href="group__libssh__sftp.html#ga5878919249d4e8abe59b0ec699eed293" title="Close an open file handle.">sftp_close</a>(file);</div>
<div class="line"> <span class="keywordflow">return</span> SSH_ERROR;</div>
<div class="line"> }</div>
<div class="line"></div>
<div class="line"> printf(<span class="stringliteral">"The counter has reached value: %ld\n"</span>, counter);</div>
<div class="line"></div>
<div class="line"> rc = <a class="code" href="group__libssh__sftp.html#ga5878919249d4e8abe59b0ec699eed293" title="Close an open file handle.">sftp_close</a>(file);</div>
<div class="line"> <span class="keywordflow">if</span> (rc != SSH_OK)</div>
<div class="line"> {</div>
<div class="line"> fprintf(stderr, <span class="stringliteral">"Can't close the read file: %s\n"</span>, <a class="code" href="group__libssh__error.html#ga9241586665bf21f823806473fc386258" title="Retrieve the error text message from the last error.">ssh_get_error</a>(session));</div>
<div class="line"> <span class="keywordflow">return</span> rc;</div>
<div class="line"> }</div>
<div class="line"></div>
<div class="line"> <span class="keywordflow">return</span> SSH_OK;</div>
<div class="line">}</div>
</div><!-- fragment --><h2><a class="anchor" id="sftp_ls"></a>
Listing the contents of a directory</h2>
<p>The functions <a class="el" href="group__libssh__sftp.html#gab4290874bdb55796b2823496e0d9b7ec" title="Open a directory used to obtain directory entries.">sftp_opendir()</a>, <a class="el" href="group__libssh__sftp.html#ga976ecf6f7d415856e1fd4a0f16ada9b8" title="Get a single file attributes structure of a directory.">sftp_readdir()</a>, <a class="el" href="group__libssh__sftp.html#gad60f8e71b06eb8fdae2b262bb58f8fec" title="Tell if the directory has reached EOF (End Of File).">sftp_dir_eof()</a>, and <a class="el" href="group__libssh__sftp.html#ga35551e5b28b192ef8035628d347f7d3e" title="Close a directory handle opened by sftp_opendir().">sftp_closedir()</a> enable to list the contents of a directory. They use a new handle_type, "sftp_dir", which gives access to the directory being read.</p>
<p>In addition, <a class="el" href="group__libssh__sftp.html#ga976ecf6f7d415856e1fd4a0f16ada9b8" title="Get a single file attributes structure of a directory.">sftp_readdir()</a> returns a "sftp_attributes" which is a pointer to a structure with informations about a directory entry:</p>
<ul>
<li>name: the name of the file or directory</li>
<li>size: its size in bytes</li>
<li>etc.</li>
</ul>
<p><a class="el" href="group__libssh__sftp.html#ga976ecf6f7d415856e1fd4a0f16ada9b8" title="Get a single file attributes structure of a directory.">sftp_readdir()</a> might return NULL under two conditions:</p>
<ul>
<li>when the end of the directory has been met</li>
<li>when an error occured</li>
</ul>
<p>To tell the difference, call <a class="el" href="group__libssh__sftp.html#gad60f8e71b06eb8fdae2b262bb58f8fec" title="Tell if the directory has reached EOF (End Of File).">sftp_dir_eof()</a>.</p>
<p>The attributes must be freed with <a class="el" href="group__libssh__sftp.html#gadee9f7af9fc1ad3a0a66c7d97bf7977c" title="Free a sftp attribute structure.">sftp_attributes_free()</a> when no longer needed.</p>
<p>The following example reads the contents of some remote directory:</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> sftp_list_dir(ssh_session session, sftp_session sftp)</div>
<div class="line">{</div>
<div class="line"> sftp_dir dir;</div>
<div class="line"> sftp_attributes attributes;</div>
<div class="line"> <span class="keywordtype">int</span> rc;</div>
<div class="line"></div>
<div class="line"> dir = <a class="code" href="group__libssh__sftp.html#gab4290874bdb55796b2823496e0d9b7ec" title="Open a directory used to obtain directory entries.">sftp_opendir</a>(sftp, <span class="stringliteral">"/var/log"</span>);</div>
<div class="line"> <span class="keywordflow">if</span> (!dir)</div>
<div class="line"> {</div>
<div class="line"> fprintf(stderr, <span class="stringliteral">"Directory not opened: %s\n"</span>, <a class="code" href="group__libssh__error.html#ga9241586665bf21f823806473fc386258" title="Retrieve the error text message from the last error.">ssh_get_error</a>(session));</div>
<div class="line"> <span class="keywordflow">return</span> SSH_ERROR;</div>
<div class="line"> }</div>
<div class="line"></div>
<div class="line"> printf(<span class="stringliteral">"Name Size Perms Owner\tGroup\n"</span>);</div>
<div class="line"></div>
<div class="line"> <span class="keywordflow">while</span> ((attributes = <a class="code" href="group__libssh__sftp.html#ga976ecf6f7d415856e1fd4a0f16ada9b8" title="Get a single file attributes structure of a directory.">sftp_readdir</a>(sftp, dir)) != NULL)</div>
<div class="line"> {</div>
<div class="line"> printf(<span class="stringliteral">"%-22s %10llu %.8o %s(%d)\t%s(%d)\n"</span>,</div>
<div class="line"> attributes->name,</div>
<div class="line"> (<span class="keywordtype">long</span> <span class="keywordtype">long</span> <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span>) attributes->size,</div>
<div class="line"> attributes->permissions,</div>
<div class="line"> attributes->owner,</div>
<div class="line"> attributes->uid,</div>
<div class="line"> attributes->group,</div>
<div class="line"> attributes->gid);</div>
<div class="line"></div>
<div class="line"> <a class="code" href="group__libssh__sftp.html#gadee9f7af9fc1ad3a0a66c7d97bf7977c" title="Free a sftp attribute structure.">sftp_attributes_free</a>(attributes);</div>
<div class="line"> }</div>
<div class="line"></div>
<div class="line"> <span class="keywordflow">if</span> (!<a class="code" href="group__libssh__sftp.html#gad60f8e71b06eb8fdae2b262bb58f8fec" title="Tell if the directory has reached EOF (End Of File).">sftp_dir_eof</a>(dir))</div>
<div class="line"> {</div>
<div class="line"> fprintf(stderr, <span class="stringliteral">"Can't list directory: %s\n"</span>, <a class="code" href="group__libssh__error.html#ga9241586665bf21f823806473fc386258" title="Retrieve the error text message from the last error.">ssh_get_error</a>(session));</div>
<div class="line"> <a class="code" href="group__libssh__sftp.html#ga35551e5b28b192ef8035628d347f7d3e" title="Close a directory handle opened by sftp_opendir().">sftp_closedir</a>(dir);</div>
<div class="line"> <span class="keywordflow">return</span> SSH_ERROR;</div>
<div class="line"> }</div>
<div class="line"></div>
<div class="line"> rc = <a class="code" href="group__libssh__sftp.html#ga35551e5b28b192ef8035628d347f7d3e" title="Close a directory handle opened by sftp_opendir().">sftp_closedir</a>(dir);</div>
<div class="line"> <span class="keywordflow">if</span> (rc != SSH_OK)</div>
<div class="line"> {</div>
<div class="line"> fprintf(stderr, <span class="stringliteral">"Can't close directory: %s\n"</span>, <a class="code" href="group__libssh__error.html#ga9241586665bf21f823806473fc386258" title="Retrieve the error text message from the last error.">ssh_get_error</a>(session));</div>
<div class="line"> <span class="keywordflow">return</span> rc;</div>
<div class="line"> }</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>
