utuntap/
tun.rs

1//! APIs for level 3 Tun devices
2
3use super::Mode;
4use std::fs::File;
5use std::io::Result;
6
7/**
8Options and flags which can be used to configure how a tun device file is
9opened.
10
11This builder exposes the ability to configure how a [`std::fs::File`][file] is
12opened and what operations are permitted on the open file, and what `ioctl`
13operations should be applied to the file.
14
15Generally speaking, when using `OpenOptions`, you'll first call [`new`],
16then chain calls to methods to set each option, then call [`open`].
17This will give you a [`std::io::Result`][result] with a tuple of
18[`std::fs::File`][file] and filename [`alloc::string::String`][string]
19inside that you can further operate on.
20
21[`new`]: struct.OpenOptions.html#method.new
22[`open`]: struct.OpenOptions.html#method.open
23[result]: https://doc.rust-lang.org/nightly/std/io/type.Result.html
24[file]: https://doc.rust-lang.org/nightly/std/io/struct.File.html
25[string]: https://doc.rust-lang.org/nightly/alloc/string/struct.String.html
26
27# Examples
28
29Opening device `tun0`:
30
31```no_run
32use utuntap::tun::OpenOptions;
33
34let file = OpenOptions::new().open(0).unwrap();
35```
36
37Opening device `tun0` with non-blocking I/O set:
38
39```no_run
40use utuntap::tun::OpenOptions;
41
42let file = OpenOptions::new()
43            .nonblock(true)
44            .open(0)
45            .unwrap();
46```
47*/
48pub struct OpenOptions {
49    options: super::OpenOptions,
50}
51
52impl OpenOptions {
53    /**
54    Creates a blank new set of options ready for configuration.
55
56    All options are initially set to `false` except read and write.
57
58    # Examples
59
60    ```no_run
61    use utuntap::tun::OpenOptions;
62
63    let mut options = OpenOptions::new();
64    let file = options.open(0).unwrap();
65    ```
66    */
67    pub fn new() -> Self {
68        let mut options = super::OpenOptions::new();
69        options.mode(Mode::Tun);
70        Self { options }
71    }
72
73    /**
74    Sets the option for read access.
75
76    This option, when true, will indicate that the file should be
77    `read`-able if opened.
78
79    This opiton defaults to `true`.
80
81    # Examples
82
83    ```no_run
84    use utuntap::tun::OpenOptions;
85
86    let mut options = OpenOptions::new();
87    let file = options.read(true).write(true).open(0).unwrap();
88    ```
89    */
90    pub fn read(&mut self, value: bool) -> &mut Self {
91        self.options.read(value);
92        self
93    }
94
95    /**
96    Sets the option for write access.
97
98    This option, when true, will indicate that the file should be
99    `write`-able if opened.
100
101    This opiton defaults to `true`.
102
103    # Examples
104
105    ```no_run
106    use utuntap::tun::OpenOptions;
107
108    let mut options = OpenOptions::new();
109    let file = options.read(true).write(true).open(0).unwrap();
110    ```
111    */
112    pub fn write(&mut self, value: bool) -> &mut Self {
113        self.options.write(value);
114        self
115    }
116
117    /**
118    Sets the option for non-blocking I/O.
119
120    This option, when true, will indicate that the file should not
121    block for data to become available.
122
123    # Examples
124
125    ```no_run
126    use utuntap::tun::OpenOptions;
127
128    let mut options = OpenOptions::new();
129    let file = options.nonblock(true).open(0).unwrap();
130    ```
131    */
132    #[cfg(target_family = "unix")]
133    pub fn nonblock(&mut self, value: bool) -> &mut Self {
134        self.options.nonblock(value);
135        self
136    }
137
138    /**
139    Sets the option for packet info.
140
141    This option, when true, will indicate that each packet read or
142    written is prefixed with a 4-byte packet info.
143
144    This option is only available on Linux.
145
146    # Examples
147
148    ```no_run
149    use utuntap::tun::OpenOptions;
150
151    let mut options = OpenOptions::new();
152    let file = options.packet_info(true).open(0).unwrap();
153    ```
154    */
155    #[cfg(target_os = "linux")]
156    pub fn packet_info(&mut self, value: bool) -> &mut Self {
157        self.options.packet_info(value);
158        self
159    }
160
161    /**
162    Opens a tun device file with the options specified by `self`.
163
164    # Arguments
165
166    * `number` - the number of the device, e.g. the "0" of "tun0".
167
168    # Errors
169
170    This function will return an error under a number of different
171    circumstances. Some of these error conditions are listed here, together
172    with their [`ErrorKind`]. The mapping to [`ErrorKind`]s is not part of
173    the compatibility contract of the function.
174
175    * [`NotFound`]: The device file does not exist.
176    * [`PermissionDenied`]: The user lacks permission to get the specified
177      access rights for the file.
178
179    # Examples
180
181    ```no_run
182    use utuntap::tun::OpenOptions;
183
184    let mut options = OpenOptions::new();
185    let file = options.open(0).unwrap();
186    ```
187
188    [`ErrorKind`]: https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html
189    [`NotFound`]: https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html#variant.NotFound
190    [`PermissionDenied`]: https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html#variant.PermissionDenied
191    */
192    pub fn open(&mut self, number: u32) -> Result<File> {
193        Ok(self.options.open(number)?)
194    }
195}
utuntap/tun.rs

utuntap/
tun.rs
