sascha
/
difftastic
mirror of https://github.com/Wilfred/difftastic/
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
difftastic/rustdoc/rustix/ioctl/trait.Ioctl.html

62 lines
20 KiB
HTML
Raw Permalink Blame History Unescape Escape

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

<!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="A trait defining the properties of an `ioctl` command."><title>Ioctl in rustix::ioctl - Rust</title><link rel="preload" as="font" type="font/woff2" crossorigin href="../../static.files/SourceSerif4-Regular-46f98efaafac5295.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../static.files/FiraSans-Regular-018c141bf0843ffd.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../static.files/FiraSans-Medium-8f9a781e4970d388.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../static.files/SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../static.files/SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2"><link rel="stylesheet" href="../../static.files/normalize-76eba96aa4d2e634.css"><link rel="stylesheet" href="../../static.files/rustdoc-ac92e1bbe349e143.css"><meta name="rustdoc-vars" data-root-path="../../" data-static-root-path="../../static.files/" data-current-crate="rustix" data-themes="" data-resource-suffix="" data-rustdoc-version="1.76.0 (07dca489a 2024-02-04)" data-channel="1.76.0" data-search-js="search-2b6ce74ff89ae146.js" data-settings-js="settings-4313503d2e1961c2.js" ><script src="../../static.files/storage-f2adc0d6ca4d09fb.js"></script><script defer src="sidebar-items.js"></script><script defer src="../../static.files/main-305769736d49e732.js"></script><noscript><link rel="stylesheet" href="../../static.files/noscript-feafe1bb7466e4bd.css"></noscript><link rel="alternate icon" type="image/png" href="../../static.files/favicon-16x16-8b506e7a72182f1c.png"><link rel="alternate icon" type="image/png" href="../../static.files/favicon-32x32-422f7d1d52889060.png"><link rel="icon" type="image/svg+xml" href="../../static.files/favicon-2c020d218678b618.svg"></head><body class="rustdoc trait"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle">&#9776;</button></nav><nav class="sidebar"><div class="sidebar-crate"><h2><a href="../../rustix/index.html">rustix</a><span class="version">0.38.34</span></h2></div><h2 class="location"><a href="#">Ioctl</a></h2><div class="sidebar-elems"><section><h3><a href="#required-associated-types">Required Associated Types</a></h3><ul class="block"><li><a href="#associatedtype.Output">Output</a></li></ul><h3><a href="#required-associated-consts">Required Associated Constants</a></h3><ul class="block"><li><a href="#associatedconstant.IS_MUTATING">IS_MUTATING</a></li><li><a href="#associatedconstant.OPCODE">OPCODE</a></li></ul><h3><a href="#required-methods">Required Methods</a></h3><ul class="block"><li><a href="#tymethod.as_ptr">as_ptr</a></li><li><a href="#tymethod.output_from_ptr">output_from_ptr</a></li></ul><h3><a href="#object-safety">Object Safety</a></h3><h3><a href="#implementors">Implementors</a></h3></section><h2><a href="index.html">In rustix::ioctl</a></h2></div></nav><div class="sidebar-resizer"></div>
<main><div class="width-limiter"><nav class="sub"><form class="search-form"><span></span><div id="sidebar-button" tabindex="-1"><a href="../../rustix/all.html" title="show sidebar"></a></div><input class="search-input" name="search" aria-label="Run search in the documentation" autocomplete="off" spellcheck="false" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"><div id="help-button" tabindex="-1"><a href="../../help.html" title="help">?</a></div><div id="settings-menu" tabindex="-1"><a href="../../settings.html" title="settings"><img width="22" height="22" alt="Change settings" src="../../static.files/wheel-7b819b6101059cd0.svg"></a></div></form></nav><section id="main-content" class="content"><div class="main-heading"><h1>Trait <a href="../index.html">rustix</a>::<wbr><a href="index.html">ioctl</a>::<wbr><a class="trait" href="#">Ioctl</a><button id="copy-path" title="Copy item path to clipboard"><img src="../../static.files/clipboard-7571035ce49a181d.svg" width="19" height="18" alt="Copy item path"></button></h1><span class="out-of-band"><a class="src" href="../../src/rustix/ioctl/mod.rs.html#146-189">source</a> · <button id="toggle-all-docs" title="collapse all docs">[<span>&#x2212;</span>]</button></span></div><pre class="rust item-decl"><code>pub unsafe trait Ioctl {
type <a href="#associatedtype.Output" class="associatedtype">Output</a>;
const <a href="#associatedconstant.OPCODE" class="constant">OPCODE</a>: <a class="struct" href="struct.Opcode.html" title="struct rustix::ioctl::Opcode">Opcode</a>;
const <a href="#associatedconstant.IS_MUTATING" class="constant">IS_MUTATING</a>: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.bool.html">bool</a>;
// Required methods
fn <a href="#tymethod.as_ptr" class="fn">as_ptr</a>(&amp;mut self) -&gt; <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.pointer.html">*mut </a><a class="enum" href="https://doc.rust-lang.org/1.76.0/core/ffi/enum.c_void.html" title="enum core::ffi::c_void">c_void</a>;
<span class="item-spacer"></span> unsafe fn <a href="#tymethod.output_from_ptr" class="fn">output_from_ptr</a>(
out: <a class="type" href="type.IoctlOutput.html" title="type rustix::ioctl::IoctlOutput">IoctlOutput</a>,
extract_output: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.pointer.html">*mut </a><a class="enum" href="https://doc.rust-lang.org/1.76.0/core/ffi/enum.c_void.html" title="enum core::ffi::c_void">c_void</a>
) -&gt; <a class="type" href="../io/type.Result.html" title="type rustix::io::Result">Result</a>&lt;Self::<a class="associatedtype" href="trait.Ioctl.html#associatedtype.Output" title="type rustix::ioctl::Ioctl::Output">Output</a>&gt;;
}</code></pre><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>A trait defining the properties of an <code>ioctl</code> command.</p>
<p>Objects implementing this trait can be passed to <a href="fn.ioctl.html" title="fn rustix::ioctl::ioctl"><code>ioctl</code></a> to make an
<code>ioctl</code> call. The contents of the object represent the inputs to the
<code>ioctl</code> call. The inputs must be convertible to a pointer through the
<code>as_ptr</code> method. In most cases, this involves either casting a number to a
pointer, or creating a pointer to the actual data. The latter case is
necessary for <code>ioctl</code> calls that modify userspace data.</p>
<h2 id="safety"><a href="#safety">Safety</a></h2>
<p>This trait is unsafe to implement because it is impossible to guarantee
that the <code>ioctl</code> call is safe. The <code>ioctl</code> call may be proprietary, or it
may be unsafe to call in certain circumstances.</p>
<p>By implementing this trait, you guarantee that:</p>
<ul>
<li>The <code>ioctl</code> call expects the input provided by <code>as_ptr</code> and produces the
output as indicated by <code>output</code>.</li>
<li>That <code>output_from_ptr</code> can safely take the pointer from <code>as_ptr</code> and cast
it to the correct type, <em>only</em> after the <code>ioctl</code> call.</li>
<li>That <code>OPCODE</code> uniquely identifies the <code>ioctl</code> call.</li>
<li>That, for whatever platforms you are targeting, the <code>ioctl</code> call is safe
to make.</li>
<li>If <code>IS_MUTATING</code> is false, that no userspace data will be modified by the
<code>ioctl</code> call.</li>
</ul>
</div></details><h2 id="required-associated-types" class="section-header">Required Associated Types<a href="#required-associated-types" class="anchor">§</a></h2><div class="methods"><details class="toggle" open><summary><section id="associatedtype.Output" class="method"><a class="src rightside" href="../../src/rustix/ioctl/mod.rs.html#151">source</a><h4 class="code-header">type <a href="#associatedtype.Output" class="associatedtype">Output</a></h4></section></summary><div class="docblock"><p>The type of the output data.</p>
<p>Given a pointer, one should be able to construct an instance of this
type.</p>
</div></details></div><h2 id="required-associated-consts" class="section-header">Required Associated Constants<a href="#required-associated-consts" class="anchor">§</a></h2><div class="methods"><details class="toggle" open><summary><section id="associatedconstant.OPCODE" class="method"><a class="src rightside" href="../../src/rustix/ioctl/mod.rs.html#157">source</a><h4 class="code-header">const <a href="#associatedconstant.OPCODE" class="constant">OPCODE</a>: <a class="struct" href="struct.Opcode.html" title="struct rustix::ioctl::Opcode">Opcode</a></h4></section></summary><div class="docblock"><p>The opcode used by this <code>ioctl</code> command.</p>
<p>There are different types of opcode depending on the operation. See
documentation for the <a href="struct.Opcode.html" title="struct rustix::ioctl::Opcode"><code>Opcode</code></a> struct for more information.</p>
</div></details><details class="toggle" open><summary><section id="associatedconstant.IS_MUTATING" class="method"><a class="src rightside" href="../../src/rustix/ioctl/mod.rs.html#170">source</a><h4 class="code-header">const <a href="#associatedconstant.IS_MUTATING" class="constant">IS_MUTATING</a>: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.bool.html">bool</a></h4></section></summary><div class="docblock"><p>Does the <code>ioctl</code> mutate any data in the userspace?</p>
<p>If the <code>ioctl</code> call does not mutate any data in the userspace, then
making this <code>false</code> enables optimizations that can make the call
faster. When in doubt, set this to <code>true</code>.</p>
<h5 id="safety-1"><a href="#safety-1">Safety</a></h5>
<p>This should only be set to <code>false</code> if the <code>ioctl</code> call does not mutate
any data in the userspace. Undefined behavior may occur if this is set
to <code>false</code> when it should be <code>true</code>.</p>
</div></details></div><h2 id="required-methods" class="section-header">Required Methods<a href="#required-methods" class="anchor">§</a></h2><div class="methods"><details class="toggle method-toggle" open><summary><section id="tymethod.as_ptr" class="method"><a class="src rightside" href="../../src/rustix/ioctl/mod.rs.html#175">source</a><h4 class="code-header">fn <a href="#tymethod.as_ptr" class="fn">as_ptr</a>(&amp;mut self) -&gt; <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.pointer.html">*mut </a><a class="enum" href="https://doc.rust-lang.org/1.76.0/core/ffi/enum.c_void.html" title="enum core::ffi::c_void">c_void</a></h4></section></summary><div class="docblock"><p>Get a pointer to the data to be passed to the <code>ioctl</code> command.</p>
<p>See trait-level documentation for more information.</p>
</div></details><details class="toggle method-toggle" open><summary><section id="tymethod.output_from_ptr" class="method"><a class="src rightside" href="../../src/rustix/ioctl/mod.rs.html#185-188">source</a><h4 class="code-header">unsafe fn <a href="#tymethod.output_from_ptr" class="fn">output_from_ptr</a>(
out: <a class="type" href="type.IoctlOutput.html" title="type rustix::ioctl::IoctlOutput">IoctlOutput</a>,
extract_output: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.pointer.html">*mut </a><a class="enum" href="https://doc.rust-lang.org/1.76.0/core/ffi/enum.c_void.html" title="enum core::ffi::c_void">c_void</a>
) -&gt; <a class="type" href="../io/type.Result.html" title="type rustix::io::Result">Result</a>&lt;Self::<a class="associatedtype" href="trait.Ioctl.html#associatedtype.Output" title="type rustix::ioctl::Ioctl::Output">Output</a>&gt;</h4></section></summary><div class="docblock"><p>Cast the output data to the correct type.</p>
<h5 id="safety-2"><a href="#safety-2">Safety</a></h5>
<p>The <code>extract_output</code> value must be the resulting value after a
successful <code>ioctl</code> call, and <code>out</code> is the direct return value of an
<code>ioctl</code> call that did not fail. In this case <code>extract_output</code> is the
pointer that was passed to the <code>ioctl</code> call.</p>
</div></details></div><h2 id="object-safety" class="section-header">Object Safety<a href="#object-safety" class="anchor">§</a></h2><div class="object-safety-info">This trait is <b>not</b> <a href="https://doc.rust-lang.org/1.76.0/reference/items/traits.html#object-safety">object safe</a>.</div><h2 id="implementors" class="section-header">Implementors<a href="#implementors" class="anchor">§</a></h2><div id="implementors-list"><details class="toggle implementors-toggle"><summary><section id="impl-Ioctl-for-Updater%3C'a,+Opcode,+T%3E" class="impl"><a class="src rightside" href="../../src/rustix/ioctl/patterns.rs.html#185-198">source</a><a href="#impl-Ioctl-for-Updater%3C'a,+Opcode,+T%3E" class="anchor">§</a><h3 class="code-header">impl&lt;'a, Opcode: <a class="trait" href="trait.CompileTimeOpcode.html" title="trait rustix::ioctl::CompileTimeOpcode">CompileTimeOpcode</a>, T&gt; <a class="trait" href="trait.Ioctl.html" title="trait rustix::ioctl::Ioctl">Ioctl</a> for <a class="struct" href="struct.Updater.html" title="struct rustix::ioctl::Updater">Updater</a>&lt;'a, Opcode, T&gt;</h3></section></summary><div class="impl-items"><section id="associatedtype.Output-1" class="associatedtype trait-impl"><a href="#associatedtype.Output-1" class="anchor">§</a><h4 class="code-header">type <a href="#associatedtype.Output" class="associatedtype">Output</a> = <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.unit.html">()</a></h4></section><section id="associatedconstant.IS_MUTATING-1" class="associatedconstant trait-impl"><a class="src rightside" href="../../src/rustix/ioctl/patterns.rs.html#188">source</a><a href="#associatedconstant.IS_MUTATING-1" class="anchor">§</a><h4 class="code-header">const <a href="#associatedconstant.IS_MUTATING" class="constant">IS_MUTATING</a>: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.bool.html">bool</a> = true</h4></section><section id="associatedconstant.OPCODE-1" class="associatedconstant trait-impl"><a class="src rightside" href="../../src/rustix/ioctl/patterns.rs.html#189">source</a><a href="#associatedconstant.OPCODE-1" class="anchor">§</a><h4 class="code-header">const <a href="#associatedconstant.OPCODE" class="constant">OPCODE</a>: <a class="struct" href="struct.Opcode.html" title="struct rustix::ioctl::Opcode">Opcode</a> = Opcode::OPCODE</h4></section></div></details><details class="toggle implementors-toggle"><summary><section id="impl-Ioctl-for-NoArg%3COpcode%3E" class="impl"><a class="src rightside" href="../../src/rustix/ioctl/patterns.rs.html#38-51">source</a><a href="#impl-Ioctl-for-NoArg%3COpcode%3E" class="anchor">§</a><h3 class="code-header">impl&lt;Opcode: <a class="trait" href="trait.CompileTimeOpcode.html" title="trait rustix::ioctl::CompileTimeOpcode">CompileTimeOpcode</a>&gt; <a class="trait" href="trait.Ioctl.html" title="trait rustix::ioctl::Ioctl">Ioctl</a> for <a class="struct" href="struct.NoArg.html" title="struct rustix::ioctl::NoArg">NoArg</a>&lt;Opcode&gt;</h3></section></summary><div class="impl-items"><section id="associatedtype.Output-2" class="associatedtype trait-impl"><a href="#associatedtype.Output-2" class="anchor">§</a><h4 class="code-header">type <a href="#associatedtype.Output" class="associatedtype">Output</a> = <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.unit.html">()</a></h4></section><section id="associatedconstant.IS_MUTATING-2" class="associatedconstant trait-impl"><a class="src rightside" href="../../src/rustix/ioctl/patterns.rs.html#41">source</a><a href="#associatedconstant.IS_MUTATING-2" class="anchor">§</a><h4 class="code-header">const <a href="#associatedconstant.IS_MUTATING" class="constant">IS_MUTATING</a>: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.bool.html">bool</a> = false</h4></section><section id="associatedconstant.OPCODE-2" class="associatedconstant trait-impl"><a class="src rightside" href="../../src/rustix/ioctl/patterns.rs.html#42">source</a><a href="#associatedconstant.OPCODE-2" class="anchor">§</a><h4 class="code-header">const <a href="#associatedconstant.OPCODE" class="constant">OPCODE</a>: <a class="struct" href="struct.Opcode.html" title="struct rustix::ioctl::Opcode">Opcode</a> = Opcode::OPCODE</h4></section></div></details><details class="toggle implementors-toggle"><summary><section id="impl-Ioctl-for-Setter%3COpcode,+Input%3E" class="impl"><a class="src rightside" href="../../src/rustix/ioctl/patterns.rs.html#141-154">source</a><a href="#impl-Ioctl-for-Setter%3COpcode,+Input%3E" class="anchor">§</a><h3 class="code-header">impl&lt;Opcode: <a class="trait" href="trait.CompileTimeOpcode.html" title="trait rustix::ioctl::CompileTimeOpcode">CompileTimeOpcode</a>, Input&gt; <a class="trait" href="trait.Ioctl.html" title="trait rustix::ioctl::Ioctl">Ioctl</a> for <a class="struct" href="struct.Setter.html" title="struct rustix::ioctl::Setter">Setter</a>&lt;Opcode, Input&gt;</h3></section></summary><div class="impl-items"><section id="associatedtype.Output-3" class="associatedtype trait-impl"><a href="#associatedtype.Output-3" class="anchor">§</a><h4 class="code-header">type <a href="#associatedtype.Output" class="associatedtype">Output</a> = <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.unit.html">()</a></h4></section><section id="associatedconstant.IS_MUTATING-3" class="associatedconstant trait-impl"><a class="src rightside" href="../../src/rustix/ioctl/patterns.rs.html#144">source</a><a href="#associatedconstant.IS_MUTATING-3" class="anchor">§</a><h4 class="code-header">const <a href="#associatedconstant.IS_MUTATING" class="constant">IS_MUTATING</a>: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.bool.html">bool</a> = false</h4></section><section id="associatedconstant.OPCODE-3" class="associatedconstant trait-impl"><a class="src rightside" href="../../src/rustix/ioctl/patterns.rs.html#145">source</a><a href="#associatedconstant.OPCODE-3" class="anchor">§</a><h4 class="code-header">const <a href="#associatedconstant.OPCODE" class="constant">OPCODE</a>: <a class="struct" href="struct.Opcode.html" title="struct rustix::ioctl::Opcode">Opcode</a> = Opcode::OPCODE</h4></section></div></details><details class="toggle implementors-toggle"><summary><section id="impl-Ioctl-for-Getter%3COpcode,+Output%3E" class="impl"><a class="src rightside" href="../../src/rustix/ioctl/patterns.rs.html#88-101">source</a><a href="#impl-Ioctl-for-Getter%3COpcode,+Output%3E" class="anchor">§</a><h3 class="code-header">impl&lt;Opcode: <a class="trait" href="trait.CompileTimeOpcode.html" title="trait rustix::ioctl::CompileTimeOpcode">CompileTimeOpcode</a>, Output&gt; <a class="trait" href="trait.Ioctl.html" title="trait rustix::ioctl::Ioctl">Ioctl</a> for <a class="struct" href="struct.Getter.html" title="struct rustix::ioctl::Getter">Getter</a>&lt;Opcode, Output&gt;</h3></section></summary><div class="impl-items"><section id="associatedtype.Output-4" class="associatedtype trait-impl"><a href="#associatedtype.Output-4" class="anchor">§</a><h4 class="code-header">type <a href="#associatedtype.Output" class="associatedtype">Output</a> = Output</h4></section><section id="associatedconstant.IS_MUTATING-4" class="associatedconstant trait-impl"><a class="src rightside" href="../../src/rustix/ioctl/patterns.rs.html#91">source</a><a href="#associatedconstant.IS_MUTATING-4" class="anchor">§</a><h4 class="code-header">const <a href="#associatedconstant.IS_MUTATING" class="constant">IS_MUTATING</a>: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.bool.html">bool</a> = true</h4></section><section id="associatedconstant.OPCODE-4" class="associatedconstant trait-impl"><a class="src rightside" href="../../src/rustix/ioctl/patterns.rs.html#92">source</a><a href="#associatedconstant.OPCODE-4" class="anchor">§</a><h4 class="code-header">const <a href="#associatedconstant.OPCODE" class="constant">OPCODE</a>: <a class="struct" href="struct.Opcode.html" title="struct rustix::ioctl::Opcode">Opcode</a> = Opcode::OPCODE</h4></section></div></details></div><script src="../../trait.impl/rustix/ioctl/trait.Ioctl.js" async></script></section></div></main></body></html>
Reference in New Issue View Git Blame Copy Permalink