dir_new_leaf(9)

💖 dir_new_leaf — the manual page, but make it bestie-coded 💖

okay so you found your way to dir_new_leaf(9) in the Kernel API Manual, and honestly? slay. this one's a little niche but it's iconic once you get it, i promise. let's get into it 🫶

---

✨ NAME ✨

dir_new_leaf — literally just: add a new leaf onto a hash chain. that's the whole vibe. 🍃

---

🎀 SYNOPSIS 🎀

int dir_new_leaf (struct inode *inode , const struct qstr *name );

like, exactly that. no cap. 💅

---

🌸 ARGUMENTS 🌸

• inode — the directory. the actual dir we're messing with, bestie.
• name — the name we are adding. the little string that needs a home. 🏠

---

🦋 DESCRIPTION 🦋

okay so picture this: you're trying to squeeze a new dir entry into an existing leaf, and there is literally not enough space. what do you do? you add a new dir leaf onto an existing leaf. that's the move. ✨

and before you come for me — this is a last resort. like, we've already expanded the hash table to max size and we've split existing leaf blocks, and still no room. so this only ever happens for very large directories. it's giving "we tried everything else first" energy ngl 😭

now, the dist parameter — obsessed with her honestly:

• 1 for leaf blocks directly attached to the hash table
• 2 for one layer of indirection
• 3 for two layers, etc.

so the way that works is we can tell the difference between an old leaf with dist set to zero (which means, and i quote, "don't know" 💀) and a new one where we actually set this info for debug/fsck purposes. it's giving organized. it's giving responsible. we love a self-aware leaf. 👑

---

🔥 RETURN 🔥

• 0 on success 🎉
• -ve on error 😔 (yes, negative. it's fine. it happens.)

---

🌈 SEE ALSO 🌈

go read the kernel file ./fs/gfs2/dir.c, and then honestly just go down the whole list because they're all linked up like a group chat:

gfs2_dir_write_data(9), gfs2_dir_read_data(9), gfs2_dir_get_hash_table(9), gfs2_dir_hash_inval(9), dirent_next(9), dirent_del(9), get_leaf_nr(9), dir_make_exhash(9), dir_split_leaf(9), dir_double_exhash(9), compare_dents(9), do_filldir_main(9), gfs2_dir_readahead(9), dir_e_read(9), gfs2_dir_search(9), gfs2_dir_add(9), gfs2_dir_del(9), gfs2_dir_mvino(9), leaf_dealloc(9), gfs2_dir_exhash_dealloc(9), gfs2_diradd_alloc_required(9)

💀 warning-ish: this whole thing only kicks in when the directory is genuinely enormous, so if you're seeing this in a trace you probably have a big dir on your hands. no invented facts here, just the actual last-resort behaviour from above, bestie.

---

🧚 and that's the page!! this one came out of ./fs/gfs2, dated October 2026, in the dir_new_leaf(9) era of the Kernel API Manual. mwah 💋 go forth and read dir.c 🎀💖✨