CStdio — Sn

Module std.libc.cstdio

import std.libc.cstdio;

Public declaration contracts and authored examples. A page can document several related symbols. Implementation bodies are excluded.

<

pub fn<.C> puts(
    [abi.NonNull]
    [abi.NoCapture]
    Value: readonly byte*
) -> i32;

Writes a NUL-terminated C byte string followed by a newline to stdout.

The call borrows Value only until return. It may block, mutate global C stream state, partially emit bytes before failure, and trigger host I/O signal behavior. It does not validate UTF-8 and does not transfer ownership.

Value: Nonnull pointer to the first byte of the C string. Return: A nonnegative value on success or the target C EOF value on failure. Pre: Safety: Value has valid provenance for a live byte-aligned readable range extending through and including its first NUL byte. Pre: Safety: the complete range remains live and free of conflicting concurrent mutation until the call returns; the callee does not retain it. Pre: Safety: the selected libc matches the declared C ABI, its stdio runtime is initialized, and no foreign unwind crosses into Sn. Warning: This is a raw unsafe operation with global output side effects.

Example

module example.puts;
from std.libc.cstdio import puts;
fn Main() -> i32 {
    unsafe {
        return puts(c"ready");
    }
}

<

pub fn<.C> fopen(
    [abi.NonNull]
    [abi.NoCapture]
    Path: readonly byte*,
    [abi.NonNull]
    [abi.NoCapture]
    Mode: readonly byte*
) -> mut byte*;

Opens one C stream from NUL-terminated native path and mode strings.

Path is a native byte pathname and need not be UTF-8. A nonnull result is an opaque live FILE*; its owner synchronizes all uses and eventually closes it exactly once unless immediate process termination reclaims the resource. The input strings are borrowed only for this potentially blocking call.

Path: Nonnull pointer to a NUL-terminated native pathname. Mode: Nonnull pointer to a NUL-terminated target-libc mode string. Return: Null on failure, or an owning opaque open stream pointer on success. Pre: Safety: both pointers have valid provenance for separate live byte-aligned readable ranges extending through their first NUL bytes. Pre: Safety: both ranges remain live and free of conflicting concurrent mutation until return; Mode satisfies the selected libc mode grammar. Pre: Safety: the selected libc matches the declared C ABI, its stdio runtime is initialized, and no foreign unwind crosses into Sn. Warning: May block and inspect or mutate filesystem and libc process state.

Example

module example.fopen;
from std.libc.cstdio import fopen;
fn Main() -> i32 {
    // Any successful stream is intentionally reclaimed by immediate process
    // termination; longer-lived code must test the pointer and call fclose.
    unsafe {
        fopen(c"/dev/null", c"r");
    }
    return 0;
}

<

pub fn<.C> fclose(
    [abi.NonNull]
    [abi.NoCapture]
    Stream: mut byte*
) -> i32;

Flushes as required and consumes one live C stream.

The stream becomes unusable after the call regardless of the result. The operation may block while flushing pending output.

Stream: Nonnull opaque FILE* represented as mut byte*. Return: Zero on success or the target C EOF value on failure. Pre: Safety: Stream has valid provenance, alignment, lifetime, and active C FILE type, denotes a live open stream, and has not already been closed. Pre: Safety: the caller owns close authority, excludes concurrent access or closure, and performs no later use through any alias. Pre: Safety: the selected libc matches the declared C ABI, its stdio runtime is initialized, and no foreign unwind crosses into Sn. Warning: This operation consumes the stream even when it reports failure.

Example

module example.fclose;
from std.libc.cstdio import fclose;
// Safety: Stream satisfies every fclose precondition above.
unsafe fn CloseOwnedStream(Stream: mut byte*) -> i32 {
    unsafe {
        return fclose(Stream);
    }
}
fn Main() -> i32 { return 0; }

<

pub fn<.C> fgetc(
    [abi.NonNull]
    [abi.NoCapture]
    Stream: mut byte*
) -> i32;

Reads the next byte from one live C stream.

The operation may block, fill libc buffers, mutate stream state, and advance the input position. EOF alone does not distinguish end-of-file from error.

Stream: Nonnull opaque FILE* represented as mut byte*. Return: The next unsigned byte converted to i32, or target C EOF. Pre: Safety: Stream denotes a live stream open for input and is byte-oriented or unoriented; update-stream sequencing permits a byte input operation. Pre: Safety: the caller excludes concurrent close and every unsynchronized stream access and never dereferences the opaque pointer as Sn storage. Pre: Safety: the selected libc matches the declared C ABI, its stdio runtime is initialized, and no foreign unwind crosses into Sn. Warning: Mutates stream buffers and position and may block.

Example

module example.fgetc;
from std.libc.cstdio import fgetc;
// Safety: Stream satisfies every fgetc precondition above.
unsafe fn ReadKnownStream(Stream: mut byte*) -> i32 {
    unsafe {
        return fgetc(Stream);
    }
}
fn Main() -> i32 { return 0; }

<

pub fn<.C> fputs(
    [abi.NonNull]
    [abi.NoCapture]
    Value: readonly byte*,
    [abi.NonNull]
    [abi.NoCapture]
    Stream: mut byte*
) -> i32;

Writes one NUL-terminated C byte string to a live C stream.

The operation writes neither the terminator nor an implicit newline. It may block, buffer or partially emit bytes, mutate stream state, and trigger host I/O signal behavior.

Value: Nonnull pointer to the first byte of the C string. Stream: Nonnull opaque FILE* represented as mut byte*. Return: A nonnegative value on success or the target C EOF value on failure. Pre: Safety: Value designates a live byte-aligned readable range through its first NUL and remains live and unmodified until return; it is not retained. Pre: Safety: Stream is live, open for output, byte-oriented or unoriented, correctly sequenced for output, and synchronized against access or close. Pre: Safety: Value does not overlap mutable storage representing Stream; the selected libc matches the ABI and no foreign unwind crosses into Sn. Warning: Mutates stream state and may block or partially output before failure.

Example

module example.fputs;
from std.libc.cstdio import fputs;
// Safety: Stream satisfies every fputs stream precondition above.
unsafe fn WriteKnownStream(Stream: mut byte*) -> i32 {
    unsafe {
        return fputs(c"ready", Stream);
    }
}
fn Main() -> i32 { return 0; }