explain_setpgid(3)

💖 explain_setpgid(3) 💖

okay bestie, we're in the Library Functions Manual today and this page is literally all about explain_setpgid — the glow-up your setpgid(2) error messages have been waiting for. ✨

---

🌸 NAME 🌸

explain_setpgid — the way to, like, explain setpgid(2) errors. no cap.

---

✨ SYNOPSIS ✨

#include <libexplain/setpgid.h>
const char *explain_setpgid(pid_t pid, pid_t pgid);
const char *explain_errno_setpgid(int errnum, pid_t pid, pid_t pgid);
void explain_message_setpgid(char *message, int message_size, pid_t pid,
pid_t pgid);
void explain_message_errno_setpgid(char *message, int message_size, int
errnum, pid_t pid, pid_t pgid);

---

🦋 DESCRIPTION 🦋

so like, these functions? they exist to hand you explanations for errors that the setpgid(2) system call throws back at you. instead of a sad little mystery, you get ✨lore✨. 💅

💜 explain_setpgid

const char *explain_setpgid(pid_t pid, pid_t pgid);

explain_setpgid is the one you call to get an explanation of an error returned by setpgid(2). the bare minimum it's gonna give you is the value of strerror(errno), but fr fr, usually it does so much better and tells you the actual underlying cause in more detail. main character energy. 👑

the errno global variable is what's used to grab the error value that needs decoding.

• pid — the original pid, exactly as passed to the setpgid(2) system call. like, character for character, no edits, bestie.
• pgid — the original pgid, exactly as passed to the setpgid(2) system call. same deal.

Returns: the message explaining the error. ⚠️ this message buffer is shared by all the libexplain functions that don't supply a buffer in their argument list. it's gonna get overwritten by the next call to any libexplain function that shares that buffer — including other threads. yikes.

Note: this function is not thread safe, because it shares a return buffer across all threads, and honestly, so do a bunch of other functions in this library. it's giving "we all share one bathroom". 😭

Example: this function is meant to be used in a fashion similar to the following example:

if (setpgid(pid, pgid) < 0)
{
    fprintf(stderr, "%s\n", explain_setpgid(pid, pgid));
    exit(EXIT_FAILURE);
}

and guess what 🎀 — that code example above is available pre-packaged as the explain_setpgid_or_die(3) function. iconic.

🌈 explain_errno_setpgid

const char *explain_errno_setpgid(int errnum, pid_t pid, pid_t pgid);

explain_errno_setpgid gets you an explanation of an error returned by the setpgid(2) system call. least it'll contain is the value of strerror(errno), but usually it does way better and points at the underlying cause in more detail. 💫

• errnum — the error value to be decoded, usually grabbed from the errno global variable right before this function is called. you need this if you have to run any code between the system call being explained and this function, because so many libc functions will alter the value of errno. sneaky little things. 🙈
• pid — the original pid, exactly as passed to the setpgid(2) system call.
• pgid — the original pgid, exactly as passed to the setpgid(2) system call.

Returns: the message explaining the error. ⚠️ same shared-buffer situation as before — shared by all libexplain functions that don't supply a buffer in their argument list, and it will be overwritten by the next call to any libexplain function sharing it, other threads included.

Note: not thread safe, because it shares a return buffer across all threads, and many other functions in this library do the same. it's a whole thing. 💀

Example: this function is meant to be used in a fashion similar to the following example:

if (setpgid(pid, pgid) < 0)
{
    int err = errno;
    fprintf(stderr, "%s\n", explain_errno_setpgid(err, pid,
    pgid));
    exit(EXIT_FAILURE);
}

and yes 💖 — that example is available pre-packaged as the explain_setpgid_or_die(3) function.

🎀 explain_message_setpgid

void explain_message_setpgid(char *message, int message_size, pid_t pid,
pid_t pgid);

explain_message_setpgid gets you an explanation of an error returned by the setpgid(2) system call. least the message will contain is the value of strerror(errno), but usually it does much better and shows the underlying cause in more detail. 🌸

the errno global variable is used to get the error value that's being decoded.

• message — the location where the returned message gets stored. if you supply a suitable message return buffer, this function is thread safe. slay. ✨
• message_size — the size in bytes of the location where the returned message gets stored.
• pid — the original pid, exactly as passed to the setpgid(2) system call.
• pgid — the original pgid, exactly as passed to the setpgid(2) system call.

Example: this function is meant to be used in a fashion similar to the following example:

if (setpgid(pid, pgid) < 0)
{
    char message[3000];
    explain_message_setpgid(message, sizeof(message), pid, pgid);
    fprintf(stderr, "%s\n", message);
    exit(EXIT_FAILURE);
}

pre-packaged as explain_setpgid_or_die(3), obviously. 🫶

🧚 explain_message_errno_setpgid

void explain_message_errno_setpgid(char *message, int message_size, int
errnum, pid_t pid, pid_t pgid);

explain_message_errno_setpgid gets you an explanation of an error returned by the setpgid(2) system call. least the message will contain is the value of strerror(errno), but usually it does much better and shows the underlying cause in more detail. 🔥

• message — the location where the returned message gets stored. if you supply a suitable message return buffer, 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 to be explained and this function, because many libc functions will alter the value of errno. 😭
• pid — the original pid, exactly as passed to the setpgid(2) system call.
• pgid — the original pgid, exactly as passed to the setpgid(2) system call.

Example: this function is meant to be used in a fashion similar to the following example:

if (setpgid(pid, pgid) < 0)
{
    int err = errno;
    char message[3000];
    explain_message_errno_setpgid(message, sizeof(message), err,
    pid, pgid);
    fprintf(stderr, "%s\n", message);
    exit(EXIT_FAILURE);
}

and the above code example is available pre-packaged as the explain_setpgid_or_die(3) function. periodt. 👑

---

👀 SEE ALSO 👀

• setpgid(2) — set process group
• explain_setpgid_or_die(3) — set process group and report errors

---

📜 COPYRIGHT 📜

libexplain version 1.4 Copyright (C) 2011 Peter Miller

---

and that's the whole page bestie 🫶 libexplain version 1.4, Copyright (C) 2011 Peter Miller — go forth and let your setpgid(2) errors explain themselves, explain_setpgid(3) out. 💖✨