1//! Vectored I/O
2
3use crate::errno::Errno;
4use crate::Result;
5use libc::{self, c_int, off_t, size_t};
6use std::io::{IoSlice, IoSliceMut};
7use std::os::unix::io::{AsFd, AsRawFd};
8
9/// Low-level vectored write to a raw file descriptor
10///
11/// See also [writev(2)](https://pubs.opengroup.org/onlinepubs/9699919799/functions/writev.html)
12pub fn writev<Fd: AsFd>(fd: Fd, iov: &[IoSlice<'_>]) -> Result<usize> {
13 // SAFETY: to quote the documentation for `IoSlice`:
14 //
15 // [IoSlice] is semantically a wrapper around a &[u8], but is
16 // guaranteed to be ABI compatible with the iovec type on Unix
17 // platforms.
18 //
19 // Because it is ABI compatible, a pointer cast here is valid
20 let res: isize = unsafe {
21 libc::writev(
22 fd.as_fd().as_raw_fd(),
23 iov.as_ptr().cast(),
24 iovcnt:iov.len() as c_int,
25 )
26 };
27
28 Errno::result(res).map(|r: isize| r as usize)
29}
30
31/// Low-level vectored read from a raw file descriptor
32///
33/// See also [readv(2)](https://pubs.opengroup.org/onlinepubs/9699919799/functions/readv.html)
34// Clippy doesn't know that we need to pass iov mutably only because the
35// mutation happens after converting iov to a pointer
36#[allow(clippy::needless_pass_by_ref_mut)]
37pub fn readv<Fd: AsFd>(fd: Fd, iov: &mut [IoSliceMut<'_>]) -> Result<usize> {
38 // SAFETY: same as in writev(), IoSliceMut is ABI-compatible with iovec
39 let res: isize = unsafe {
40 libc::readv(
41 fd.as_fd().as_raw_fd(),
42 iov.as_ptr().cast(),
43 iovcnt:iov.len() as c_int,
44 )
45 };
46
47 Errno::result(res).map(|r: isize| r as usize)
48}
49
50/// Write to `fd` at `offset` from buffers in `iov`.
51///
52/// Buffers in `iov` will be written in order until all buffers have been written
53/// or an error occurs. The file offset is not changed.
54///
55/// See also: [`writev`](fn.writev.html) and [`pwrite`](fn.pwrite.html)
56#[cfg(not(any(target_os = "redox", target_os = "haiku", target_os = "solaris")))]
57pub fn pwritev<Fd: AsFd>(
58 fd: Fd,
59 iov: &[IoSlice<'_>],
60 offset: off_t,
61) -> Result<usize> {
62 #[cfg(target_env = "uclibc")]
63 let offset = offset as libc::off64_t; // uclibc doesn't use off_t
64
65 // SAFETY: same as in writev()
66 let res: isize = unsafe {
67 libc::pwritev(
68 fd.as_fd().as_raw_fd(),
69 iov.as_ptr().cast(),
70 iovcnt:iov.len() as c_int,
71 offset,
72 )
73 };
74
75 Errno::result(res).map(|r: isize| r as usize)
76}
77
78/// Read from `fd` at `offset` filling buffers in `iov`.
79///
80/// Buffers in `iov` will be filled in order until all buffers have been filled,
81/// no more bytes are available, or an error occurs. The file offset is not
82/// changed.
83///
84/// See also: [`readv`](fn.readv.html) and [`pread`](fn.pread.html)
85#[cfg(not(any(target_os = "redox", target_os = "haiku", target_os = "solaris")))]
86// Clippy doesn't know that we need to pass iov mutably only because the
87// mutation happens after converting iov to a pointer
88#[allow(clippy::needless_pass_by_ref_mut)]
89pub fn preadv<Fd: AsFd>(
90 fd: Fd,
91 iov: &mut [IoSliceMut<'_>],
92 offset: off_t,
93) -> Result<usize> {
94 #[cfg(target_env = "uclibc")]
95 let offset = offset as libc::off64_t; // uclibc doesn't use off_t
96
97 // SAFETY: same as in readv()
98 let res: isize = unsafe {
99 libc::preadv(
100 fd.as_fd().as_raw_fd(),
101 iov.as_ptr().cast(),
102 iovcnt:iov.len() as c_int,
103 offset,
104 )
105 };
106
107 Errno::result(res).map(|r: isize| r as usize)
108}
109
110/// Low-level write to a file, with specified offset.
111///
112/// See also [pwrite(2)](https://pubs.opengroup.org/onlinepubs/9699919799/functions/pwrite.html)
113// TODO: move to unistd
114pub fn pwrite<Fd: AsFd>(fd: Fd, buf: &[u8], offset: off_t) -> Result<usize> {
115 let res: isize = unsafe {
116 libc::pwrite(
117 fd.as_fd().as_raw_fd(),
118 buf.as_ptr().cast(),
119 count:buf.len() as size_t,
120 offset,
121 )
122 };
123
124 Errno::result(res).map(|r: isize| r as usize)
125}
126
127/// Low-level read from a file, with specified offset.
128///
129/// See also [pread(2)](https://pubs.opengroup.org/onlinepubs/9699919799/functions/pread.html)
130// TODO: move to unistd
131pub fn pread<Fd: AsFd>(fd: Fd, buf: &mut [u8], offset: off_t) -> Result<usize> {
132 let res: isize = unsafe {
133 libc::pread(
134 fd.as_fd().as_raw_fd(),
135 buf.as_mut_ptr().cast(),
136 count:buf.len() as size_t,
137 offset,
138 )
139 };
140
141 Errno::result(res).map(|r: isize| r as usize)
142}
143
144/// A slice of memory in a remote process, starting at address `base`
145/// and consisting of `len` bytes.
146///
147/// This is the same underlying C structure as `IoSlice`,
148/// except that it refers to memory in some other process, and is
149/// therefore not represented in Rust by an actual slice as `IoSlice` is. It
150/// is used with [`process_vm_readv`](fn.process_vm_readv.html)
151/// and [`process_vm_writev`](fn.process_vm_writev.html).
152#[cfg(linux_android)]
153#[repr(C)]
154#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
155pub struct RemoteIoVec {
156 /// The starting address of this slice (`iov_base`).
157 pub base: usize,
158 /// The number of bytes in this slice (`iov_len`).
159 pub len: usize,
160}
161
162feature! {
163#![feature = "process"]
164
165/// Write data directly to another process's virtual memory
166/// (see [`process_vm_writev`(2)]).
167///
168/// `local_iov` is a list of [`IoSlice`]s containing the data to be written,
169/// and `remote_iov` is a list of [`RemoteIoVec`]s identifying where the
170/// data should be written in the target process. On success, returns the
171/// number of bytes written, which will always be a whole
172/// number of `remote_iov` chunks.
173///
174/// This requires the same permissions as debugging the process using
175/// [ptrace]: you must either be a privileged process (with
176/// `CAP_SYS_PTRACE`), or you must be running as the same user as the
177/// target process and the OS must have unprivileged debugging enabled.
178///
179/// This function is only available on Linux and Android(SDK23+).
180///
181/// [`process_vm_writev`(2)]: https://man7.org/linux/man-pages/man2/process_vm_writev.2.html
182/// [ptrace]: ../ptrace/index.html
183/// [`IoSlice`]: https://doc.rust-lang.org/std/io/struct.IoSlice.html
184/// [`RemoteIoVec`]: struct.RemoteIoVec.html
185#[cfg(all(linux_android, not(target_env = "uclibc")))]
186pub fn process_vm_writev(
187 pid: crate::unistd::Pid,
188 local_iov: &[IoSlice<'_>],
189 remote_iov: &[RemoteIoVec]) -> Result<usize>
190{
191 let res = unsafe {
192 libc::process_vm_writev(pid.into(),
193 local_iov.as_ptr().cast(), local_iov.len() as libc::c_ulong,
194 remote_iov.as_ptr().cast(), remote_iov.len() as libc::c_ulong, 0)
195 };
196
197 Errno::result(res).map(|r| r as usize)
198}
199
200/// Read data directly from another process's virtual memory
201/// (see [`process_vm_readv`(2)]).
202///
203/// `local_iov` is a list of [`IoSliceMut`]s containing the buffer to copy
204/// data into, and `remote_iov` is a list of [`RemoteIoVec`]s identifying
205/// where the source data is in the target process. On success,
206/// returns the number of bytes written, which will always be a whole
207/// number of `remote_iov` chunks.
208///
209/// This requires the same permissions as debugging the process using
210/// [`ptrace`]: you must either be a privileged process (with
211/// `CAP_SYS_PTRACE`), or you must be running as the same user as the
212/// target process and the OS must have unprivileged debugging enabled.
213///
214/// This function is only available on Linux and Android(SDK23+).
215///
216/// [`process_vm_readv`(2)]: https://man7.org/linux/man-pages/man2/process_vm_readv.2.html
217/// [`ptrace`]: ../ptrace/index.html
218/// [`IoSliceMut`]: https://doc.rust-lang.org/std/io/struct.IoSliceMut.html
219/// [`RemoteIoVec`]: struct.RemoteIoVec.html
220#[cfg(all(linux_android, not(target_env = "uclibc")))]
221pub fn process_vm_readv(
222 pid: crate::unistd::Pid,
223 local_iov: &mut [IoSliceMut<'_>],
224 remote_iov: &[RemoteIoVec]) -> Result<usize>
225{
226 let res = unsafe {
227 libc::process_vm_readv(pid.into(),
228 local_iov.as_ptr().cast(), local_iov.len() as libc::c_ulong,
229 remote_iov.as_ptr().cast(), remote_iov.len() as libc::c_ulong, 0)
230 };
231
232 Errno::result(res).map(|r| r as usize)
233}
234}
235