nstd_sys/io/
stderr.rs

1//! A handle to the standard error stream.
2use crate::{
3    alloc::CBox,
4    core::{
5        optional::{gen_optional, NSTDOptional},
6        slice::NSTDSlice,
7    },
8    io::{NSTDIOError, NSTDIOResult},
9};
10use nstdapi::nstdapi;
11use std::io::{Stderr, StderrLock};
12#[cfg(unix)]
13use std::os::unix::io::AsRawFd;
14
15/// A handle to the standard error stream.
16#[nstdapi]
17pub struct NSTDStderr {
18    /// Rust's [Stderr].
19    err: CBox<Stderr>,
20}
21gen_optional!(NSTDOptionalStderr, NSTDStderr);
22
23/// Constructs a new handle to the standard error stream.
24///
25/// # Returns
26///
27/// `NSTDOptionalStderr handle` - A handle to the standard error stream, or an uninitialized "none"
28/// variant on error.
29#[inline]
30#[nstdapi]
31pub fn nstd_io_stderr() -> NSTDOptionalStderr {
32    CBox::new(std::io::stderr()).map_or(NSTDOptional::None, |err| {
33        NSTDOptional::Some(NSTDStderr { err })
34    })
35}
36
37/// Writes some data to the standard error stream, returning how many bytes were written.
38///
39/// # Note
40///
41/// This function will return an error code of `NSTD_IO_ERROR_INVALID_INPUT` if the slice's element
42/// size is not 1.
43///
44/// # Parameters:
45///
46/// - `NSTDStderr *handle` - A handle to stderr.
47///
48/// - `const NSTDSlice *bytes` - The data to be written to stderr.
49///
50/// # Returns
51///
52/// `NSTDIOResult written` - The number of bytes written to `handle` on success, or the I/O
53/// operation error code on failure.
54///
55/// # Safety
56///
57/// This function can cause undefined behavior if `bytes`'s data is invalid.
58#[inline]
59#[nstdapi]
60pub unsafe fn nstd_io_stderr_write(handle: &mut NSTDStderr, bytes: &NSTDSlice) -> NSTDIOResult {
61    #[cfg(not(unix))]
62    return crate::io::stdio::write(&mut *handle.err, bytes);
63    #[cfg(unix)]
64    return crate::os::unix::io::stdio::write(handle.err.lock().as_raw_fd(), bytes).into();
65}
66
67/// Writes an entire buffer to the standard error stream.
68///
69/// # Note
70///
71/// This function will return an error code of `NSTD_IO_ERROR_INVALID_INPUT` if the slice's element
72/// size is not 1.
73///
74/// # Parameters:
75///
76/// - `NSTDStderr *handle` - A handle to stderr.
77///
78/// - `const NSTDSlice *bytes` - The data to be written to stderr.
79///
80/// # Returns
81///
82/// `NSTDIOError errc` - The I/O operation error code.
83///
84/// # Safety
85///
86/// This function can cause undefined behavior if `bytes`'s data is invalid.
87#[inline]
88#[nstdapi]
89pub unsafe fn nstd_io_stderr_write_all(handle: &mut NSTDStderr, bytes: &NSTDSlice) -> NSTDIOError {
90    #[cfg(not(unix))]
91    return crate::io::stdio::write_all(&mut *handle.err, bytes);
92    #[cfg(unix)]
93    return crate::os::unix::io::stdio::write_all(handle.err.lock().as_raw_fd(), bytes).into();
94}
95
96/// Flushes the standard error stream.
97///
98/// # Parameters:
99///
100/// - `NSTDStderr *handle` - A handle to stderr.
101///
102/// # Returns
103///
104/// `NSTDIOError errc` - The I/O operation error code.
105#[inline]
106#[nstdapi]
107pub fn nstd_io_stderr_flush(handle: &mut NSTDStderr) -> NSTDIOError {
108    crate::io::stdio::flush(&mut *handle.err)
109}
110
111/// Frees an instance of `NSTDStderr`.
112///
113/// # Parameters:
114///
115/// - `NSTDStderr handle` - A handle to the standard error stream.
116#[inline]
117#[nstdapi]
118#[allow(
119    unused_variables,
120    clippy::missing_const_for_fn,
121    clippy::needless_pass_by_value
122)]
123pub fn nstd_io_stderr_free(handle: NSTDStderr) {}
124
125/// A locked handle to the standard error stream.
126#[nstdapi]
127pub struct NSTDStderrLock {
128    /// Rust's [StderrLock].
129    err: CBox<StderrLock<'static>>,
130}
131gen_optional!(NSTDOptionalStderrLock, NSTDStderrLock);
132
133/// Constructs a new locked handle to the standard error stream.
134///
135/// # Returns
136///
137/// `NSTDOptionalStderrLock handle` - A locked handle to the standard error stream on success, or
138/// an uninitialized "none" variant on error.
139#[inline]
140#[nstdapi]
141pub fn nstd_io_stderr_lock() -> NSTDOptionalStderrLock {
142    CBox::new(std::io::stderr().lock()).map_or(NSTDOptional::None, |err| {
143        NSTDOptional::Some(NSTDStderrLock { err })
144    })
145}
146
147/// Writes some data to the standard error stream, returning how many bytes were written.
148///
149/// # Note
150///
151/// This function will return an error code of `NSTD_IO_ERROR_INVALID_INPUT` if the slice's element
152/// size is not 1.
153///
154/// # Parameters:
155///
156/// - `NSTDStderrLock *handle` - A locked handle to stderr.
157///
158/// - `const NSTDSlice *bytes` - The data to be written to stderr.
159///
160/// # Returns
161///
162/// `NSTDIOResult written` - The number of bytes written to `handle` on success, or the I/O
163/// operation error code on failure.
164///
165/// # Safety
166///
167/// This function can cause undefined behavior if `bytes`'s data is invalid.
168#[inline]
169#[nstdapi]
170pub unsafe fn nstd_io_stderr_lock_write(
171    handle: &mut NSTDStderrLock,
172    bytes: &NSTDSlice,
173) -> NSTDIOResult {
174    #[cfg(not(unix))]
175    return crate::io::stdio::write(&mut *handle.err, bytes);
176    #[cfg(unix)]
177    return crate::os::unix::io::stdio::write(handle.err.as_raw_fd(), bytes).into();
178}
179
180/// Writes an entire buffer to the standard error stream.
181///
182/// # Note
183///
184/// This function will return an error code of `NSTD_IO_ERROR_INVALID_INPUT` if the slice's element
185/// size is not 1.
186///
187/// # Parameters:
188///
189/// - `NSTDStderrLock *handle` - A locked handle to stderr.
190///
191/// - `const NSTDSlice *bytes` - The data to be written to stderr.
192///
193/// # Returns
194///
195/// `NSTDIOError errc` - The I/O operation error code.
196///
197/// # Safety
198///
199/// This function can cause undefined behavior if `bytes`'s data is invalid.
200#[inline]
201#[nstdapi]
202pub unsafe fn nstd_io_stderr_lock_write_all(
203    handle: &mut NSTDStderrLock,
204    bytes: &NSTDSlice,
205) -> NSTDIOError {
206    #[cfg(not(unix))]
207    return crate::io::stdio::write_all(&mut *handle.err, bytes);
208    #[cfg(unix)]
209    return crate::os::unix::io::stdio::write_all(handle.err.as_raw_fd(), bytes).into();
210}
211
212/// Flushes the standard error stream.
213///
214/// # Parameters:
215///
216/// - `NSTDStderrLock *handle` - A locked handle to stderr.
217///
218/// # Returns
219///
220/// `NSTDIOError errc` - The I/O operation error code.
221#[inline]
222#[nstdapi]
223pub fn nstd_io_stderr_lock_flush(handle: &mut NSTDStderrLock) -> NSTDIOError {
224    crate::io::stdio::flush(&mut *handle.err)
225}
226
227/// Frees and unlocks an instance of `NSTDStderrLock`.
228///
229/// # Parameters:
230///
231/// - `NSTDStderrLock handle` - A locked handle to the standard error stream.
232#[inline]
233#[nstdapi]
234#[allow(
235    unused_variables,
236    clippy::missing_const_for_fn,
237    clippy::needless_pass_by_value
238)]
239pub fn nstd_io_stderr_unlock(handle: NSTDStderrLock) {}
nstd_sys/io/stderr.rs

nstd_sys/io/
stderr.rs
