#![allow(unused_imports, unused_macros)]
crate::CONST! { pub(super),
_DOC_SYS_READ = r#"Performs a [read] syscall.
Read `count` bytes from a file descriptor `fd` into a buffer `buf`.
[read]: https://www.man7.org/linux/man-pages/man2/read.2.html
# Example
```no_run
# use devela::{Linux, LINUX_FILENO};
let mut buf: [u8; 1024] = [0; 1024];
let bytes_read: isize = unsafe {
Linux::sys_read(LINUX_FILENO::STDIN, buf.as_mut_ptr(), buf.len())
};
assert![bytes_read > 0];
```
# Safety
TODO
"#;
_DOC_SYS_WRITE = r#"Performs a [write] syscall.
Writes `count` bytes from a buffer `buf` into a file descriptor `fd`.
If a write() is interrupted by a signal handler before any bytes
are written, then the call fails with the error EINTR; if it is
interrupted after at least one byte has been written, the call
succeeds, and returns the number of bytes written.
[write]: https://www.man7.org/linux/man-pages/man2/write.2.html
# Example
```
# use devela::{Linux, LINUX_FILENO};
let buf = "Hello\n".as_bytes();
let bytes_written: isize = unsafe {
Linux::sys_write(LINUX_FILENO::STDOUT, buf.as_ptr(), buf.len())
};
assert![bytes_written > 0];
```
# Safety
TODO
"#;
_DOC_SYS_OPEN = r#"Performs an [open] syscall.
Opens the file specified by `path` with given `flags` and `mode`.
[open]: https://www.man7.org/linux/man-pages/man2/open.2.html
# Example
```no_run
# use devela::{Linux, LINUX_FILENO, LINUX_O_FLAGS};
let path = b"/tmp/test\0".as_ptr().cast();
let fd = unsafe {
Linux::sys_open(path, LINUX_O_FLAGS::RDWR | LINUX_O_FLAGS::CREAT, 0o644)
};
assert!(fd > 0);
```
# Safety
- path must point to valid null-terminated string
- Caller must ensure proper file permissions
"#;
_DOC_SYS_CLOSE = r#"Performs a [close] syscall.
Closes the file descriptor `fd`.
[close]: https://www.man7.org/linux/man-pages/man2/close.2.html
# Example
```no_run
# use devela::Linux;
let fd = 3; // Example descriptor
let result = unsafe { Linux::sys_close(fd) };
assert_eq!(result, 0);
```
# Safety
- `fd` must be valid open file descriptor
- No further operations should use `fd` after closing
"#;
_DOC_SYS_LSEEK = r#"Performs an [lseek] syscall.
Repositions file offset for `fd` based on `whence`:
- `SEEK_SET` - absolute `offset`
- `SEEK_CUR` - relative to current
- `SEEK_END` - relative to end
[lseek]: https://www.man7.org/linux/man-pages/man2/lseek.2.html
# Example
```no_run
# use devela::{Linux, LINUX_SEEK};
let fd = 3; // Example descriptor
let offset = unsafe { Linux::sys_lseek(fd, 1024, LINUX_SEEK::SET) };
assert!(offset >= 0);
```
# Safety
- `fd` must be open and seekable
- Invalid offsets may return EINVAL
"#;
_DOC_SYS_DUP = r#"Performs a [dup] syscall.
Duplicates file descriptor `oldfd` to lowest-numbered available fd.
[dup]: https://www.man7.org/linux/man-pages/man2/dup.2.html
# Example
```no_run
# use devela::{Linux, LINUX_FILENO};
let new_fd = unsafe { Linux::sys_dup(LINUX_FILENO::STDOUT) };
assert!(new_fd > 0);
```
# Safety
- `oldfd` must be valid open file descriptor
"#;
_DOC_SYS_DUP2 = r#"Performs a [dup2] syscall.
Duplicates `oldfd` to specific `newfd`, closing `newfd` first if open.
[dup2]: https://www.man7.org/linux/man-pages/man2/dup2.2.html
# Example
```no_run
# use devela::{Linux, LINUX_FILENO};
let new_fd = unsafe {
Linux::sys_dup2(LINUX_FILENO::STDOUT, 10) // Duplicate stdout to fd 10
};
assert_eq!(new_fd, 10);
```
# Safety
- Both descriptors must be valid
- May unexpectedly close `newfd` if already open
"#;
_DOC_SYS_FCNTL = r#"Performs a [fcntl] syscall.
Manipulates file descriptor properties (duplication, flags, locks).
[fcntl]: https://www.man7.org/linux/man-pages/man2/fcntl.2.html
# Example
```no_run
# use devela::{Linux, LINUX_F_CMD, LINUX_FILENO};
let fd = 3; // Example descriptor
let flags = unsafe { Linux::sys_fcntl(fd, LINUX_F_CMD::GETFL, 0) };
```
# Safety
- Operation must match expected argument type
- Lock operations require careful process coordination
"#;
_DOC_SYS_STAT = r#"Performs a [stat] syscall.
Gets file status for `path` into `statbuf` (follows symlinks).
[stat]: https://www.man7.org/linux/man-pages/man2/stat.2.html
# Example
```no_run
# use devela::{Linux, LinuxStat};
let path = b"/etc/passwd\0".as_ptr().cast();
let mut stat = LinuxStat::default();
unsafe { Linux::sys_stat(path, &mut stat) };
assert!(stat.st_size > 0);
```
# Safety
- `path` must be valid null-terminated string
- `statbuf` must have full struct alignment
"#;
_DOC_SYS_FSTAT = r#"Performs an [fstat] syscall.
Gets file status for open descriptor `fd` into `statbuf`.
[fstat]: https://www.man7.org/linux/man-pages/man2/fstat.2.html
# Example
```no_run
# use devela::{Linux, LinuxStat};
let mut stat = LinuxStat::default();
let fd = 3; // Example descriptor
unsafe { Linux::sys_fstat(fd, &mut stat) };
assert!(stat.st_mode & 0o777 > 0);
```
# Safety
- `fd` must be valid open descriptor
- Same alignment requirements as `stat`
"#;
_DOC_SYS_GETDENTS = r#"Performs a [getdents] syscall.
Reads directory entries from `fd` into `dirp` buffer of size `count`.
[getdents]: https://www.man7.org/linux/man-pages/man2/getdents.2.html
# Example
```no_run
# use devela::Linux;
let mut buf: [u8; 2048] = [0; 2048];
let dir_fd = 3; // Example descriptor
let entries = unsafe {
Linux::sys_getdents(dir_fd, buf.as_mut_ptr(), buf.len())
};
assert!(entries > 0);
```
# Safety
- `fd` must be valid directory file descriptor
- Buffer must have sufficient size for directory entries
"#;
_DOC_SYS_IOCTL = r#"Performs an [ioctl] syscall.
Performs a generic I/O control operation (ioctl) on the given file descriptor.
The operation to perform and the data to use is determined by the `request`
argument, which is a device-specific request code, and the `argp` argument,
which is a pointer to the data.
[ioctl]: https://www.man7.org/linux/man-pages/man2/ioctl.2.html
# Safety
TODO
"#;
_DOC_SYS_PIPE = r#"Performs a [pipe] syscall.
Creates unidirectional pipe channel. Writes to `pipefd[1]`, reads from `pipefd[0]`.
[pipe]: https://www.man7.org/linux/man-pages/man2/pipe.2.html
# Example
```no_run
# use devela::Linux;
let mut fds = [0; 2];
unsafe { Linux::sys_pipe(fds.as_mut_ptr()) };
assert!(fds[0] > 0 && fds[1] > 0);
```
# Safety
- Buffer must hold exactly 2 integers
- Must close both ends when done
"#;
_DOC_SYS_PIPE2 = r#"Performs a [pipe2] syscall.
Creates pipe with flags (e.g. `LINUX_O_FLAGS::NONBLOCK`).
[pipe2]: https://www.man7.org/linux/man-pages/man2/pipe2.2.html
# Example
```no_run
# use devela::{Linux, LINUX_O_FLAGS};
let mut fds = [0; 2];
unsafe { Linux::sys_pipe2(fds.as_mut_ptr(), LINUX_O_FLAGS::NONBLOCK) };
```
# Safety
- Same as `pipe` plus valid flags
"#;
_DOC_SYS_EXIT = r#"Performs an [exit] syscall.
Terminate the process with an exit status.
[exit]: https://www.man7.org/linux/man-pages/man2/exit.2.html
# Example
```
# use devela::Linux;
# #[cfg(target_os = "linux")]
unsafe { Linux::sys_exit(0) };
```
# Safety
TODO
"#;
_DOC_SYS_GETPID = r#"Performs a [getpid] syscall.
Get process identification.
[getpid]: https://www.man7.org/linux/man-pages/man2/getpid.2.html
# Example
```no_run
# use devela::Linux;
# #[cfg(target_os = "linux")]
let pid: i32 = unsafe { Linux::sys_getpid() };
```
# Safety
TODO
"#;
_DOC_SYS_GETRANDOM = r#"Performs a [getrandom] syscall.
Obtain a series of random bytes.
[getrandom]: https://www.man7.org/linux/man-pages/man2/getrandom.2.html
# Example
```no_run
# use devela::Linux;
let mut r = 0u8;
# #[cfg(target_os = "linux")]
unsafe { Linux::sys_getrandom(&mut r as *mut u8, 1, 0) };
```
# Flags
- `GRND_RANDOM` = 0x001
Use the `/dev/random` (blocking) source instead of the `/dev/urandom`
(non-blocking) source to obtain randomness.
If this flag is specified, the call may block, potentially for quite some
time, even after the randomness source has been initialized. If it is not
specified, the call can only block when the system has just booted and the
randomness source has not yet been initialized.
- `GRND_NONBLOCK` = 0x002
Instead of blocking, return to the caller immediately if no data is available.
- `GRND_INSECURE` = 0x0004
Write random data that may not be cryptographically secure.
# Safety
TODO
"#;
_DOC_SYS_CLOCK_GETRES = r#"Performs a [clock_getres] syscall.
Finds the resolution (precision) of the specified clock `clock_id`
and stores it in the timespec structure pointed to by `tp`.
[clock_getres]: https://www.man7.org/linux/man-pages/man2/clock_getres.2.html
# Safety
TODO
"#;
_DOC_SYS_CLOCK_GETTIME = r#"Performs a [clock_gettime] syscall.
Retrieves the time of the specified clock `clock_id`
and stores it in the timespec structure pointed to by `res`.
Returns the syscall return value (0 for success, -1 for error with errno set).
[clock_gettime]: https://www.man7.org/linux/man-pages/man2/clock_gettime.2.html
# Example
```
# use devela::{Linux, LinuxTimespec, LinuxClock};
let mut tp = LinuxTimespec::default();
# #[cfg(target_os = "linux")]
assert_eq![0, unsafe { Linux::sys_clock_gettime(LinuxClock::Realtime, &mut tp) }];
```
# Safety
TODO
"#;
_DOC_SYS_NANOSLEEP = r#"Performs a [nanosleep] syscall.
Suspend execution of calling thread.
Suspension will last until either the time interval specified in `*req`
has elapsed or a signal is delivered to the calling thread, in which
case the remaining time will be stored in `rem`.
Returns the syscall return value.
[nanosleep]: https://www.man7.org/linux/man-pages/man2/nanosleep.2.html
# Example
```
# use devela::{Duration, Linux, LinuxTimespec};
let mut req = LinuxTimespec::try_from(Duration::from_millis(99)).unwrap();
let mut rem = LinuxTimespec::default();
# #[cfg(target_os = "linux")]
assert_eq![0, unsafe { Linux::sys_nanosleep(&mut req, &mut rem) }];
```
# Safety
TODO
"#;
_DOC_SYS_RT_SIGACTION = r#"Performs an [rt_sigaction] syscall.
Examine and change a signal action.
[rt_sigaction]: https://man7.org/linux/man-pages/man2/rt_sigaction.2.html
# Flags
# Safety
TODO
"#;
}