blob: 8990c05ef94829970c525963afdb71def6f709d6 [file]
// Copyright 2026 The Fuchsia Authors
//
// Use of this source code is governed by a MIT-style
// license that can be found in the LICENSE file or at
// https://opensource.org/licenses/MIT
use core::ffi::{VaList, c_char, c_int, c_void};
use core::fmt;
use core::mem::{align_of, size_of};
mod string_file;
pub use string_file::{ScopedFile, StringFile};
/// The C++ `FILE::Callback` signature: `int(void* ptr, const char* str, size_t len)`.
pub type FileCallback = unsafe extern "C" fn(*mut c_void, *const c_char, usize) -> c_int;
/// This represents the kernel `<stdio.h>` `FILE` type.
#[repr(C)]
pub struct FILE {
write: Option<FileCallback>,
ptr: *mut c_void,
}
const _: () = {
assert!(size_of::<FILE>() == 16);
assert!(align_of::<FILE>() == 8);
};
impl FILE {
/// Creates a `FILE` that sends everything written to it to `write`, passing `ptr` as the
/// callback's first argument, like the C++ `FILE(Callback* write, void* ptr)` constructor.
///
/// # Safety
///
/// For the lifetime of the returned `FILE`, `write` (if present) must be sound to call with
/// `ptr` and any `(data, len)` where `data` points to `len` readable bytes when `len > 0` (and
/// may be null when `len == 0`).
pub const unsafe fn new(write: Option<FileCallback>, ptr: *mut c_void) -> Self {
Self { write, ptr }
}
/// Writes `bytes` via the callback of `*this` without forming a Rust reference to `*this`.
///
/// Returns the callback's result, or -1 if `*this` has no callback.
///
/// # Safety
///
/// `this` must be non-null, aligned, and point to an initialized `FILE` whose `write` and
/// `ptr` fields can be read without a data race, and whose `write` callback (if `Some`) is
/// sound to call with `(ptr, bytes.as_ptr().cast::<c_char>(), bytes.len())`.
pub unsafe fn write_raw(this: *const Self, bytes: &[u8]) -> c_int {
// SAFETY: The caller guarantees `this` is non-null, aligned, and points to an initialized
// `FILE` whose `write` field is valid to read.
let Some(write) = (unsafe { (*this).write }) else {
return -1;
};
// SAFETY: The caller guarantees `this` is non-null, aligned, and points to an initialized
// `FILE` whose `ptr` field is valid to read.
let ptr = unsafe { (*this).ptr };
// SAFETY:
// - `ptr` is the context uniquely paired with `write` by the C API.
// - `bytes` points to a valid sequence of `bytes.len()` bytes that remains valid and
// immutable for the duration of the FFI call.
unsafe { write(ptr, bytes.as_ptr().cast::<c_char>(), bytes.len()) }
}
/// Writes `bytes` via the callback, like the C++ `FILE::Write`. This is what `fprintf` calls
/// to do output.
///
/// Returns the callback's result, or -1 if this `FILE` has no callback.
pub fn write(&self, bytes: &[u8]) -> c_int {
// SAFETY: `self` is a valid, aligned, initialized `FILE` whose `write` and `ptr` fields
// satisfy `Self::new`'s safety contract.
unsafe { Self::write_raw(core::ptr::from_ref(self), bytes) }
}
}
impl fmt::Write for FILE {
fn write_str(&mut self, s: &str) -> fmt::Result {
if self.write(s.as_bytes()) < 0 { Err(fmt::Error) } else { Ok(()) }
}
}
/// Returns a pointer to the kernel's global `gStdout`, matching `<stdio.h>` `stdout`.
///
/// `gStdout` is initialized during early boot once global constructors run and uses a thread-safe
/// write callback without further mutation during normal kernel operation (note that `console_rust`
/// unit tests temporarily overwrite `*stdout()` assuming quiescent output).
#[inline]
pub fn stdout() -> *mut FILE {
&raw mut gStdout
}
unsafe extern "C" {
/// The kernel's `<stdio.h>` `gStdout`.
#[allow(non_upper_case_globals)]
static mut gStdout: FILE;
/// Writes formatted output to `f`, matching `<stdio.h>` `fprintf`.
///
/// # Safety
///
/// `f` must point to a valid `FILE`. `fmt` must be non-null and point to a valid
/// NUL-terminated C format string whose format specifiers match the variadic arguments.
pub fn fprintf(f: *mut FILE, fmt: *const c_char, ...) -> c_int;
/// Writes `VaList` formatted output to `f`, matching `<stdio.h>` `vfprintf`.
///
/// # Safety
///
/// `f` must point to a valid `FILE`. `fmt` must be non-null and point to a valid
/// NUL-terminated C format string whose format specifiers match the arguments in `ap`.
pub fn vfprintf(f: *mut FILE, fmt: *const c_char, ap: VaList<'_>) -> c_int;
}