explain_ioctl(3)

✨ explain_ioctl ✨

okay bestie, welcome to explain_ioctl from the libexplain manual, section 3 (library functions, we're fancy like that 💅). short version: this lil family of functions takes your busted ioctl(2) call and turns the error into a whole explanation, not just a sad little number. it's giving "translator for your syscall trauma". let's get into it 🫶

---

🌸 NAME 🌸

explain_ioctl — explain ioctl(2) errors. that's the whole vibe. you called ioctl, it said no, and now you want to know why. this is the why. 💖

---

✨ SYNOPSIS ✨

#include <libexplain/ioctl.h>
const char *explain_ioctl(int fildes, int request, void *data);
const char *explain_errno_ioctl(int errnum, int fildes, int request,
void *data);
void explain_message_ioctl(char *message, int message_size, int fildes,
int request, void *data);
void explain_message_errno_ioctl(char *message, int message_size, int
errnum, int fildes, int request, void *data);

four functions, four flavors of "let me explain". pick your fighter 👑

---

💜 DESCRIPTION 💜

so basically, these functions are how you get explanations for errors handed back to you by the ioctl(2) system call. no cap. that's the entire job description.

---

🦋 explain_ioctl

const char *explain_ioctl(int fildes, int request, void *data);

the explain_ioctl function is your go-to for getting an explanation of an error returned by the ioctl(2) system call. the least the message is ever gonna contain is the value of strerror(errno) — but usually it does so much better than that and tells you the actual underlying cause in way more detail. it's the difference between "something broke" and "bestie here's exactly what broke and why" 😌

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

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

int result = ioctl(fildes, request, data);
if (result < 0)
{
    fprintf(stderr, "%s\n", explain_ioctl(fildes, request, data));
    exit(EXIT_FAILURE);
}

that code example above? it's available pre‐packaged as the explain_ioctl_or_die(3) function. yes, the name is iconic, no, i did not choose it.

• fildes — the original fildes, exactly as passed to the ioctl(2) system call. don't get cute with it, pass it as-is.
• request — the original request, exactly as passed to the ioctl(2) system call. same energy.
• data — the original data, exactly as passed to the ioctl(2) system call. keep it verbatim, bestie.

Returns: the message explaining the error. this message buffer is shared by all libexplain functions that don't supply a buffer in their argument list. it will be overwritten by the next call to any libexplain function that shares this buffer, including calls from other threads. so like… don't hold onto it, it's not yours, it's everybody's 🙈

Note: this function is not thread safe, because it shares a return buffer across all threads, and so do many other functions in this library. if you're threading, you've been warned 💀

---

🌈 explain_errno_ioctl

const char *explain_errno_ioctl(int errnum, int fildes, int request,
void *data);

the explain_errno_ioctl function gets you an explanation of an error returned by the ioctl(2) system call. the least the message will contain is the value of strerror(errnum), but usually it goes way harder and points at the underlying cause in much more detail. slay.

this function is intended to be used in a fashion similar to this example:

if (ioctl(fildes, request, data) < 0)
{
    int err = errno;
    fprintf(stderr, "%s\n",
        explain_errno_ioctl(err, fildes, request, data));
    exit(EXIT_FAILURE);
}

and yep, this code example is available pre‐packaged as the explain_ioctl_or_die(3) function too. ✨

• errnum — the error value to be decoded, usually grabbed from the errno global variable right before this function is called. this is necessary if you need to call any code between the system call you're explaining and this function, because a lot of libc functions will alter the value of errno. so save it first, fr fr.
• fildes — the original fildes, exactly as passed to the ioctl(2) system call.
• request — the original request, exactly as passed to the ioctl(2) system call.
• data — the original data, exactly as passed to the ioctl(2) system call.

Returns: the message explaining the error. this message buffer is shared by all libexplain functions that don't supply a buffer in their argument list, and it'll get overwritten by the next call to any libexplain function sharing this buffer — other threads included. the way it does not belong to you 😭

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.

---

🎀 explain_message_ioctl

void explain_message_ioctl(char *message, int message_size, int fildes,
int request, void *data);

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

the errno global variable is used to obtain the error value that needs decoding.

this function is intended to be used in a fashion similar to this example:

if (ioctl(fildes, request, data) < 0)
{
    char message[3000];
    explain_message_ioctl(message, sizeof(message), fildes, request, data);
    fprintf(stderr, "%s\n", message);
    exit(EXIT_FAILURE);
}

and yes, this code example is available pre‐packaged as the explain_ioctl_or_die(3) function. 💅

• message — the location in which to store the returned message. if a suitable message return buffer is supplied, this function is thread safe. look at that, growth.
• message_size — the size in bytes of the location in which to store the returned message.
• fildes — the original fildes, exactly as passed to the ioctl(2) system call.
• request — the original request, exactly as passed to the ioctl(2) system call.
• data — the original data, exactly as passed to the ioctl(2) system call.

---

⭐ explain_message_errno_ioctl

void explain_message_errno_ioctl(char *message, int message_size, int
errnum, int fildes, int request, void *data);

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

this function is intended to be used in a fashion similar to this example:

if (ioctl(fildes, request, data) < 0)
{
    int err = errno;
    char message[3000];
    explain_message_errno_ioctl(message, sizeof(message), err,
        fildes, request, data);
    fprintf(stderr, "%s\n", message);
    exit(EXIT_FAILURE);
}

and guess what — this code example is available pre‐packaged as the explain_ioctl_or_die(3) function. ✨

• message — the location in which to store the returned message. if a suitable message return buffer is supplied, this function is thread safe.
• message_size — the size in bytes of the location in which to store the returned message.
• 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. so like, grab it early, babe.
• fildes — the original fildes, exactly as passed to the ioctl(2) system call.
• request — the original request, exactly as passed to the ioctl(2) system call.
• data — the original data, exactly as passed to the ioctl(2) system call.

---

🌈 SEE ALSO 🌈

• ioctl(2) — control device
• explain_ioctl_or_die(3) — control device and report errors

iykyk. these two are the besties you go read next. 🫶

---

👑 COPYRIGHT 👑

libexplain version 1.4 Copyright (C) 2008 Peter Miller

---

and that's the whole page, bestie 🎀 libexplain version 1.4, Copyright (C) 2008 Peter Miller, and this little manual page goes by explain_ioctl(3) — main character energy, no notes, periodt 💖✨