1 // Copyright 2015 The Rust Project Developers. See the COPYRIGHT
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
11 //! Unix-specific extensions to primitives in the `std::fs` module.
13 #![stable(feature = "rust1", since = "1.0.0")]
15 use fs::{self, Permissions, OpenOptions};
22 use sys_common::{FromInner, AsInner, AsInnerMut};
23 use sys::platform::fs::MetadataExt as UnixMetadataExt;
25 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
26 #[rustc_deprecated(since = "1.7.0", reason = "moved to the libc crate instead")]
28 pub const USER_READ: raw::mode_t = 0o400;
29 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
30 #[rustc_deprecated(since = "1.7.0", reason = "moved to the libc crate instead")]
32 pub const USER_WRITE: raw::mode_t = 0o200;
33 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
34 #[rustc_deprecated(since = "1.7.0", reason = "moved to the libc crate instead")]
36 pub const USER_EXECUTE: raw::mode_t = 0o100;
37 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
38 #[rustc_deprecated(since = "1.7.0", reason = "moved to the libc crate instead")]
40 pub const USER_RWX: raw::mode_t = 0o700;
41 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
42 #[rustc_deprecated(since = "1.7.0", reason = "moved to the libc crate instead")]
44 pub const GROUP_READ: raw::mode_t = 0o040;
45 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
46 #[rustc_deprecated(since = "1.7.0", reason = "moved to the libc crate instead")]
48 pub const GROUP_WRITE: raw::mode_t = 0o020;
49 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
50 #[rustc_deprecated(since = "1.7.0", reason = "moved to the libc crate instead")]
52 pub const GROUP_EXECUTE: raw::mode_t = 0o010;
53 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
54 #[rustc_deprecated(since = "1.7.0", reason = "moved to the libc crate instead")]
56 pub const GROUP_RWX: raw::mode_t = 0o070;
57 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
58 #[rustc_deprecated(since = "1.7.0", reason = "moved to the libc crate instead")]
60 pub const OTHER_READ: raw::mode_t = 0o004;
61 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
62 #[rustc_deprecated(since = "1.7.0", reason = "moved to the libc crate instead")]
64 pub const OTHER_WRITE: raw::mode_t = 0o002;
65 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
66 #[rustc_deprecated(since = "1.7.0", reason = "moved to the libc crate instead")]
68 pub const OTHER_EXECUTE: raw::mode_t = 0o001;
69 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
70 #[rustc_deprecated(since = "1.7.0", reason = "moved to the libc crate instead")]
72 pub const OTHER_RWX: raw::mode_t = 0o007;
73 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
74 #[rustc_deprecated(since = "1.7.0", reason = "moved to the libc crate instead")]
76 pub const ALL_READ: raw::mode_t = 0o444;
77 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
78 #[rustc_deprecated(since = "1.7.0", reason = "moved to the libc crate instead")]
80 pub const ALL_WRITE: raw::mode_t = 0o222;
81 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
82 #[rustc_deprecated(since = "1.7.0", reason = "moved to the libc crate instead")]
84 pub const ALL_EXECUTE: raw::mode_t = 0o111;
85 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
86 #[rustc_deprecated(since = "1.7.0", reason = "moved to the libc crate instead")]
88 pub const ALL_RWX: raw::mode_t = 0o777;
89 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
90 #[rustc_deprecated(since = "1.7.0", reason = "moved to the libc crate instead")]
92 pub const SETUID: raw::mode_t = 0o4000;
93 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
94 #[rustc_deprecated(since = "1.7.0", reason = "moved to the libc crate instead")]
96 pub const SETGID: raw::mode_t = 0o2000;
97 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
98 #[rustc_deprecated(since = "1.7.0", reason = "moved to the libc crate instead")]
100 pub const STICKY_BIT: raw::mode_t = 0o1000;
102 /// Unix-specific extensions to `Permissions`
103 #[stable(feature = "fs_ext", since = "1.1.0")]
104 pub trait PermissionsExt {
105 /// Returns the underlying raw `mode_t` bits that are the standard Unix
106 /// permissions for this file.
107 #[stable(feature = "fs_ext", since = "1.1.0")]
108 fn mode(&self) -> u32;
110 /// Sets the underlying raw bits for this set of permissions.
111 #[stable(feature = "fs_ext", since = "1.1.0")]
112 fn set_mode(&mut self, mode: u32);
114 /// Creates a new instance of `Permissions` from the given set of Unix
116 #[stable(feature = "fs_ext", since = "1.1.0")]
117 fn from_mode(mode: u32) -> Self;
120 #[stable(feature = "fs_ext", since = "1.1.0")]
121 impl PermissionsExt for Permissions {
122 fn mode(&self) -> u32 {
123 self.as_inner().mode()
126 fn set_mode(&mut self, mode: u32) {
127 *self = Permissions::from_inner(FromInner::from_inner(mode));
130 fn from_mode(mode: u32) -> Permissions {
131 Permissions::from_inner(FromInner::from_inner(mode))
135 /// Unix-specific extensions to `OpenOptions`
136 #[stable(feature = "fs_ext", since = "1.1.0")]
137 pub trait OpenOptionsExt {
138 /// Sets the mode bits that a new file will be created with.
140 /// If a new file is created as part of a `File::open_opts` call then this
141 /// specified `mode` will be used as the permission bits for the new file.
142 /// If no `mode` is set, the default of `0o666` will be used.
143 /// The operating system masks out bits with the systems `umask`, to produce
144 /// the final permissions.
145 #[stable(feature = "fs_ext", since = "1.1.0")]
146 fn mode(&mut self, mode: u32) -> &mut Self;
148 /// Pass custom flags to the `flags` agument of `open`.
150 /// The bits that define the access mode are masked out with `O_ACCMODE`, to
151 /// ensure they do not interfere with the access mode set by Rusts options.
153 /// Custom flags can only set flags, not remove flags set by Rusts options.
154 /// This options overwrites any previously set custom flags.
159 /// extern crate libc;
160 /// use std::fs::OpenOptions;
161 /// use std::os::unix::fs::OpenOptionsExt;
163 /// let mut options = OpenOptions::new();
164 /// options.write(true);
166 /// options.custom_flags(libc::O_NOFOLLOW);
168 /// let file = options.open("foo.txt");
170 #[unstable(feature = "expand_open_options",
171 reason = "recently added",
173 fn custom_flags(&mut self, flags: i32) -> &mut Self;
176 #[stable(feature = "fs_ext", since = "1.1.0")]
177 impl OpenOptionsExt for OpenOptions {
178 fn mode(&mut self, mode: u32) -> &mut OpenOptions {
179 self.as_inner_mut().mode(mode); self
182 fn custom_flags(&mut self, flags: i32) -> &mut OpenOptions {
183 self.as_inner_mut().custom_flags(flags); self
187 // Hm, why are there casts here to the returned type, shouldn't the types always
188 // be the same? Right you are! Turns out, however, on android at least the types
189 // in the raw `stat` structure are not the same as the types being returned. Who
192 // As a result to make sure this compiles for all platforms we do the manual
193 // casts and rely on manual lowering to `stat` if the raw type is desired.
194 #[stable(feature = "metadata_ext", since = "1.1.0")]
195 pub trait MetadataExt {
196 #[stable(feature = "metadata_ext", since = "1.1.0")]
197 fn dev(&self) -> u64;
198 #[stable(feature = "metadata_ext", since = "1.1.0")]
199 fn ino(&self) -> u64;
200 #[stable(feature = "metadata_ext", since = "1.1.0")]
201 fn mode(&self) -> u32;
202 #[stable(feature = "metadata_ext", since = "1.1.0")]
203 fn nlink(&self) -> u64;
204 #[stable(feature = "metadata_ext", since = "1.1.0")]
205 fn uid(&self) -> u32;
206 #[stable(feature = "metadata_ext", since = "1.1.0")]
207 fn gid(&self) -> u32;
208 #[stable(feature = "metadata_ext", since = "1.1.0")]
209 fn rdev(&self) -> u64;
210 #[stable(feature = "metadata_ext", since = "1.1.0")]
211 fn size(&self) -> u64;
212 #[stable(feature = "metadata_ext", since = "1.1.0")]
213 fn atime(&self) -> i64;
214 #[stable(feature = "metadata_ext", since = "1.1.0")]
215 fn atime_nsec(&self) -> i64;
216 #[stable(feature = "metadata_ext", since = "1.1.0")]
217 fn mtime(&self) -> i64;
218 #[stable(feature = "metadata_ext", since = "1.1.0")]
219 fn mtime_nsec(&self) -> i64;
220 #[stable(feature = "metadata_ext", since = "1.1.0")]
221 fn ctime(&self) -> i64;
222 #[stable(feature = "metadata_ext", since = "1.1.0")]
223 fn ctime_nsec(&self) -> i64;
224 #[stable(feature = "metadata_ext", since = "1.1.0")]
225 fn blksize(&self) -> u64;
226 #[stable(feature = "metadata_ext", since = "1.1.0")]
227 fn blocks(&self) -> u64;
230 #[stable(feature = "metadata_ext", since = "1.1.0")]
231 impl MetadataExt for fs::Metadata {
232 fn dev(&self) -> u64 { self.st_dev() }
233 fn ino(&self) -> u64 { self.st_ino() }
234 fn mode(&self) -> u32 { self.st_mode() }
235 fn nlink(&self) -> u64 { self.st_nlink() }
236 fn uid(&self) -> u32 { self.st_uid() }
237 fn gid(&self) -> u32 { self.st_gid() }
238 fn rdev(&self) -> u64 { self.st_rdev() }
239 fn size(&self) -> u64 { self.st_size() }
240 fn atime(&self) -> i64 { self.st_atime() }
241 fn atime_nsec(&self) -> i64 { self.st_atime_nsec() }
242 fn mtime(&self) -> i64 { self.st_mtime() }
243 fn mtime_nsec(&self) -> i64 { self.st_mtime_nsec() }
244 fn ctime(&self) -> i64 { self.st_ctime() }
245 fn ctime_nsec(&self) -> i64 { self.st_ctime_nsec() }
246 fn blksize(&self) -> u64 { self.st_blksize() }
247 fn blocks(&self) -> u64 { self.st_blocks() }
250 /// Add special unix types (block/char device, fifo and socket)
251 #[stable(feature = "file_type_ext", since = "1.5.0")]
252 pub trait FileTypeExt {
253 /// Returns whether this file type is a block device.
254 #[stable(feature = "file_type_ext", since = "1.5.0")]
255 fn is_block_device(&self) -> bool;
256 /// Returns whether this file type is a char device.
257 #[stable(feature = "file_type_ext", since = "1.5.0")]
258 fn is_char_device(&self) -> bool;
259 /// Returns whether this file type is a fifo.
260 #[stable(feature = "file_type_ext", since = "1.5.0")]
261 fn is_fifo(&self) -> bool;
262 /// Returns whether this file type is a socket.
263 #[stable(feature = "file_type_ext", since = "1.5.0")]
264 fn is_socket(&self) -> bool;
267 #[stable(feature = "file_type_ext", since = "1.5.0")]
268 impl FileTypeExt for fs::FileType {
269 fn is_block_device(&self) -> bool { self.as_inner().is(libc::S_IFBLK) }
270 fn is_char_device(&self) -> bool { self.as_inner().is(libc::S_IFCHR) }
271 fn is_fifo(&self) -> bool { self.as_inner().is(libc::S_IFIFO) }
272 fn is_socket(&self) -> bool { self.as_inner().is(libc::S_IFSOCK) }
275 /// Unix-specific extension methods for `fs::DirEntry`
276 #[stable(feature = "dir_entry_ext", since = "1.1.0")]
277 pub trait DirEntryExt {
278 /// Returns the underlying `d_ino` field in the contained `dirent`
280 #[stable(feature = "dir_entry_ext", since = "1.1.0")]
281 fn ino(&self) -> u64;
284 #[stable(feature = "dir_entry_ext", since = "1.1.0")]
285 impl DirEntryExt for fs::DirEntry {
286 fn ino(&self) -> u64 { self.as_inner().ino() }
289 /// Creates a new symbolic link on the filesystem.
291 /// The `dst` path will be a symbolic link pointing to the `src` path.
295 /// On Windows, you must specify whether a symbolic link points to a file
296 /// or directory. Use `os::windows::fs::symlink_file` to create a
297 /// symbolic link to a file, or `os::windows::fs::symlink_dir` to create a
298 /// symbolic link to a directory. Additionally, the process must have
299 /// `SeCreateSymbolicLinkPrivilege` in order to be able to create a
305 /// use std::os::unix::fs;
307 /// # fn foo() -> std::io::Result<()> {
308 /// try!(fs::symlink("a.txt", "b.txt"));
312 #[stable(feature = "symlink", since = "1.1.0")]
313 pub fn symlink<P: AsRef<Path>, Q: AsRef<Path>>(src: P, dst: Q) -> io::Result<()>
315 sys::fs::symlink(src.as_ref(), dst.as_ref())
318 #[stable(feature = "dir_builder", since = "1.6.0")]
319 /// An extension trait for `fs::DirBuilder` for unix-specific options.
320 pub trait DirBuilderExt {
321 /// Sets the mode to create new directories with. This option defaults to
323 #[stable(feature = "dir_builder", since = "1.6.0")]
324 fn mode(&mut self, mode: u32) -> &mut Self;
327 #[stable(feature = "dir_builder", since = "1.6.0")]
328 impl DirBuilderExt for fs::DirBuilder {
329 fn mode(&mut self, mode: u32) -> &mut fs::DirBuilder {
330 self.as_inner_mut().set_mode(mode);