explain_wait3(3)

🎀 NAME 🎀

okay so this whole page is about explain_wait3, and its one job is literally explaining wait3(2) errors. that's it. that's the vibe. 💅

---

✨ SYNOPSIS ✨

bestie, here's the roster of functions you're getting, and yes you gotta include the header first:

#include <libexplain/wait3.h>
const char *explain_wait3(int *status, int options, struct rusage *rusage);
const char *explain_errno_wait3(int errnum, int *status, int options, struct rusage *rusage);
void explain_message_wait3(char *message, int message_size, int *status, int options, struct rusage *rusage);
void explain_message_errno_wait3(char *message, int message_size, int errnum, int *status, int options, struct rusage *rusage);

---

💖 DESCRIPTION 💖

so these functions? they're your little translator besties for errors that come back from the wait3(2) system call. instead of you squinting at a cryptic error, they hand you a whole explanation. iconic behavior honestly. 🫶

🌸 explain_wait3 🌸

const char *explain_wait3(int *status, int options, struct rusage *rusage);

the explain_wait3 function gets you an explanation of an error that came back from the wait3(2) system call. the absolute bare minimum it'll give you is the value of strerror(errno), but ngl it usually does way better than that and points at the actual underlying cause in more detail. slay. ✨

it pulls the error value it's gonna decode from the errno global variable.

you're meant to use this one like, basically like this:

int pid = wait3(status, options, rusage);
if (pid < 0)
{
    fprintf(stderr, "%s\n", explain_wait3(status, options, rusage));
    exit(EXIT_FAILURE);
}

• status — the original status, exactly as passed to the wait3(2) system call. no edits, no glow-ups, just as-is.
• options — the original options, exactly as passed to the wait3(2) system call.
• rusage — the original rusage, exactly as passed to the wait3(2) system call.

Returns:

• the message explaining the error. lowkey important: this message buffer is shared by all the libexplain functions that don't supply a buffer in their argument list. so the next call to any libexplain function that shares this buffer will overwrite it — including calls from other threads. 😭

Note: this function is not thread safe, because it shares a return buffer across all threads, and many other functions in this library do the same thing. so, like, be careful out there.

🦋 explain_errno_wait3 🦋

const char *explain_errno_wait3(int errnum, int *status, int options, struct rusage *rusage);

the explain_errno_wait3 function gets you an explanation of an error returned by the wait3(2) system call. least it'll give you is the value of strerror(errnum), but usually it does so much better and tells you the underlying cause in more detail. periodt.

use it like this, bestie:

int pid = wait3(status, options, rusage);
if (pid < 0)
{
    int err = errno;
    fprintf(stderr, "%s\n", explain_errno_wait3(err, status, options,
        rusage));
    exit(EXIT_FAILURE);
}

• errnum — the error value to be decoded, usually grabbed from the errno global variable right before you call this function. you need to do that if there's any code running between the system call you're explaining and this function, because a whole bunch of libc functions will change the value of errno on you. sneaky. 💀
• status — the original status, exactly as passed to the wait3(2) system call.
• options — the original options, exactly as passed to the wait3(2) system call.
• rusage — the original rusage, exactly as passed to the wait3(2) system call.

Returns:

• the message explaining the error. and again, this message buffer is shared by all libexplain functions that don't supply a buffer in their argument list, so the next call to any libexplain function sharing this buffer will overwrite it — other threads included.

Note: this function is not thread safe, because it shares a return buffer across all threads, and many other functions in this library do too.

🧚 explain_message_wait3 🧚

void explain_message_wait3(char *message, int message_size, int *status, int options, struct rusage *rusage);

the explain_message_wait3 function may be used to obtain an explanation of an error returned by the wait3(2) system call. minimum content is the value of strerror(errno), but bestie, usually it goes way harder and shows the underlying cause in more detail. 🔥

it uses the errno global variable to get the error value that needs decoding.

use it like:

int pid = wait3(status, options, rusage);
if (pid < 0)
{
    char message[3000];
    explain_message_wait3(message, sizeof(message),
        status, options, rusage);
    fprintf(stderr, "%s\n", message);
    exit(EXIT_FAILURE);
}

• message — the location where the returned message gets stored. and here's the glow-up: if you supply a suitable message return buffer, this function is thread safe. we love that for you. 💖
• message_size — the size in bytes of the location where the returned message gets stored.
• status — the original status, exactly as passed to the wait3(2) system call.
• options — the original options, exactly as passed to the wait3(2) system call.
• rusage — the original rusage, exactly as passed to the wait3(2) system call.

🍓 explain_message_errno_wait3 🍓

void explain_message_errno_wait3(char *message, int message_size, int errnum, int *status, int options, struct rusage *rusage);

the explain_message_errno_wait3 function may be used to obtain an explanation of an error returned by the wait3(2) system call. the least the message will contain is the value of strerror(errnum), but usually it does much better and indicates the underlying cause in more detail. she ate. 👑

use it like this:

int pid = wait3(status, options, rusage);
if (pid < 0)
{
    int err = errno;
    char message[3000];
    explain_message_errno_wait3(message, sizeof(message), err,
        status, options, rusage);
    fprintf(stderr, "%s\n", message);
    exit(EXIT_FAILURE);
}

• message — the location where the returned message gets stored. if a suitable message return buffer is supplied, this function is thread safe. 💜
• message_size — the size in bytes of the location where the returned message gets stored.
• errnum — the error value to be decoded, usually obtained from the errno global variable just before this function is called. this is necessary if you need to call any code between the system call being explained and this function, because many libc functions will alter the value of errno. no cap.
• status — the original status, exactly as passed to the wait3(2) system call.
• options — the original options, exactly as passed to the wait3(2) system call.
• rusage — the original rusage, exactly as passed to the wait3(2) system call.

---

🌈 SEE ALSO 🌈

• wait3(2) — wait for process to change state
• explain_wait3_or_die(3) — wait for process to change state and report errors

---

👑 COPYRIGHT 👑

libexplain version 1.4 Copyright (C) 2008 Peter Miller

---

and that's the whole page bestie, mwah 💅✨ the explain_wait3(3) manual page, version 1.4 energy, dated all the way back to the 2008 copyright era — she's vintage and she's still iconic, fr fr 🎀🦋💖