Coverage Report

Created: 2024-12-17 06:15

/rust/registry/src/index.crates.io-6f17d22bba15001f/rustix-0.38.42/src/io/fcntl.rs
Line
Count
Source (jump to first uncovered line)
1
//! The Unix `fcntl` function is effectively lots of different functions hidden
2
//! behind a single dynamic dispatch interface. In order to provide a type-safe
3
//! API, rustix makes them all separate functions so that they can have
4
//! dedicated static type signatures.
5
//!
6
//! `fcntl` functions which are not specific to files or directories live in
7
//! the [`io`] module instead.
8
//!
9
//! [`io`]: crate::io
10
11
use crate::{backend, io};
12
use backend::fd::{AsFd, OwnedFd, RawFd};
13
14
pub use backend::io::types::FdFlags;
15
16
/// `fcntl(fd, F_GETFD)`—Returns a file descriptor's flags.
17
///
18
/// # References
19
///  - [POSIX]
20
///  - [Linux]
21
///  - [Apple]
22
///  - [FreeBSD]
23
///  - [NetBSD]
24
///  - [OpenBSD]
25
///  - [DragonFly BSD]
26
///  - [illumos]
27
///  - [glibc]
28
///
29
/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/fcntl.html
30
/// [Linux]: https://man7.org/linux/man-pages/man2/fcntl.2.html
31
/// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/fcntl.2.html
32
/// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=fcntl&sektion=2
33
/// [NetBSD]: https://man.netbsd.org/fcntl.2
34
/// [OpenBSD]: https://man.openbsd.org/fcntl.2
35
/// [DragonFly BSD]: https://man.dragonflybsd.org/?command=fcntl&section=2
36
/// [illumos]: https://illumos.org/man/2/fcntl
37
/// [glibc]: https://sourceware.org/glibc/manual/latest/html_node/Control-Operations.html#index-fcntl-function
38
#[inline]
39
#[doc(alias = "F_GETFD")]
40
0
pub fn fcntl_getfd<Fd: AsFd>(fd: Fd) -> io::Result<FdFlags> {
41
0
    backend::io::syscalls::fcntl_getfd(fd.as_fd())
42
0
}
43
44
/// `fcntl(fd, F_SETFD, flags)`—Sets a file descriptor's flags.
45
///
46
/// # References
47
///  - [POSIX]
48
///  - [Linux]
49
///  - [Apple]
50
///  - [FreeBSD]
51
///  - [NetBSD]
52
///  - [OpenBSD]
53
///  - [DragonFly BSD]
54
///  - [illumos]
55
///  - [glibc]
56
///
57
/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/fcntl.html
58
/// [Linux]: https://man7.org/linux/man-pages/man2/fcntl.2.html
59
/// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/fcntl.2.html
60
/// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=fcntl&sektion=2
61
/// [NetBSD]: https://man.netbsd.org/fcntl.2
62
/// [OpenBSD]: https://man.openbsd.org/fcntl.2
63
/// [DragonFly BSD]: https://man.dragonflybsd.org/?command=fcntl&section=2
64
/// [illumos]: https://illumos.org/man/2/fcntl
65
/// [glibc]: https://sourceware.org/glibc/manual/latest/html_node/Control-Operations.html#index-fcntl-function
66
#[inline]
67
#[doc(alias = "F_SETFD")]
68
0
pub fn fcntl_setfd<Fd: AsFd>(fd: Fd, flags: FdFlags) -> io::Result<()> {
69
0
    backend::io::syscalls::fcntl_setfd(fd.as_fd(), flags)
70
0
}
71
72
/// `fcntl(fd, F_DUPFD_CLOEXEC)`—Creates a new `OwnedFd` instance, with value
73
/// at least `min`, that has `O_CLOEXEC` set and that shares the same
74
/// underlying [file description] as `fd`.
75
///
76
/// POSIX guarantees that `F_DUPFD_CLOEXEC` will use the lowest unused file
77
/// descriptor which is at least `min`, however it is not safe in general to
78
/// rely on this, as file descriptors may be unexpectedly allocated on other
79
/// threads or in libraries.
80
///
81
/// # References
82
///  - [POSIX]
83
///  - [Linux]
84
///  - [Apple]
85
///  - [FreeBSD]
86
///  - [NetBSD]
87
///  - [OpenBSD]
88
///  - [DragonFly BSD]
89
///  - [illumos]
90
///  - [glibc]
91
///
92
/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/fcntl.html
93
/// [Linux]: https://man7.org/linux/man-pages/man2/fcntl.2.html
94
/// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/fcntl.2.html
95
/// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=fcntl&sektion=2
96
/// [NetBSD]: https://man.netbsd.org/fcntl.2
97
/// [OpenBSD]: https://man.openbsd.org/fcntl.2
98
/// [DragonFly BSD]: https://man.dragonflybsd.org/?command=fcntl&section=2
99
/// [illumos]: https://illumos.org/man/2/fcntl
100
/// [glibc]: https://sourceware.org/glibc/manual/latest/html_node/Control-Operations.html#index-fcntl-function
101
/// [file description]: https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap03.html#tag_03_258
102
#[cfg(not(any(target_os = "espidf", target_os = "wasi")))]
103
#[inline]
104
#[doc(alias = "F_DUPFD_CLOEXEC")]
105
0
pub fn fcntl_dupfd_cloexec<Fd: AsFd>(fd: Fd, min: RawFd) -> io::Result<OwnedFd> {
106
0
    backend::io::syscalls::fcntl_dupfd_cloexec(fd.as_fd(), min)
107
0
}
108
109
/// `fcntl(fd, F_DUPFD)`—Creates a new `OwnedFd` instance, with value at
110
/// least `min`, that shares the same underlying [file description] as `fd`.
111
///
112
/// POSIX guarantees that `F_DUPFD` will use the lowest unused file descriptor
113
/// which is at least `min`, however it is not safe in general to rely on this,
114
/// as file descriptors may be unexpectedly allocated on other threads or in
115
/// libraries.
116
///
117
/// # References
118
///  - [POSIX]
119
///  - [Linux]
120
///  - [Apple]
121
///  - [FreeBSD]
122
///  - [NetBSD]
123
///  - [OpenBSD]
124
///  - [DragonFly BSD]
125
///  - [illumos]
126
///  - [glibc]
127
///
128
/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/fcntl.html
129
/// [Linux]: https://man7.org/linux/man-pages/man2/fcntl.2.html
130
/// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/fcntl.2.html
131
/// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=fcntl&sektion=2
132
/// [NetBSD]: https://man.netbsd.org/fcntl.2
133
/// [OpenBSD]: https://man.openbsd.org/fcntl.2
134
/// [DragonFly BSD]: https://man.dragonflybsd.org/?command=fcntl&section=2
135
/// [illumos]: https://illumos.org/man/2/fcntl
136
/// [glibc]: https://sourceware.org/glibc/manual/latest/html_node/Control-Operations.html#index-fcntl-function
137
/// [file description]: https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap03.html#tag_03_258
138
#[cfg(target_os = "espidf")]
139
#[inline]
140
#[doc(alias = "F_DUPFD")]
141
pub fn fcntl_dupfd<Fd: AsFd>(fd: Fd, min: RawFd) -> io::Result<OwnedFd> {
142
    backend::io::syscalls::fcntl_dupfd(fd.as_fd(), min)
143
}