1//! POSIX-style filesystem functions which operate on bare paths.
2
3use crate::fd::OwnedFd;
4#[cfg(not(any(target_os = "espidf", target_os = "horizon", target_os = "vita")))]
5use crate::fs::Access;
6#[cfg(not(any(
7 solarish,
8 target_os = "espidf",
9 target_os = "haiku",
10 target_os = "horizon",
11 target_os = "netbsd",
12 target_os = "nto",
13 target_os = "redox",
14 target_os = "vita",
15 target_os = "wasi",
16)))]
17use crate::fs::StatFs;
18#[cfg(not(any(target_os = "haiku", target_os = "redox", target_os = "wasi")))]
19use crate::fs::StatVfs;
20use crate::fs::{Mode, OFlags, Stat};
21#[cfg(not(target_os = "wasi"))]
22use crate::ugid::{Gid, Uid};
23use crate::{backend, io, path};
24#[cfg(feature = "alloc")]
25use {
26 crate::ffi::{CStr, CString},
27 crate::path::SMALL_PATH_BUFFER_SIZE,
28 alloc::vec::Vec,
29};
30
31/// `open(path, oflags, mode)`—Opens a file.
32///
33/// POSIX guarantees that `open` will use the lowest unused file descriptor,
34/// however it is not safe in general to rely on this, as file descriptors may
35/// be unexpectedly allocated on other threads or in libraries.
36///
37/// The `Mode` argument is only significant when creating a file.
38///
39/// # References
40/// - [POSIX]
41/// - [Linux]
42///
43/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/open.html
44/// [Linux]: https://man7.org/linux/man-pages/man2/open.2.html
45#[inline]
46pub fn open<P: path::Arg>(path: P, flags: OFlags, mode: Mode) -> io::Result<OwnedFd> {
47 path.into_with_c_str(|path: &CStr| backend::fs::syscalls::open(path, flags, mode))
48}
49
50/// `chmod(path, mode)`—Sets file or directory permissions.
51///
52/// # References
53/// - [POSIX]
54/// - [Linux]
55///
56/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/chmod.html
57/// [Linux]: https://man7.org/linux/man-pages/man2/chmod.2.html
58#[cfg(not(target_os = "wasi"))]
59#[inline]
60pub fn chmod<P: path::Arg>(path: P, mode: Mode) -> io::Result<()> {
61 path.into_with_c_str(|path: &CStr| backend::fs::syscalls::chmod(path, mode))
62}
63
64/// `stat(path)`—Queries metadata for a file or directory.
65///
66/// [`Mode::from_raw_mode`] and [`FileType::from_raw_mode`] may be used to
67/// interpret the `st_mode` field.
68///
69/// # References
70/// - [POSIX]
71/// - [Linux]
72///
73/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/stat.html
74/// [Linux]: https://man7.org/linux/man-pages/man2/stat.2.html
75/// [`Mode::from_raw_mode`]: crate::fs::Mode::from_raw_mode
76/// [`FileType::from_raw_mode`]: crate::fs::FileType::from_raw_mode
77#[inline]
78pub fn stat<P: path::Arg>(path: P) -> io::Result<Stat> {
79 path.into_with_c_str(backend::fs::syscalls::stat)
80}
81
82/// `lstat(path)`—Queries metadata for a file or directory, without following
83/// symlinks.
84///
85/// [`Mode::from_raw_mode`] and [`FileType::from_raw_mode`] may be used to
86/// interpret the `st_mode` field.
87///
88/// # References
89/// - [POSIX]
90/// - [Linux]
91///
92/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/lstat.html
93/// [Linux]: https://man7.org/linux/man-pages/man2/lstat.2.html
94/// [`Mode::from_raw_mode`]: crate::fs::Mode::from_raw_mode
95/// [`FileType::from_raw_mode`]: crate::fs::FileType::from_raw_mode
96#[inline]
97pub fn lstat<P: path::Arg>(path: P) -> io::Result<Stat> {
98 path.into_with_c_str(backend::fs::syscalls::lstat)
99}
100
101/// `readlink(path)`—Reads the contents of a symlink.
102///
103/// If `reuse` is non-empty, reuse its buffer to store the result if possible.
104///
105/// # References
106/// - [POSIX]
107/// - [Linux]
108///
109/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/readlink.html
110/// [Linux]: https://man7.org/linux/man-pages/man2/readlink.2.html
111#[cfg(feature = "alloc")]
112#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
113#[inline]
114pub fn readlink<P: path::Arg, B: Into<Vec<u8>>>(path: P, reuse: B) -> io::Result<CString> {
115 path.into_with_c_str(|path: &CStr| _readlink(path, buffer:reuse.into()))
116}
117
118#[cfg(feature = "alloc")]
119fn _readlink(path: &CStr, mut buffer: Vec<u8>) -> io::Result<CString> {
120 // This code would benefit from having a better way to read into
121 // uninitialized memory, but that requires `unsafe`.
122 buffer.clear();
123 buffer.reserve(SMALL_PATH_BUFFER_SIZE);
124 buffer.resize(new_len:buffer.capacity(), value:0_u8);
125
126 loop {
127 let nread: usize = backend::fs::syscalls::readlink(path, &mut buffer)?;
128
129 let nread: usize = nread as usize;
130 assert!(nread <= buffer.len());
131 if nread < buffer.len() {
132 buffer.resize(new_len:nread, value:0_u8);
133 return Ok(CString::new(buffer).unwrap());
134 }
135 // Use `Vec` reallocation strategy to grow capacity exponentially.
136 buffer.reserve(additional:1);
137 buffer.resize(new_len:buffer.capacity(), value:0_u8);
138 }
139}
140
141/// `rename(old_path, new_path)`—Renames a file or directory.
142///
143/// # References
144/// - [POSIX]
145/// - [Linux]
146///
147/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/rename.html
148/// [Linux]: https://man7.org/linux/man-pages/man2/rename.2.html
149#[inline]
150pub fn rename<P: path::Arg, Q: path::Arg>(old_path: P, new_path: Q) -> io::Result<()> {
151 old_path.into_with_c_str(|old_path: &CStr| {
152 new_path.into_with_c_str(|new_path: &CStr| backend::fs::syscalls::rename(old_path, new_path))
153 })
154}
155
156/// `unlink(path)`—Unlinks a file.
157///
158/// # References
159/// - [POSIX]
160/// - [Linux]
161///
162/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/unlink.html
163/// [Linux]: https://man7.org/linux/man-pages/man2/unlink.2.html
164#[inline]
165pub fn unlink<P: path::Arg>(path: P) -> io::Result<()> {
166 path.into_with_c_str(backend::fs::syscalls::unlink)
167}
168
169/// `rmdir(path)`—Removes a directory.
170///
171/// # References
172/// - [POSIX]
173/// - [Linux]
174///
175/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/rmdir.html
176/// [Linux]: https://man7.org/linux/man-pages/man2/rmdir.2.html
177#[inline]
178pub fn rmdir<P: path::Arg>(path: P) -> io::Result<()> {
179 path.into_with_c_str(backend::fs::syscalls::rmdir)
180}
181
182/// `link(old_path, new_path)`—Creates a hard link.
183///
184/// POSIX leaves it implementation-defined whether `link` follows a symlink in
185/// `old_path`, or creates a new link to the symbolic link itself. On platforms
186/// which have it, [`linkat`] avoids this problem since it has an [`AtFlags`]
187/// parameter and the [`AtFlags::SYMLINK_FOLLOW`] flag determines whether
188/// symlinks should be followed.
189///
190/// # References
191/// - [POSIX]
192/// - [Linux]
193///
194/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/link.html
195/// [Linux]: https://man7.org/linux/man-pages/man2/link.2.html
196/// [`linkat`]: crate::fs::linkat
197/// [`AtFlags`]: crate::fs::AtFlags
198/// [`AtFlags::SYMLINK_FOLLOW`]: crate::fs::AtFlags::SYMLINK_FOLLOW
199#[inline]
200pub fn link<P: path::Arg, Q: path::Arg>(old_path: P, new_path: Q) -> io::Result<()> {
201 old_path.into_with_c_str(|old_path: &CStr| {
202 new_path.into_with_c_str(|new_path: &CStr| backend::fs::syscalls::link(old_path, new_path))
203 })
204}
205
206/// `symlink(old_path, new_path)`—Creates a symlink.
207///
208/// # References
209/// - [POSIX]
210/// - [Linux]
211///
212/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/symlink.html
213/// [Linux]: https://man7.org/linux/man-pages/man2/symlink.2.html
214#[inline]
215pub fn symlink<P: path::Arg, Q: path::Arg>(old_path: P, new_path: Q) -> io::Result<()> {
216 old_path.into_with_c_str(|old_path: &CStr| {
217 new_path.into_with_c_str(|new_path: &CStr| backend::fs::syscalls::symlink(old_path, new_path))
218 })
219}
220
221/// `mkdir(path, mode)`—Creates a directory.
222///
223/// # References
224/// - [POSIX]
225/// - [Linux]
226///
227/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/mkdir.html
228/// [Linux]: https://man7.org/linux/man-pages/man2/mkdir.2.html
229#[inline]
230pub fn mkdir<P: path::Arg>(path: P, mode: Mode) -> io::Result<()> {
231 path.into_with_c_str(|path: &CStr| backend::fs::syscalls::mkdir(path, mode))
232}
233
234/// `access(path, access)`—Tests permissions for a file or directory.
235///
236/// # References
237/// - [POSIX]
238/// - [Linux]
239///
240/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/access.html
241/// [Linux]: https://man7.org/linux/man-pages/man2/access.2.html
242#[cfg(not(any(target_os = "espidf", target_os = "horizon", target_os = "vita")))]
243#[inline]
244pub fn access<P: path::Arg>(path: P, access: Access) -> io::Result<()> {
245 path.into_with_c_str(|path: &CStr| backend::fs::syscalls::access(path, access))
246}
247
248/// `statfs`—Queries filesystem metadata.
249///
250/// Compared to [`statvfs`], this function often provides more information,
251/// though it's less portable.
252///
253/// # References
254/// - [Linux]
255///
256/// [Linux]: https://man7.org/linux/man-pages/man2/statfs.2.html
257#[cfg(not(any(
258 solarish,
259 target_os = "espidf",
260 target_os = "haiku",
261 target_os = "horizon",
262 target_os = "netbsd",
263 target_os = "nto",
264 target_os = "redox",
265 target_os = "vita",
266 target_os = "wasi",
267)))]
268#[inline]
269pub fn statfs<P: path::Arg>(path: P) -> io::Result<StatFs> {
270 path.into_with_c_str(backend::fs::syscalls::statfs)
271}
272
273/// `statvfs`—Queries filesystem metadata, POSIX version.
274///
275/// Compared to [`statfs`], this function often provides less information, but
276/// it is more portable. But even so, filesystems are very diverse and not all
277/// the fields are meaningful for every filesystem. And `f_fsid` doesn't seem
278/// to have a clear meaning anywhere.
279///
280/// # References
281/// - [POSIX]
282/// - [Linux]
283///
284/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/statvfs.html
285/// [Linux]: https://man7.org/linux/man-pages/man2/statvfs.2.html
286#[cfg(not(any(target_os = "haiku", target_os = "redox", target_os = "wasi")))]
287#[inline]
288pub fn statvfs<P: path::Arg>(path: P) -> io::Result<StatVfs> {
289 path.into_with_c_str(backend::fs::syscalls::statvfs)
290}
291
292/// `chown(path, owner, group)`—Sets open file or directory ownership.
293///
294/// # References
295/// - [POSIX]
296/// - [Linux]
297///
298/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/chown.html
299/// [Linux]: https://man7.org/linux/man-pages/man2/chown.2.html
300#[cfg(not(target_os = "wasi"))]
301#[inline]
302pub fn chown<P: path::Arg>(path: P, owner: Option<Uid>, group: Option<Gid>) -> io::Result<()> {
303 path.into_with_c_str(|path: &CStr| backend::fs::syscalls::chown(path, owner, group))
304}
305