<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="API documentation for the Rust `io` mod in crate `std`."><meta name="keywords" content="rust, rustlang, rust-lang, io"><title>std::io - Rust</title><link rel="stylesheet" type="text/css" href="../../normalize1.35.0.css"><link rel="stylesheet" type="text/css" href="../../rustdoc1.35.0.css" id="mainThemeStyle"><link rel="stylesheet" type="text/css" href="../../dark1.35.0.css"><link rel="stylesheet" type="text/css" href="../../light1.35.0.css" id="themeStyle"><script src="../../storage1.35.0.js"></script><noscript><link rel="stylesheet" href="../../noscript1.35.0.css"></noscript><link rel="shortcut icon" href="../../favicon1.35.0.ico"><style type="text/css">#crate-search{background-image:url("../../down-arrow1.35.0.svg");}</style></head><body class="rustdoc mod"><!--[if lte IE 8]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="sidebar"><div class="sidebar-menu">☰</div><a href='../../std/index.html'><img src='../../rust-logo1.35.0.png' alt='logo' width='100'></a><p class='location'>Module io</p><div class="sidebar-elems"><div class="block items"><ul><li><a href="#modules">Modules</a></li><li><a href="#structs">Structs</a></li><li><a href="#enums">Enums</a></li><li><a href="#traits">Traits</a></li><li><a href="#functions">Functions</a></li><li><a href="#types">Type Definitions</a></li></ul></div><p class='location'><a href='../index.html'>std</a></p><script>window.sidebarCurrent = {name: 'io', ty: 'mod', relpath: '../'};</script><script defer src="../sidebar-items.js"></script></div></nav><div class="theme-picker"><button id="theme-picker" aria-label="Pick another theme!"><img src="../../brush1.35.0.svg" width="18" alt="Pick another theme!"></button><div id="theme-choices"></div></div><script src="../../theme1.35.0.js"></script><nav class="sub"><form class="search-form js-only"><div class="search-container"><div><select id="crate-search"><option value="All crates">All crates</option></select><input class="search-input" name="search" autocomplete="off" spellcheck="false" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"></div><a id="settings-menu" href="../../settings.html"><img src="../../wheel1.35.0.svg" width="18" alt="Change settings"></a></div></form></nav><section id="main" class="content"><h1 class='fqn'><span class='out-of-band'><span class='since' title='Stable since Rust version 1.0.0'>1.0.0</span><span id='render-detail'><a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">[<span class='inner'>−</span>]</a></span><a class='srclink' href='../../src/std/io/mod.rs.html#1-2536' title='goto source code'>[src]</a></span><span class='in-band'>Module <a href='../index.html'>std</a>::<wbr><a class="mod" href=''>io</a></span></h1><div class='docblock'><p>Traits, helpers, and type definitions for core I/O functionality.</p>
<p>The <code>std::io</code> module contains a number of common things you'll need
when doing input and output. The most core part of this module is
the <a href="trait.Read.html"><code>Read</code></a> and <a href="trait.Write.html"><code>Write</code></a> traits, which provide the
most general interface for reading and writing input and output.</p>
<h1 id="read-and-write" class="section-header"><a href="#read-and-write">Read and Write</a></h1>
<p>Because they are traits, <a href="trait.Read.html"><code>Read</code></a> and <a href="trait.Write.html"><code>Write</code></a> are implemented by a number
of other types, and you can implement them for your types too. As such,
you'll see a few different types of I/O throughout the documentation in
this module: <a href="../fs/struct.File.html"><code>File</code></a>s, <a href="../net/struct.TcpStream.html"><code>TcpStream</code></a>s, and sometimes even <a href="../vec/struct.Vec.html"><code>Vec<T></code></a>s. For
example, <a href="trait.Read.html"><code>Read</code></a> adds a <a href="trait.Read.html#tymethod.read"><code>read</code></a> method, which we can use on
<a href="../fs/struct.File.html"><code>File</code></a>s:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">io</span>;
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">io</span>::<span class="ident">prelude</span>::<span class="kw-2">*</span>;
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">fs</span>::<span class="ident">File</span>;
<span class="kw">fn</span> <span class="ident">main</span>() <span class="op">-></span> <span class="ident">io</span>::<span class="prelude-ty">Result</span><span class="op"><</span>()<span class="op">></span> {
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">f</span> <span class="op">=</span> <span class="ident">File</span>::<span class="ident">open</span>(<span class="string">"foo.txt"</span>)<span class="question-mark">?</span>;
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">buffer</span> <span class="op">=</span> [<span class="number">0</span>; <span class="number">10</span>];
<span class="comment">// read up to 10 bytes</span>
<span class="kw">let</span> <span class="ident">n</span> <span class="op">=</span> <span class="ident">f</span>.<span class="ident">read</span>(<span class="kw-2">&</span><span class="kw-2">mut</span> <span class="ident">buffer</span>)<span class="question-mark">?</span>;
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"The bytes: {:?}"</span>, <span class="kw-2">&</span><span class="ident">buffer</span>[..<span class="ident">n</span>]);
<span class="prelude-val">Ok</span>(())
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Ause%20std%3A%3Aio%3B%0Ause%20std%3A%3Aio%3A%3Aprelude%3A%3A*%3B%0Ause%20std%3A%3Afs%3A%3AFile%3B%0A%0Afn%20main()%20-%3E%20io%3A%3AResult%3C()%3E%20%7B%0A%20%20%20%20let%20mut%20f%20%3D%20File%3A%3Aopen(%22foo.txt%22)%3F%3B%0A%20%20%20%20let%20mut%20buffer%20%3D%20%5B0%3B%2010%5D%3B%0A%0A%20%20%20%20%2F%2F%20read%20up%20to%2010%20bytes%0A%20%20%20%20let%20n%20%3D%20f.read(%26mut%20buffer)%3F%3B%0A%0A%20%20%20%20println!(%22The%20bytes%3A%20%7B%3A%3F%7D%22%2C%20%26buffer%5B..n%5D)%3B%0A%20%20%20%20Ok(())%0A%7D">Run</a></pre></div>
<p><a href="trait.Read.html"><code>Read</code></a> and <a href="trait.Write.html"><code>Write</code></a> are so important, implementors of the two traits have a
nickname: readers and writers. So you'll sometimes see 'a reader' instead
of 'a type that implements the <a href="trait.Read.html"><code>Read</code></a> trait'. Much easier!</p>
<h2 id="seek-and-bufread" class="section-header"><a href="#seek-and-bufread">Seek and BufRead</a></h2>
<p>Beyond that, there are two important traits that are provided: <a href="trait.Seek.html"><code>Seek</code></a>
and <a href="trait.BufRead.html"><code>BufRead</code></a>. Both of these build on top of a reader to control
how the reading happens. <a href="trait.Seek.html"><code>Seek</code></a> lets you control where the next byte is
coming from:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">io</span>;
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">io</span>::<span class="ident">prelude</span>::<span class="kw-2">*</span>;
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">io</span>::<span class="ident">SeekFrom</span>;
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">fs</span>::<span class="ident">File</span>;
<span class="kw">fn</span> <span class="ident">main</span>() <span class="op">-></span> <span class="ident">io</span>::<span class="prelude-ty">Result</span><span class="op"><</span>()<span class="op">></span> {
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">f</span> <span class="op">=</span> <span class="ident">File</span>::<span class="ident">open</span>(<span class="string">"foo.txt"</span>)<span class="question-mark">?</span>;
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">buffer</span> <span class="op">=</span> [<span class="number">0</span>; <span class="number">10</span>];
<span class="comment">// skip to the last 10 bytes of the file</span>
<span class="ident">f</span>.<span class="ident">seek</span>(<span class="ident">SeekFrom</span>::<span class="ident">End</span>(<span class="op">-</span><span class="number">10</span>))<span class="question-mark">?</span>;
<span class="comment">// read up to 10 bytes</span>
<span class="kw">let</span> <span class="ident">n</span> <span class="op">=</span> <span class="ident">f</span>.<span class="ident">read</span>(<span class="kw-2">&</span><span class="kw-2">mut</span> <span class="ident">buffer</span>)<span class="question-mark">?</span>;
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"The bytes: {:?}"</span>, <span class="kw-2">&</span><span class="ident">buffer</span>[..<span class="ident">n</span>]);
<span class="prelude-val">Ok</span>(())
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Ause%20std%3A%3Aio%3B%0Ause%20std%3A%3Aio%3A%3Aprelude%3A%3A*%3B%0Ause%20std%3A%3Aio%3A%3ASeekFrom%3B%0Ause%20std%3A%3Afs%3A%3AFile%3B%0A%0Afn%20main()%20-%3E%20io%3A%3AResult%3C()%3E%20%7B%0A%20%20%20%20let%20mut%20f%20%3D%20File%3A%3Aopen(%22foo.txt%22)%3F%3B%0A%20%20%20%20let%20mut%20buffer%20%3D%20%5B0%3B%2010%5D%3B%0A%0A%20%20%20%20%2F%2F%20skip%20to%20the%20last%2010%20bytes%20of%20the%20file%0A%20%20%20%20f.seek(SeekFrom%3A%3AEnd(-10))%3F%3B%0A%0A%20%20%20%20%2F%2F%20read%20up%20to%2010%20bytes%0A%20%20%20%20let%20n%20%3D%20f.read(%26mut%20buffer)%3F%3B%0A%0A%20%20%20%20println!(%22The%20bytes%3A%20%7B%3A%3F%7D%22%2C%20%26buffer%5B..n%5D)%3B%0A%20%20%20%20Ok(())%0A%7D">Run</a></pre></div>
<p><a href="trait.BufRead.html"><code>BufRead</code></a> uses an internal buffer to provide a number of other ways to read, but
to show it off, we'll need to talk about buffers in general. Keep reading!</p>
<h2 id="bufreader-and-bufwriter" class="section-header"><a href="#bufreader-and-bufwriter">BufReader and BufWriter</a></h2>
<p>Byte-based interfaces are unwieldy and can be inefficient, as we'd need to be
making near-constant calls to the operating system. To help with this,
<code>std::io</code> comes with two structs, <a href="struct.BufReader.html"><code>BufReader</code></a> and <a href="struct.BufWriter.html"><code>BufWriter</code></a>, which wrap
readers and writers. The wrapper uses a buffer, reducing the number of
calls and providing nicer methods for accessing exactly what you want.</p>
<p>For example, <a href="struct.BufReader.html"><code>BufReader</code></a> works with the <a href="trait.BufRead.html"><code>BufRead</code></a> trait to add extra
methods to any reader:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">io</span>;
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">io</span>::<span class="ident">prelude</span>::<span class="kw-2">*</span>;
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">io</span>::<span class="ident">BufReader</span>;
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">fs</span>::<span class="ident">File</span>;
<span class="kw">fn</span> <span class="ident">main</span>() <span class="op">-></span> <span class="ident">io</span>::<span class="prelude-ty">Result</span><span class="op"><</span>()<span class="op">></span> {
<span class="kw">let</span> <span class="ident">f</span> <span class="op">=</span> <span class="ident">File</span>::<span class="ident">open</span>(<span class="string">"foo.txt"</span>)<span class="question-mark">?</span>;
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">reader</span> <span class="op">=</span> <span class="ident">BufReader</span>::<span class="ident">new</span>(<span class="ident">f</span>);
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">buffer</span> <span class="op">=</span> <span class="ident">String</span>::<span class="ident">new</span>();
<span class="comment">// read a line into buffer</span>
<span class="ident">reader</span>.<span class="ident">read_line</span>(<span class="kw-2">&</span><span class="kw-2">mut</span> <span class="ident">buffer</span>)<span class="question-mark">?</span>;
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"{}"</span>, <span class="ident">buffer</span>);
<span class="prelude-val">Ok</span>(())
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Ause%20std%3A%3Aio%3B%0Ause%20std%3A%3Aio%3A%3Aprelude%3A%3A*%3B%0Ause%20std%3A%3Aio%3A%3ABufReader%3B%0Ause%20std%3A%3Afs%3A%3AFile%3B%0A%0Afn%20main()%20-%3E%20io%3A%3AResult%3C()%3E%20%7B%0A%20%20%20%20let%20f%20%3D%20File%3A%3Aopen(%22foo.txt%22)%3F%3B%0A%20%20%20%20let%20mut%20reader%20%3D%20BufReader%3A%3Anew(f)%3B%0A%20%20%20%20let%20mut%20buffer%20%3D%20String%3A%3Anew()%3B%0A%0A%20%20%20%20%2F%2F%20read%20a%20line%20into%20buffer%0A%20%20%20%20reader.read_line(%26mut%20buffer)%3F%3B%0A%0A%20%20%20%20println!(%22%7B%7D%22%2C%20buffer)%3B%0A%20%20%20%20Ok(())%0A%7D">Run</a></pre></div>
<p><a href="struct.BufWriter.html"><code>BufWriter</code></a> doesn't add any new ways of writing; it just buffers every call
to <a href="trait.Write.html#tymethod.write"><code>write</code></a>:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">io</span>;
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">io</span>::<span class="ident">prelude</span>::<span class="kw-2">*</span>;
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">io</span>::<span class="ident">BufWriter</span>;
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">fs</span>::<span class="ident">File</span>;
<span class="kw">fn</span> <span class="ident">main</span>() <span class="op">-></span> <span class="ident">io</span>::<span class="prelude-ty">Result</span><span class="op"><</span>()<span class="op">></span> {
<span class="kw">let</span> <span class="ident">f</span> <span class="op">=</span> <span class="ident">File</span>::<span class="ident">create</span>(<span class="string">"foo.txt"</span>)<span class="question-mark">?</span>;
{
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">writer</span> <span class="op">=</span> <span class="ident">BufWriter</span>::<span class="ident">new</span>(<span class="ident">f</span>);
<span class="comment">// write a byte to the buffer</span>
<span class="ident">writer</span>.<span class="ident">write</span>(<span class="kw-2">&</span>[<span class="number">42</span>])<span class="question-mark">?</span>;
} <span class="comment">// the buffer is flushed once writer goes out of scope</span>
<span class="prelude-val">Ok</span>(())
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Ause%20std%3A%3Aio%3B%0Ause%20std%3A%3Aio%3A%3Aprelude%3A%3A*%3B%0Ause%20std%3A%3Aio%3A%3ABufWriter%3B%0Ause%20std%3A%3Afs%3A%3AFile%3B%0A%0Afn%20main()%20-%3E%20io%3A%3AResult%3C()%3E%20%7B%0A%20%20%20%20let%20f%20%3D%20File%3A%3Acreate(%22foo.txt%22)%3F%3B%0A%20%20%20%20%7B%0A%20%20%20%20%20%20%20%20let%20mut%20writer%20%3D%20BufWriter%3A%3Anew(f)%3B%0A%0A%20%20%20%20%20%20%20%20%2F%2F%20write%20a%20byte%20to%20the%20buffer%0A%20%20%20%20%20%20%20%20writer.write(%26%5B42%5D)%3F%3B%0A%0A%20%20%20%20%7D%20%2F%2F%20the%20buffer%20is%20flushed%20once%20writer%20goes%20out%20of%20scope%0A%0A%20%20%20%20Ok(())%0A%7D">Run</a></pre></div>
<h2 id="standard-input-and-output" class="section-header"><a href="#standard-input-and-output">Standard input and output</a></h2>
<p>A very common source of input is standard input:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">io</span>;
<span class="kw">fn</span> <span class="ident">main</span>() <span class="op">-></span> <span class="ident">io</span>::<span class="prelude-ty">Result</span><span class="op"><</span>()<span class="op">></span> {
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">input</span> <span class="op">=</span> <span class="ident">String</span>::<span class="ident">new</span>();
<span class="ident">io</span>::<span class="ident">stdin</span>().<span class="ident">read_line</span>(<span class="kw-2">&</span><span class="kw-2">mut</span> <span class="ident">input</span>)<span class="question-mark">?</span>;
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"You typed: {}"</span>, <span class="ident">input</span>.<span class="ident">trim</span>());
<span class="prelude-val">Ok</span>(())
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Ause%20std%3A%3Aio%3B%0A%0Afn%20main()%20-%3E%20io%3A%3AResult%3C()%3E%20%7B%0A%20%20%20%20let%20mut%20input%20%3D%20String%3A%3Anew()%3B%0A%0A%20%20%20%20io%3A%3Astdin().read_line(%26mut%20input)%3F%3B%0A%0A%20%20%20%20println!(%22You%20typed%3A%20%7B%7D%22%2C%20input.trim())%3B%0A%20%20%20%20Ok(())%0A%7D">Run</a></pre></div>
<p>Note that you cannot use the <a href="../../book/appendix-02-operators.html"><code>?</code> operator</a> in functions that do not return
a <a href="../result/enum.Result.html"><code>Result<T, E></code></a>. Instead, you can call <a href="../result/enum.Result.html#method.unwrap"><code>.unwrap()</code></a>
or <code>match</code> on the return value to catch any possible errors:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">io</span>;
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">input</span> <span class="op">=</span> <span class="ident">String</span>::<span class="ident">new</span>();
<span class="ident">io</span>::<span class="ident">stdin</span>().<span class="ident">read_line</span>(<span class="kw-2">&</span><span class="kw-2">mut</span> <span class="ident">input</span>).<span class="ident">unwrap</span>();<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Afn%20main()%20%7B%0Ause%20std%3A%3Aio%3B%0A%0Alet%20mut%20input%20%3D%20String%3A%3Anew()%3B%0A%0Aio%3A%3Astdin().read_line(%26mut%20input).unwrap()%3B%0A%7D">Run</a></pre></div>
<p>And a very common source of output is standard output:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">io</span>;
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">io</span>::<span class="ident">prelude</span>::<span class="kw-2">*</span>;
<span class="kw">fn</span> <span class="ident">main</span>() <span class="op">-></span> <span class="ident">io</span>::<span class="prelude-ty">Result</span><span class="op"><</span>()<span class="op">></span> {
<span class="ident">io</span>::<span class="ident">stdout</span>().<span class="ident">write</span>(<span class="kw-2">&</span>[<span class="number">42</span>])<span class="question-mark">?</span>;
<span class="prelude-val">Ok</span>(())
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Ause%20std%3A%3Aio%3B%0Ause%20std%3A%3Aio%3A%3Aprelude%3A%3A*%3B%0A%0Afn%20main()%20-%3E%20io%3A%3AResult%3C()%3E%20%7B%0A%20%20%20%20io%3A%3Astdout().write(%26%5B42%5D)%3F%3B%0A%20%20%20%20Ok(())%0A%7D">Run</a></pre></div>
<p>Of course, using <a href="fn.stdout.html"><code>io::stdout</code></a> directly is less common than something like
<a href="../macro.println.html"><code>println!</code></a>.</p>
<h2 id="iterator-types" class="section-header"><a href="#iterator-types">Iterator types</a></h2>
<p>A large number of the structures provided by <code>std::io</code> are for various
ways of iterating over I/O. For example, <a href="struct.Lines.html"><code>Lines</code></a> is used to split over
lines:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">io</span>;
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">io</span>::<span class="ident">prelude</span>::<span class="kw-2">*</span>;
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">io</span>::<span class="ident">BufReader</span>;
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">fs</span>::<span class="ident">File</span>;
<span class="kw">fn</span> <span class="ident">main</span>() <span class="op">-></span> <span class="ident">io</span>::<span class="prelude-ty">Result</span><span class="op"><</span>()<span class="op">></span> {
<span class="kw">let</span> <span class="ident">f</span> <span class="op">=</span> <span class="ident">File</span>::<span class="ident">open</span>(<span class="string">"foo.txt"</span>)<span class="question-mark">?</span>;
<span class="kw">let</span> <span class="ident">reader</span> <span class="op">=</span> <span class="ident">BufReader</span>::<span class="ident">new</span>(<span class="ident">f</span>);
<span class="kw">for</span> <span class="ident">line</span> <span class="kw">in</span> <span class="ident">reader</span>.<span class="ident">lines</span>() {
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"{}"</span>, <span class="ident">line</span><span class="question-mark">?</span>);
}
<span class="prelude-val">Ok</span>(())
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Ause%20std%3A%3Aio%3B%0Ause%20std%3A%3Aio%3A%3Aprelude%3A%3A*%3B%0Ause%20std%3A%3Aio%3A%3ABufReader%3B%0Ause%20std%3A%3Afs%3A%3AFile%3B%0A%0Afn%20main()%20-%3E%20io%3A%3AResult%3C()%3E%20%7B%0A%20%20%20%20let%20f%20%3D%20File%3A%3Aopen(%22foo.txt%22)%3F%3B%0A%20%20%20%20let%20reader%20%3D%20BufReader%3A%3Anew(f)%3B%0A%0A%20%20%20%20for%20line%20in%20reader.lines()%20%7B%0A%20%20%20%20%20%20%20%20println!(%22%7B%7D%22%2C%20line%3F)%3B%0A%20%20%20%20%7D%0A%20%20%20%20Ok(())%0A%7D">Run</a></pre></div>
<h2 id="functions" class="section-header"><a href="#functions">Functions</a></h2>
<p>There are a number of <a href="#functions-1">functions</a> that offer access to various
features. For example, we can use three of these functions to copy everything
from standard input to standard output:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">io</span>;
<span class="kw">fn</span> <span class="ident">main</span>() <span class="op">-></span> <span class="ident">io</span>::<span class="prelude-ty">Result</span><span class="op"><</span>()<span class="op">></span> {
<span class="ident">io</span>::<span class="ident">copy</span>(<span class="kw-2">&</span><span class="kw-2">mut</span> <span class="ident">io</span>::<span class="ident">stdin</span>(), <span class="kw-2">&</span><span class="kw-2">mut</span> <span class="ident">io</span>::<span class="ident">stdout</span>())<span class="question-mark">?</span>;
<span class="prelude-val">Ok</span>(())
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Ause%20std%3A%3Aio%3B%0A%0Afn%20main()%20-%3E%20io%3A%3AResult%3C()%3E%20%7B%0A%20%20%20%20io%3A%3Acopy(%26mut%20io%3A%3Astdin()%2C%20%26mut%20io%3A%3Astdout())%3F%3B%0A%20%20%20%20Ok(())%0A%7D">Run</a></pre></div>
<h2 id="ioresult" class="section-header"><a href="#ioresult">io::Result</a></h2>
<p>Last, but certainly not least, is <a href="type.Result.html"><code>io::Result</code></a>. This type is used
as the return type of many <code>std::io</code> functions that can cause an error, and
can be returned from your own functions as well. Many of the examples in this
module use the <a href="../../book/appendix-02-operators.html"><code>?</code> operator</a>:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">io</span>;
<span class="kw">fn</span> <span class="ident">read_input</span>() <span class="op">-></span> <span class="ident">io</span>::<span class="prelude-ty">Result</span><span class="op"><</span>()<span class="op">></span> {
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">input</span> <span class="op">=</span> <span class="ident">String</span>::<span class="ident">new</span>();
<span class="ident">io</span>::<span class="ident">stdin</span>().<span class="ident">read_line</span>(<span class="kw-2">&</span><span class="kw-2">mut</span> <span class="ident">input</span>)<span class="question-mark">?</span>;
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"You typed: {}"</span>, <span class="ident">input</span>.<span class="ident">trim</span>());
<span class="prelude-val">Ok</span>(())
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Afn%20main()%20%7B%0Ause%20std%3A%3Aio%3B%0A%0Afn%20read_input()%20-%3E%20io%3A%3AResult%3C()%3E%20%7B%0A%20%20%20%20let%20mut%20input%20%3D%20String%3A%3Anew()%3B%0A%0A%20%20%20%20io%3A%3Astdin().read_line(%26mut%20input)%3F%3B%0A%0A%20%20%20%20println!(%22You%20typed%3A%20%7B%7D%22%2C%20input.trim())%3B%0A%0A%20%20%20%20Ok(())%0A%7D%0A%7D">Run</a></pre></div>
<p>The return type of <code>read_input()</code>, <a href="type.Result.html"><code>io::Result<()></code></a>, is a very
common type for functions which don't have a 'real' return value, but do want to
return errors if they happen. In this case, the only purpose of this function is
to read the line and print it, so we use <code>()</code>.</p>
<h2 id="platform-specific-behavior" class="section-header"><a href="#platform-specific-behavior">Platform-specific behavior</a></h2>
<p>Many I/O functions throughout the standard library are documented to indicate
what various library or syscalls they are delegated to. This is done to help
applications both understand what's happening under the hood as well as investigate
any possibly unclear semantics. Note, however, that this is informative, not a binding
contract. The implementation of many of these functions are subject to change over
time and may call fewer or more syscalls/library functions.</p>
</div><h2 id='modules' class='section-header'><a href="#modules">Modules</a></h2>
<table><tr class='module-item'><td><a class="mod" href="prelude/index.html" title='std::io::prelude mod'>prelude</a></td><td class='docblock-short'><p>The I/O Prelude</p>
</td></tr></table><h2 id='structs' class='section-header'><a href="#structs">Structs</a></h2>
<table><tr class='module-item'><td><a class="struct" href="struct.BufReader.html" title='std::io::BufReader struct'>BufReader</a></td><td class='docblock-short'><p>The <code>BufReader</code> struct adds buffering to any reader.</p>
</td></tr><tr class='module-item'><td><a class="struct" href="struct.BufWriter.html" title='std::io::BufWriter struct'>BufWriter</a></td><td class='docblock-short'><p>Wraps a writer and buffers its output.</p>
</td></tr><tr class='module-item'><td><a class="struct" href="struct.Bytes.html" title='std::io::Bytes struct'>Bytes</a></td><td class='docblock-short'><p>An iterator over <code>u8</code> values of a reader.</p>
</td></tr><tr class='module-item'><td><a class="struct" href="struct.Chain.html" title='std::io::Chain struct'>Chain</a></td><td class='docblock-short'><p>Adaptor to chain together two readers.</p>
</td></tr><tr class='module-item'><td><a class="struct" href="struct.Cursor.html" title='std::io::Cursor struct'>Cursor</a></td><td class='docblock-short'><p>A <code>Cursor</code> wraps an in-memory buffer and provides it with a
<a href="trait.Seek.html"><code>Seek</code></a> implementation.</p>
</td></tr><tr class='module-item'><td><a class="struct" href="struct.Empty.html" title='std::io::Empty struct'>Empty</a></td><td class='docblock-short'><p>A reader which is always at EOF.</p>
</td></tr><tr class='module-item'><td><a class="struct" href="struct.Error.html" title='std::io::Error struct'>Error</a></td><td class='docblock-short'><p>The error type for I/O operations of the <a href="../io/trait.Read.html"><code>Read</code></a>, <a href="../io/trait.Write.html"><code>Write</code></a>, <a href="../io/trait.Seek.html"><code>Seek</code></a>, and
associated traits.</p>
</td></tr><tr class='module-item'><td><a class="struct" href="struct.IntoInnerError.html" title='std::io::IntoInnerError struct'>IntoInnerError</a></td><td class='docblock-short'><p>An error returned by <code>into_inner</code> which combines an error that
happened while writing out the buffer, and the buffered writer object
which may be used to recover from the condition.</p>
</td></tr><tr class='module-item'><td><a class="struct" href="struct.LineWriter.html" title='std::io::LineWriter struct'>LineWriter</a></td><td class='docblock-short'><p>Wraps a writer and buffers output to it, flushing whenever a newline
(<code>0x0a</code>, <code>'\n'</code>) is detected.</p>
</td></tr><tr class='module-item'><td><a class="struct" href="struct.Lines.html" title='std::io::Lines struct'>Lines</a></td><td class='docblock-short'><p>An iterator over the lines of an instance of <code>BufRead</code>.</p>
</td></tr><tr class='module-item'><td><a class="struct" href="struct.Repeat.html" title='std::io::Repeat struct'>Repeat</a></td><td class='docblock-short'><p>A reader which yields one byte over and over and over and over and over and...</p>
</td></tr><tr class='module-item'><td><a class="struct" href="struct.Sink.html" title='std::io::Sink struct'>Sink</a></td><td class='docblock-short'><p>A writer which will move data into the void.</p>
</td></tr><tr class='module-item'><td><a class="struct" href="struct.Split.html" title='std::io::Split struct'>Split</a></td><td class='docblock-short'><p>An iterator over the contents of an instance of <code>BufRead</code> split on a
particular byte.</p>
</td></tr><tr class='module-item'><td><a class="struct" href="struct.Stderr.html" title='std::io::Stderr struct'>Stderr</a></td><td class='docblock-short'><p>A handle to the standard error stream of a process.</p>
</td></tr><tr class='module-item'><td><a class="struct" href="struct.StderrLock.html" title='std::io::StderrLock struct'>StderrLock</a></td><td class='docblock-short'><p>A locked reference to the <code>Stderr</code> handle.</p>
</td></tr><tr class='module-item'><td><a class="struct" href="struct.Stdin.html" title='std::io::Stdin struct'>Stdin</a></td><td class='docblock-short'><p>A handle to the standard input stream of a process.</p>
</td></tr><tr class='module-item'><td><a class="struct" href="struct.StdinLock.html" title='std::io::StdinLock struct'>StdinLock</a></td><td class='docblock-short'><p>A locked reference to the <code>Stdin</code> handle.</p>
</td></tr><tr class='module-item'><td><a class="struct" href="struct.Stdout.html" title='std::io::Stdout struct'>Stdout</a></td><td class='docblock-short'><p>A handle to the global standard output stream of the current process.</p>
</td></tr><tr class='module-item'><td><a class="struct" href="struct.StdoutLock.html" title='std::io::StdoutLock struct'>StdoutLock</a></td><td class='docblock-short'><p>A locked reference to the <code>Stdout</code> handle.</p>
</td></tr><tr class='module-item'><td><a class="struct" href="struct.Take.html" title='std::io::Take struct'>Take</a></td><td class='docblock-short'><p>Reader adaptor which limits the bytes read from an underlying reader.</p>
</td></tr><tr class='unstable module-item'><td><a class="struct" href="struct.Initializer.html" title='std::io::Initializer struct'>Initializer</a></td><td class='docblock-short'><span class="stab unstable">Experimental</span><p>A type used to conditionally initialize buffers passed to <code>Read</code> methods.</p>
</td></tr><tr class='unstable module-item'><td><a class="struct" href="struct.IoVec.html" title='std::io::IoVec struct'>IoVec</a></td><td class='docblock-short'><span class="stab unstable">Experimental</span><p>A buffer type used with <code>Write::write_vectored</code>.</p>
</td></tr><tr class='unstable module-item'><td><a class="struct" href="struct.IoVecMut.html" title='std::io::IoVecMut struct'>IoVecMut</a></td><td class='docblock-short'><span class="stab unstable">Experimental</span><p>A buffer type used with <code>Read::read_vectored</code>.</p>
</td></tr></table><h2 id='enums' class='section-header'><a href="#enums">Enums</a></h2>
<table><tr class='module-item'><td><a class="enum" href="enum.ErrorKind.html" title='std::io::ErrorKind enum'>ErrorKind</a></td><td class='docblock-short'><p>A list specifying general categories of I/O error.</p>
</td></tr><tr class='module-item'><td><a class="enum" href="enum.SeekFrom.html" title='std::io::SeekFrom enum'>SeekFrom</a></td><td class='docblock-short'><p>Enumeration of possible methods to seek within an I/O object.</p>
</td></tr></table><h2 id='traits' class='section-header'><a href="#traits">Traits</a></h2>
<table><tr class='module-item'><td><a class="trait" href="trait.BufRead.html" title='std::io::BufRead trait'>BufRead</a></td><td class='docblock-short'><p>A <code>BufRead</code> is a type of <code>Read</code>er which has an internal buffer, allowing it
to perform extra ways of reading.</p>
</td></tr><tr class='module-item'><td><a class="trait" href="trait.Read.html" title='std::io::Read trait'>Read</a></td><td class='docblock-short'><p>The <code>Read</code> trait allows for reading bytes from a source.</p>
</td></tr><tr class='module-item'><td><a class="trait" href="trait.Seek.html" title='std::io::Seek trait'>Seek</a></td><td class='docblock-short'><p>The <code>Seek</code> trait provides a cursor which can be moved within a stream of
bytes.</p>
</td></tr><tr class='module-item'><td><a class="trait" href="trait.Write.html" title='std::io::Write trait'>Write</a></td><td class='docblock-short'><p>A trait for objects which are byte-oriented sinks.</p>
</td></tr></table><h2 id='functions-1' class='section-header'><a href="#functions-1">Functions</a></h2>
<table><tr class='module-item'><td><a class="fn" href="fn.copy.html" title='std::io::copy fn'>copy</a></td><td class='docblock-short'><p>Copies the entire contents of a reader into a writer.</p>
</td></tr><tr class='module-item'><td><a class="fn" href="fn.empty.html" title='std::io::empty fn'>empty</a></td><td class='docblock-short'><p>Constructs a new handle to an empty reader.</p>
</td></tr><tr class='module-item'><td><a class="fn" href="fn.repeat.html" title='std::io::repeat fn'>repeat</a></td><td class='docblock-short'><p>Creates an instance of a reader that infinitely repeats one byte.</p>
</td></tr><tr class='module-item'><td><a class="fn" href="fn.sink.html" title='std::io::sink fn'>sink</a></td><td class='docblock-short'><p>Creates an instance of a writer which will successfully consume all data.</p>
</td></tr><tr class='module-item'><td><a class="fn" href="fn.stderr.html" title='std::io::stderr fn'>stderr</a></td><td class='docblock-short'><p>Constructs a new handle to the standard error of the current process.</p>
</td></tr><tr class='module-item'><td><a class="fn" href="fn.stdin.html" title='std::io::stdin fn'>stdin</a></td><td class='docblock-short'><p>Constructs a new handle to the standard input of the current process.</p>
</td></tr><tr class='module-item'><td><a class="fn" href="fn.stdout.html" title='std::io::stdout fn'>stdout</a></td><td class='docblock-short'><p>Constructs a new handle to the standard output of the current process.</p>
</td></tr></table><h2 id='types' class='section-header'><a href="#types">Type Definitions</a></h2>
<table><tr class='module-item'><td><a class="type" href="type.Result.html" title='std::io::Result type'>Result</a></td><td class='docblock-short'><p>A specialized <a href="../result/enum.Result.html"><code>Result</code></a> type for I/O
operations.</p>
</td></tr></table></section><section id="search" class="content hidden"></section><section class="footer"></section><aside id="help" class="hidden"><div><h1 class="hidden">Help</h1><div class="shortcuts"><h2>Keyboard Shortcuts</h2><dl><dt><kbd>?</kbd></dt><dd>Show this help dialog</dd><dt><kbd>S</kbd></dt><dd>Focus the search field</dd><dt><kbd>↑</kbd></dt><dd>Move up in search results</dd><dt><kbd>↓</kbd></dt><dd>Move down in search results</dd><dt><kbd>↹</kbd></dt><dd>Switch tab</dd><dt><kbd>⏎</kbd></dt><dd>Go to active search result</dd><dt><kbd>+</kbd></dt><dd>Expand all sections</dd><dt><kbd>-</kbd></dt><dd>Collapse all sections</dd></dl></div><div class="infos"><h2>Search Tricks</h2><p>Prefix searches with a type followed by a colon (e.g., <code>fn:</code>) to restrict the search to a given type.</p><p>Accepted types are: <code>fn</code>, <code>mod</code>, <code>struct</code>, <code>enum</code>, <code>trait</code>, <code>type</code>, <code>macro</code>, and <code>const</code>.</p><p>Search functions by type signature (e.g., <code>vec -> usize</code> or <code>* -> vec</code>)</p><p>Search multiple things at once by splitting your query with comma (e.g., <code>str,u8</code> or <code>String,struct:Vec,test</code>)</p></div></div></aside><script>window.rootPath = "../../";window.currentCrate = "std";</script><script src="../../aliases.js"></script><script src="../../main1.35.0.js"></script><script defer src="../../search-index.js"></script></body></html>
distrib
>
Mageia
>
7
>
armv7hl
>
media
>
core-release
>
by-pkgid
>
0c2243f8a1696816431e7210e991fa52
>
files
>
15578
