IOCTL-XFS-GETPARENTS(2)

✨ ioctl_xfs_getparents — the whole manual, bestie edition ✨

okay so you wanna know about ioctl_xfs_getparents? it's a Linux system call manual page, section 2 (system calls), and it's all about asking XFS where a file's parents live. sit down, grab a snack 🍓, we're doing this.

---

💖 NAME 💖

ioctl_xfs_getparents — query XFS directory parent information 🦋

like. it gets you the parent pointers. that's the whole gig.

---

🌸 SYNOPSIS 🌸

#include <xfs/xfs_fs.h>

int ioctl(int fd, XFS_IOC_GETPARENTS, struct xfs_getparents *arg);

int ioctl(int fd, XFS_IOC_GETPARENTS_BY_HANDLE, struct
xfs_getparents_by_handle *arg);

two flavors, bestie. one for the file you already have open, one for a file handle. pick your fighter 💅

---

🎀 DESCRIPTION 🎀

so. this command pulls the directory parent pointers of either the file you've currently got open or of a file handle. and what even is a parent pointer? it's a little arrow pointing upwards in the directory tree, from a child file toward its parent directories. the way that every entry in a parent directory has to have a matching parent pointer in the child — that's the rule. no cap. 🔥

calling programs should allocate a large memory buffer and initialize a header that looks exactly like this:

struct xfs_getparents {
     struct xfs_attrlist_cursor  gp_cursor;
     __u16                       gp_iflags;
     __u16                       gp_oflags;
     __u32                       gp_bufsize;
     __u64                       __pad;
     __u64                       gp_buffer;
};

struct xfs_getparents_by_handle {
     struct xfs_handle           gph_handle;
     struct xfs_getparents       gph_request;
};

now let's go field by field, because every single one matters 👑

• gp_cursor — this tracks how far along you are in iterating through the parent pointers. you must initialize it to zero before the first system call, and after that you must not touch it. hands off. it's not yours anymore. 🙈
• gp_iflags — controls how the query behaves and carries extra info about how it went. there are no input flags currently defined, so this field must be zero.
• gp_oflags — holds info about the query itself. the possible output flags are:
  • XFS_GETPARENTS_OFLAG_ROOT — the file you queried was the root directory. main character behavior honestly 🌈
  • XFS_GETPARENTS_OFLAG_DONE — there are no more parent pointers left to query. you're done, periodt. ✨
• __pad — must be zero. that's it. that's the note. 🫶
• gp_bufsize — set this to the size of your buffer, in bytes.
• gp_buffer — should point to an output buffer where the parent pointer records land.

and the parent pointer records come back looking like this:

struct xfs_getparents_rec {
     struct xfs_handle           gpr_parent;
     __u16                       gpr_reclen;
     char                        gpr_name[];
};

breakdown time 💜:

• gpr_parent — a file handle you can use to open the parent directory. so useful. obsessed.
• gpr_reclen — gets set to the number of bytes this parent record uses.
• gpr_name — gets set to a NULL-terminated byte sequence for the filename stored in the parent pointer. and if the name is a zero-length string? the file you queried has no parents. sad but true 😭

---

🧚 SAMPLE PROGRAM 🧚

calling programs should allocate a big memory buffer, initialize the head structure to zeroes, set gp_bufsize to the size of the buffer, and then call the ioctl. the XFS_GETPARENTS_OFLAG_DONE flag gets set in gp_flags once there are no more parent pointers to read. here's an example of XFS_IOC_GETPARENTS in action:

#include <stdio.h>
#include <string.h>
#include <errno.h>
#include <xfs/linux.h>
#include <xfs/xfs.h>
#include <xfs/xfs_types.h>
#include <xfs/xfs_fs.h>

int main() {
     struct xfs_getparents gp = { };
     struct xfs_getparents_rec *gpr;
     int error, fd;

     gp.gp_buffer = (uintptr_t)malloc(65536);
     if (!gp.gp_buffer) {
          perror("malloc");
          return 1;
     }
     gp->gp_bufsize = 65536;

     fd = open("/mnt/test/foo.txt", O_RDONLY | O_CREAT);
     if (fd  == -1)
          return errno;

     do {
          error = ioctl(fd, XFS_IOC_GETPARENTS, gp);
          if (error)
               return error;

          for (gpr = xfs_getparents_first_rec(&gp);
               gpr != NULL;
               gpr = xfs_getparents_next_rec(&gp, gpr)) {
               if (gpr->gpr_name[0] == 0)
                    break;

               printf("inode       = %llu\n",
                         gpr->gpr_parent.ha_fid.fid_ino);
               printf("generation  = %u\n",
                         gpr->gpr_parent.ha_fid.fid_gen);
               printf("name        = \"%s\"\n\n",
                         gpr->gpr_name);
          }
     } while (!(gp.gp_flags & XFS_GETPARENTS_OFLAG_DONE));

     return 0;
}

copy it, run it, slay 💅

---

⭐ RETURN VALUE ⭐

on error, -1 is returned, and errno is set to tell you what went wrong. that's the vibe check failing. 😤

---

💀 ERRORS 💀

error codes can be one of, but are not limited to, the following:

• EFSBADCRC — metadata checksum validation failed while performing the query. the math did NOT math. 😭
• EFSCORRUPTED — metadata corruption was encountered while performing the query.
• EINVAL — one or more of the arguments you specified is invalid. check ur args bestie.
• EMSGSIZE — the record buffer wasn't large enough to store even a single record. grow the buffer, it's giving cramped. 🙈
• ENOMEM — not enough memory to retrieve parent pointers.
• EOPNOTSUPP — repairs of the requested metadata object are not supported.
• EROFS — filesystem is read-only and a repair was requested. read-only means read-only, no notes. 🔥
• ESHUTDOWN — filesystem is shut down due to previous errors.
• EIO — an I/O error was encountered while performing the query.

---

🌈 CONFORMING TO 🌈

this API is specific to the XFS filesystem on the Linux kernel. it's niche, it's exclusive, it's got main character energy. iykyk ✨

---

👑 SEE ALSO 👑

• ioctl(2)

---

and that's the whole page, babe! this one came from the XFS crew and it's dated 2024-04-09 — so if you're citing it, that's your source, your version, and your date. go forth and query those parents 💖🦋🎀