junction_verbatim/
lib.rs

1/*!
2Library for working with NTFS junctions.
3
4Junction Points are a little known NTFS v5+ feature roughly equivalent to Unix
5directory symbolic links.
6
7They are supported in Windows 2000 and onwards, where a directory
8serves as a symbolic link to another directory on the computer. For example,
9if the directory `D:\SYMLINK` specified `C:\WINNT\SYSTEM32` as its target, then
10an application accessing `D:\SYMLINK\DRIVERS` would in reality be accessing
11`C:\WINNT\SYSTEM32\DRIVERS`.
12*/
13#![doc(html_root_url = "https://docs.rs/junction-verbatim/~1")]
14#![cfg(windows)]
15#![deny(rust_2021_compatibility)]
16
17mod internals;
18
19#[cfg(test)]
20mod tests;
21
22use std::io;
23use std::path::{Path, PathBuf};
24
25/// Creates a junction point from the specified directory to the specified target directory.
26///
27/// N.B. Only works on NTFS.
28///
29/// # Error
30///
31/// This function may error if the `junction` path already exists.
32///
33/// # Example
34///
35/// ```rust
36/// use std::io;
37/// use std::path::Path;
38/// # use std::fs;
39/// # use junction_verbatim::create;
40/// fn main() -> io::Result<()> {
41///     let tmpdir = tempfile::tempdir()?;
42///     let target = tmpdir.path().join("target");
43///     let junction = tmpdir.path().join("junction");
44///     # fs::create_dir_all(&target)?;
45///     create(&target, &junction)
46/// }
47/// ```
48pub fn create<P, Q>(target: P, junction: Q) -> io::Result<()>
49where
50    P: AsRef<Path>,
51    Q: AsRef<Path>,
52{
53    internals::create(target.as_ref(), junction.as_ref())
54}
55
56/// Deletes a `junction` reparse point from the specified file or directory.
57///
58/// N.B. Only works on NTFS.
59///
60/// This function delete the junction point only, leaving the target directory
61/// and its content as is. It does nothing if the `junction` point does not exist.
62///
63/// # Example
64///
65/// ```rust
66/// use std::io;
67/// use std::path::Path;
68/// # use std::fs;
69/// # use junction_verbatim::{create, delete};
70/// fn main() -> io::Result<()> {
71///     let tmpdir = tempfile::tempdir()?;
72///     let target = tmpdir.path().join("target");
73///     let junction = tmpdir.path().join("junction");
74///     # fs::create_dir_all(&target)?;
75///     create(&target, &junction)?;
76///     delete(&junction)
77/// }
78/// ```
79pub fn delete<P: AsRef<Path>>(junction: P) -> io::Result<()> {
80    internals::delete(junction.as_ref())
81}
82
83/// Determines whether the specified path exists and refers to a junction point.
84///
85/// # Example
86///
87/// ```rust
88/// use std::io;
89/// # use junction_verbatim::exists;
90/// fn main() -> io::Result<()> {
91///     # #[cfg(feature = "unstable_admin")]
92///     assert!(exists(r"C:\Users\Default User")?);
93///     Ok(())
94/// }
95/// ```
96pub fn exists<P: AsRef<Path>>(junction: P) -> io::Result<bool> {
97    internals::exists(junction.as_ref())
98}
99
100/// Gets the target of the specified junction point.
101///
102/// N.B. Only works on NTFS.
103///
104/// # Example
105///
106/// ```rust
107/// use std::io;
108/// # use junction_verbatim::get_target;
109/// fn main() -> io::Result<()> {
110///     # #[cfg(feature = "unstable_admin")]
111///     assert_eq!(get_target(r"C:\Users\Default User")?.to_str(), Some(r"C:\Users\Default"));
112///     Ok(())
113/// }
114/// ```
115pub fn get_target<P: AsRef<Path>>(junction: P) -> io::Result<PathBuf> {
116    internals::get_target(junction.as_ref())
117}
junction_verbatim/lib.rs

junction_verbatim/
lib.rs
