CHASE(1)

💖 CHASE(1) — the chase page, but make it a group chat 💖

okay bestie, welcome to the Chase user's manual ✨ yes that's the actual manual name, we're being official about it. sit down, grab a boba, we're learning a whole utility in like four minutes. 🧚

---

🌸 NAME 🌸

chase — chase symbolic links. that's it. that's the whole job description. she chases links 💅

---

✨ SYNOPSIS ✨

chase [ --verbose | --from-file | -f | --null | -0 |
--loop-warn-threshold COUNT | -w COUNT | --loop-fail-threshold COUNT |
-l COUNT | --disable-loop-detection | -D ] [file...]

chase -v | --version

chase -h | --help

---

🦋 DESCRIPTION 🦋

so Chase is a tiny little utility that tracks down the name of the actual file that is truly accessed when you hit a symbolic link. it chases the link. hence the name. she said what she said. 😌

in normal operation, you hand chase the name of an existing file, and the program shows you — or, to be precise, prints to the standard output stream — the name of the real file that your original file was referring to. and honestly? if you hand her a regular file, she's not gonna be dramatic about it. she'll just hand you the same name right back. no notes. 🫶

you can also pass --verbose to have her be more chatty about what she's doing, and you can hand her a list of files to read the names from instead (that's the --from-file option, more on that below).

now let me give you the iconic example of when chase is genuinely useful. on a Debian GNU/Linux system, software installation is handled by dpkg(8). there's a way to query dpkg(8) about which package a file belongs to. unfortunately, that does not grok all symlinks. and that's a problem, because the Debian system uses symbolic links extensively to handle several flavours of a program (say, XEmacs and GNU Emacs, and versions 19 and 20 of both). but now, with chase, you can determine the real file easily and then use that result as an argument to dpkg(8). observe, bestie:

ajk@ugh:~$ dpkg -S `which xemacs20`
dpkg: /usr/bin/xemacs20 not found.
ajk@ugh:~$ dpkg -S `which xemacs20 | xargs chase`
xemacs20-nomule: /usr/bin/xemacs-20.4-nomule
ajk@ugh:~$

ate. 💅✨

and when you give her multiple file names as arguments, chase will chase every single one of them, in order. she's thorough like that.

---

💅 OPTIONS 💅

these are the options chase recognizes, and yes we're doing all of them:

• --verbose — chat about what is being done. she's telling you everything. main character energy, honestly. 🗣️
• -f, --from-file — treat the file names on the command line as sources for names to be chased. if this option is present, chase reads in each of the files given on the command line — and both a sole dash - and the absence of file names mean the standard input stream. each line in those files is taken as a verbatim file name, chased exactly like it had been given on the command line of a run without this option. heads up though: there is no means for quoting the newline character, so only file names that do not contain newlines can be specified via the files. that restriction gets lifted by -0, though. also, literal spaces are preserved and are not interpreted as special. 🎀
• -0, --null — this one implies -f, which reads file names from a file. what -0 changes is that instead of treating lines in the file as file names, the file names are expected to be separated by null characters. which is exactly what lets you specify file names with newlines in them via -f. slay. ✨
• -w WCOUNT, --loop-warn-threshold=WCOUNT
• -l LCOUNT, --loop-fail-threshold=LCOUNT — set the threshold for warning about a possible symlink loop (WCOUNT) and for failing because of one (LCOUNT). there are default values, and you can find them out by invoking chase with the argument --help. using zero as WCOUNT or LCOUNT disables the check. 🙈
• -D, --disable-loop-detection — normally chase keeps a record of all the symlinks she's visited while chasing the current file, and uses that record to reliably detect symlink loops. but — checking the record slows the process down a little (more so for long chains of symlinks), and the record requires a small amount of memory (again, more for long chains of symlinks). so sometimes it's desirable to inhibit this check. this option disables the loop detection and the associated recording of visited symlinks. when this option is in effect (assuming no bugs in the related code 👀) chase runs in constant space and linear time relative to the length of the symlink chains encountered. iconic behaviour, no cap.
• -h, --help — output a usage summary and exit successfully. she's helpful AND polite. 🫶
• -v, --version — show version information and exit successfully. 💜

---

😭 DIAGNOSTICS 😭

the exit status is 0 if and only if all files given in the command lines exist and none of them are dangling symlinks. periodt.

the following messages get emitted by chase when she suspects or detects a symlink loop:

• quite many symlink hops, hope we're not looping... — this means the chain of symlinks is longer than a given threshold. it may mean the chain is infinite (and thus contains a loop somewhere). the threshold can be specified with the --loop-warn-threshold command line option. she's side-eyeing the chain. 👀
• too many symlink hops, giving up... — this means the chain of symlinks is longer than a given threshold. this usually means the chain is infinite (and thus contains a loop somewhere). the threshold can be specified with the --loop-fail-threshold command line option. if you see this message, it means chase has given up on that file. 💀
• symlink loop detected, giving up... — the symlink chain is looping, so there is no result for the chase. chase has given up on that file. she tried, bestie. 😭

additionally, chase emits several error messages under problematic conditions. they all come from the system libraries, so the program has no control over the actual wording of the messages. they all follow the format "program name: file name: error message", where file name is the name of the offending file or directory.

---

🍓 BUGS 🍓

chase may have bugs. if you find them, please report them to <rotty@debian.org> or, preferably, via the Debian bugtracking system. don't be shy, she wants to know. 🫶

---

👑 AUTHOR 👑

chase has been written by Antti-Juhani Kaijanaho <gaia@iki.fi> and is currently maintained by Andreas Rottmann <rotty@debian.org>. legends, both of them. 🌈

---

🌈 SEE ALSO 🌈

find(1), ln(1), namei(1), readlink(1), readlink(2), symlinks(1)

iykyk. go read those next, bestie. 📚✨

---

and that's the whole page!! Chase 0.5, dated 2000-01-02 — so yeah, she's been out here chasing links since the turn of the millennium and she's still serving. ⭐💜

fr fr, if you only remember one thing: symlink goes in, real file comes out. that's the vibe check, and she passes it every time. 🎀🦋