nstd_sys/io/
stdout.rs

1//! A handle to the standard output 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::{Stdout, StdoutLock};
12#[cfg(unix)]
13use std::os::unix::io::AsRawFd;
14
15/// A handle to the standard output stream.
16#[nstdapi]
17pub struct NSTDStdout {
18    /// Rust's [Stdout].
19    out: CBox<Stdout>,
20}
21gen_optional!(NSTDOptionalStdout, NSTDStdout);
22
23/// Constructs a new handle to the standard output stream.
24///
25/// # Returns
26///
27/// `NSTDOptionalStdout handle` - A handle to the standard output stream on success, or an
28/// uninitialized "none" variant on error.
29#[inline]
30#[nstdapi]
31pub fn nstd_io_stdout() -> NSTDOptionalStdout {
32    CBox::new(std::io::stdout()).map_or(NSTDOptional::None, |out| {
33        NSTDOptional::Some(NSTDStdout { out })
34    })
35}
36
37/// Writes some data to the standard output 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/// - `NSTDStdout *handle` - A handle to stdout.
47///
48/// - `const NSTDSlice *bytes` - The data to be written to stdout.
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_stdout_write(handle: &mut NSTDStdout, bytes: &NSTDSlice) -> NSTDIOResult {
61    #[cfg(not(unix))]
62    return crate::io::stdio::write(&mut *handle.out, bytes);
63    #[cfg(unix)]
64    return crate::os::unix::io::stdio::write(handle.out.lock().as_raw_fd(), bytes).into();
65}
66
67/// Writes an entire buffer to the standard output 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/// - `NSTDStdout *handle` - A handle to stdout.
77///
78/// - `const NSTDSlice *bytes` - The data to be written to stdout.
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_stdout_write_all(handle: &mut NSTDStdout, bytes: &NSTDSlice) -> NSTDIOError {
90    #[cfg(not(unix))]
91    return crate::io::stdio::write_all(&mut *handle.out, bytes);
92    #[cfg(unix)]
93    return crate::os::unix::io::stdio::write_all(handle.out.lock().as_raw_fd(), bytes).into();
94}
95
96/// Flushes the standard output stream.
97///
98/// # Parameters:
99///
100/// - `NSTDStdout *handle` - A handle to stdout.
101///
102/// # Returns
103///
104/// `NSTDIOError errc` - The I/O operation error code.
105#[inline]
106#[nstdapi]
107pub fn nstd_io_stdout_flush(handle: &mut NSTDStdout) -> NSTDIOError {
108    crate::io::stdio::flush(&mut *handle.out)
109}
110
111/// Frees an instance of `NSTDStdout`.
112///
113/// # Parameters:
114///
115/// - `NSTDStdout handle` - A handle to the standard output 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_stdout_free(handle: NSTDStdout) {}
124
125/// A locked handle to the standard output stream.
126#[nstdapi]
127pub struct NSTDStdoutLock {
128    /// Rust's [StdoutLock].
129    out: CBox<StdoutLock<'static>>,
130}
131gen_optional!(NSTDOptionalStdoutLock, NSTDStdoutLock);
132
133/// Constructs a new locked handle to the standard output stream.
134///
135/// # Returns
136///
137/// `NSTDOptionalStdoutLock handle` - A locked handle to the standard output stream on success, or
138/// an uninitialized "none" variant on error.
139#[inline]
140#[nstdapi]
141pub fn nstd_io_stdout_lock() -> NSTDOptionalStdoutLock {
142    CBox::new(std::io::stdout().lock()).map_or(NSTDOptional::None, |out| {
143        NSTDOptional::Some(NSTDStdoutLock { out })
144    })
145}
146
147/// Writes some data to the standard output stream.
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/// - `NSTDStdoutLock *handle` - A locked handle to stdout.
157///
158/// - `const NSTDSlice *bytes` - The data to be written to stdout.
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_stdout_lock_write(
171    handle: &mut NSTDStdoutLock,
172    bytes: &NSTDSlice,
173) -> NSTDIOResult {
174    #[cfg(not(unix))]
175    return crate::io::stdio::write(&mut *handle.out, bytes);
176    #[cfg(unix)]
177    return crate::os::unix::io::stdio::write(handle.out.as_raw_fd(), bytes).into();
178}
179
180/// Writes an entire buffer to the standard output 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/// - `NSTDStdoutLock *handle` - A locked handle to stdout.
190///
191/// - `const NSTDSlice *bytes` - The data to be written to stdout.
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_stdout_lock_write_all(
203    handle: &mut NSTDStdoutLock,
204    bytes: &NSTDSlice,
205) -> NSTDIOError {
206    #[cfg(not(unix))]
207    return crate::io::stdio::write_all(&mut *handle.out, bytes);
208    #[cfg(unix)]
209    return crate::os::unix::io::stdio::write_all(handle.out.as_raw_fd(), bytes).into();
210}
211
212/// Flushes the standard output stream.
213///
214/// # Parameters:
215///
216/// - `NSTDStdoutLock *handle` - A locked handle to stdout.
217///
218/// # Returns
219///
220/// `NSTDIOError errc` - The I/O operation error code.
221#[inline]
222#[nstdapi]
223pub fn nstd_io_stdout_lock_flush(handle: &mut NSTDStdoutLock) -> NSTDIOError {
224    crate::io::stdio::flush(&mut *handle.out)
225}
226
227/// Frees and unlocks an instance of `NSTDStdoutLock`.
228///
229/// # Parameters:
230///
231/// - `NSTDStdoutLock handle` - A locked handle to the standard output 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_stdout_unlock(handle: NSTDStdoutLock) {}
nstd_sys/io/stdout.rs

nstd_sys/io/
stdout.rs
