r_linux/syscall/
api.rs

1//! System Call API
2//!
3//! This module provides symbols for all available system calls, implementing a
4//! uniform API to call into the kernel. Any architecture-peculiarities are
5//! hidden from the caller, except if they leak into external data definitions.
6//! That is, binary formatting of argument structures still need to be
7//! performed by the caller. However, correct syscall invocation and splitting
8//! across registers is performed by these helpers.
9
10pub use super::raw::Retval;
11
12/// Restart System Call
13///
14/// This system call continues an interrupted system call with the same
15/// parameters it was initially called, adjusted only for the time difference
16/// between the original syscall and now.
17///
18/// This system call is used by the kernel itself to resume system calls of
19/// frozen processes. Whenever a system call is interrupted, the kernel saves
20/// the system call parameters and restarts the system call with the same
21/// parameters once the task is resumed again. However, for system calls that
22/// take relative time-frames as arguments, the kernel usually needs to adjust
23/// these relative time-frames for the elapsed time. For those system calls,
24/// the kernel refrains from restarting the system call directly and instead
25/// changes the system call number of the to-be-restarted call to this system
26/// call. When this system call is then invoked, the kernel fetches the
27/// original system call and its parameters from its internal state, adjusts
28/// the relative timeout, and then restarts the original system call.
29///
30/// There is usually no reason why you would ever invoke this system call from
31/// user-space. Moreover, even when the kernel triggers a syscall restart with
32/// this system call, it never leaves kernel space, and thus user-space should
33/// never see this system call at all. Tracing debuggers might see it, though.
34/// And they are the only ones that might reasonable interfere with it.
35///
36/// If no system call is to be resumed, this system call returns `EINTR`.
37/// Otherwise, it resumes the original system call with adjusted relative time
38/// parameters and returns the result of the resumed system call.
39pub unsafe fn restart_syscall() -> Retval {
40    super::raw::syscall0(
41        super::arch::native::nr::RESTART_SYSCALL,
42    )
43}
44
45/// Exit Task
46///
47/// `fn sys_exit(code: u32) -> !`
48///
49/// Stop the current execution and tear down this task. Other tasks of a
50/// possible thread group are left around. See the linux task model for
51/// information how threads and processes map to linux tasks.
52///
53/// Takes a single argument `code` which specifies the exit condition of the
54/// running task.
55///
56/// This system call never returns, under no circumstances. This also implies
57/// that this system call cannot be interrupted.
58pub use crate::syscall::arch::native::nr::EXIT;
59
60/// Fork Task
61///
62/// XXX
63pub use crate::syscall::arch::native::nr::FORK;
64
65/// Read from File-Descriptor
66///
67/// XXX
68pub use crate::syscall::arch::native::nr::READ;
69
70/// Write to File-Descriptor
71///
72/// XXX
73pub use crate::syscall::arch::native::nr::WRITE;
74
75/// Open File
76///
77/// XXX
78pub use crate::syscall::arch::native::nr::OPEN;
79
80/// Close File Descriptor
81///
82/// `fn sys_close(fd: u32) -> i32`
83///
84/// Close the file-descriptor specified by the first argument. First, the
85/// file-descriptor is unlinked from the file-descriptor table of the calling
86/// task, then the reference count of the open file-description is decremented
87/// and possibly released thereafter.
88///
89/// This system call always unlinks the file-descriptor from the
90/// file-descriptor table of the calling task. That is, if the passed
91/// file-descriptor is valid, it is always invalidated by this system call,
92/// regardless of the return code, even if `EINTR` is returned. You must never
93/// repeat or restart this system call.
94///
95/// Takes a single argument `fd` which specifies the file-descriptor to close.
96/// Unlike most other system calls, this type is `unsigned`, but that should
97/// make no observable difference to the caller.
98///
99/// This system call returns `EBADF` if the specified file-descriptor was
100/// invalid. In this case, this system call was a no-op. In all other cases,
101/// regardless of the return code, the system call actually closed the
102/// file-descriptor. Moreover, if this did not release the underlying open
103/// file-description, then this will always return 0.
104/// However, if this system call ends up releasing the underlying open
105/// file-description, the teardown operation of just this can trigger any kind
106/// of writeback, cache-invalidation, resource relinking, rcu grace period,
107/// etc., and thus might take a considerable amount of time. Furthermore, for
108/// historical reasons, this final teardown can also return arbitrary error
109/// codes from deep down in the kernel device drivers (even confusingly
110/// allowing `EBADF`). Given that, you should never check the return value of
111/// this system call, but always assume it succeeded.
112///
113/// Lastly, you must never assume that a call to this operation actually
114/// performs a final teardown of the underlying open file-description. Any
115/// temporary, parallel kernel maintenance thread might pin the same open
116/// file-description for a short moment, and thus delay the teardown for an
117/// arbitrary amount of time. This especially means you *MUST NOT* rely on this
118/// function implying an `fsync()`, unless you verified this via the kernel
119/// sources yourself.
120pub use crate::syscall::arch::native::nr::CLOSE;
121
122/// XXX
123pub use crate::syscall::arch::native::nr::LSEEK;
124
125/// XXX
126pub use crate::syscall::arch::native::nr::GETPID;
127
128/// XXX
129pub use crate::syscall::arch::native::nr::PIPE2;
130
131/// XXX
132pub use crate::syscall::arch::native::nr::MEMFD_CREATE;
133
134/// XXX
135pub use crate::syscall::arch::native::nr::READLINKAT;
136
137/// XXX
138pub use crate::syscall::arch::native::nr::STATX;
139
140/// XXX
141pub use crate::syscall::arch::native::nr::COPY_FILE_RANGE;
142
143/// XXX
144pub use crate::syscall::arch::native::nr::DUP;
145
146/// XXX
147pub use crate::syscall::arch::native::nr::DUP2;
148
149/// XXX
150pub use crate::syscall::arch::native::nr::DUP3;
r_linux/syscall/api.rs

r_linux/syscall/
api.rs
