XtFindFile(3)

💖 XtFindFile(3) 💖

okay bestie, welcome to the XT FUNCTIONS corner of the manual, this one's called XtFindFile and it is literally the girl who goes hunting through your path list looking for a file, doing cute little substitutions along the way 🦋

---

✨ NAME ✨

XtFindFile — search for a file using substitutions in the path list 💅

---

✨ SYNTAX ✨

#include <X11/Intrinsic.h>

char * XtFindFile(const char *path, Substitution substitutions, Cardinal
       num_substitutions, XtFilePredicate predicate);

---

✨ ARGUMENTS ✨

• path — the path of file names, and yes it's got substitution characters in it, she's fancy like that 🎀
• substitutions — a list of substitutions to make into a path, the little glow-up kit ✨
• num_substitutions — how many substitutions got passed in, we're counting fr fr 🔢
• predicate — a procedure to call to judge a potential file name, or NULL if you're not about that judgey life 🙈

---

✨ DESCRIPTION ✨

so the path parameter is a string made of a whole series of potential file names, all delimited by colons. classic. within each name, the percent character % is like "bestie, a substitution is coming" and the character right after it decides which one 👑

the character sequence %: means an embedded colon that is not a delimiter — it gets replaced by a single colon, sneaky but valid 🫶

the character sequence %% means a literal percent character that does not introduce a substitution — it gets replaced by a single percent character, periodt 💅

if a percent character is followed by any other character, XtFindFile looks through the specified substitutions for that character in the match field, and if she finds it, she replaces the percent and match characters with the string in the corresponding substitution field ✨

a substitution field entry of NULL is equivalent to a pointer to an empty string, so like, no drama, it just means nothing goes there 🍓

okay and here's a very specific technical moment, stay with me: if the operating system does not interpret multiple embedded name separators in the path (i.e., / in POSIX) the same way as a single separator, then XtFindFile will collapse multiple separators into a single one after performing all string substitutions. she tidies up at the end, iconic 🧚

except for that collapsing-embedded-separators thing, the contents of the string substitutions are not interpreted by XtFindFile at all, so they may therefore contain any operating-system-dependent characters, including additional name separators. she does not read your vibes, she just uses them 🌈

each resulting string gets passed to the predicate procedure until a string is found for which the procedure returns True. that string is the return value for XtFindFile 🎉

if no string yields a True return from the predicate, XtFindFile returns NULL. it's giving "we looked everywhere and found nothing" 😭

---

🌸 the NULL predicate situation 🌸

if the predicate parameter is NULL, an internal procedure that checks if the file exists, is readable, and is not a directory will be used instead. so she's got a built-in vibe check, no cap 🔥

---

💀 memory business 💀

it is the responsibility of the caller to free the returned string using XtFree when it is no longer needed. do not forget, bestie, that's a leak and we don't do leaks 🙈

---

✨ SEE ALSO ✨

• X Toolkit Intrinsics - C Language Interface
• Xlib - C Language X Interface

---

X Version 11 ✦ libXt 1.3.1 ✦ XtFindFile(3)

and that's the whole page, you ate it, go free your strings with XtFree and slay the rest of your day 💖✨👑