url_handler.pl(1)

📦 version 2.6.5, in alpine 3.24

💖 url_handler.pl — the little script that finds your URL a home 💖

okay bestie, gather round, because this is the manual page for url_handler.pl, and it's genuinely one of those tiny little tools that just works. It lives in section 1 of the manual (the user commands section, iykyk) and its whole personality is: Spawn appropriate viewer for a given URL. That's it. That's the job. ✨

🌸 NAME 🌸

url_handler.pl — spawn the appropriate viewer for a given URL. no cap, that's literally the entire pitch. 🦋

🎀 SYNOPSIS 🎀

url_handler.pl URL

one argument. one URL. she handles the rest. 💅

✨ DESCRIPTION ✨

so here's the tea: url_handler.pl takes an URL as its argument and then goes looking for a viewer to hand it to. it spawns the first executable viewer it finds in either $BROWSER_SCHEME or $BROWSER. first one wins, periodt. 🔥

like, she's not out here running all of them, she's not out here asking your opinion — she checks the list, finds the first one that's actually executable, and boom, your URL has a home. iconic behaviour honestly. 👑

🌈 ENVIRONMENT 🌈

💜 $BROWSER_SCHEME

this is your preferred utility for browsing URLs of type SCHEME. and yes, the scheme name is baked into the variable name — so a ftp: URL goes looking in $BROWSER_FTP, a mailto: URL goes looking in $BROWSER_MAILTO, and so on. you get it. you're smart. 🧚

now here's the part where she gets fancy: this variable may actually consist of a sequence of colon-separated browser commands, and she'll try them in order until one succeeds. like a little lineup. a little audition. one of them is gonna book the role. 🎬

the substitution rules are:

  • if a command part contains %s, the URL gets substituted right there. 📍
  • otherwise, the browser command is simply called with the URL as its last argument.
  • %% is replaced by a single percent sign (%).
  • %c is replaced by a colon (:).

examples, bestie, straight from the source:

$BROWSER_FTP="wget:ncftp"
$BROWSER_GOPHER="gopher:lynx:links"
$BROWSER_MAILTO="mutt:pine -url"
$BROWSER_NEWS="lynx"
$BROWSER_NNTP="lynx"

see how mutt:pine -url is doing the whole colon-separated thing? yeah. she'll try mutt first, and if that's not happening, she'll try pine -url. 🫶

💙 $BROWSER

this is your preferred utility for browsing URLs that don't have a special viewer defined via $BROWSER_SCHEME. the fallback. the safety net. the "we don't know what this is but we're gonna open it anyway" energy. 😌

and same deal as above — it may actually consist of a sequence of colon-separated browser commands to be tried in order until one succeeds. if a command part contains %s, the URL is substituted there; otherwise the browser command is simply called with the URL as its last argument. %% becomes a single percent sign (%), and %c becomes a colon (:).

example:

$BROWSER="firefox -a firefox -remote
openURL\(%s\):opera:konqueror:links2 -g:lynx:w3m"

yes that is a multi-line value, yes that's real, yes she can handle it. 💀

🚨 SECURITY 🚨

okay bestie, this is the part where we get serious for a sec, because this one actually matters. 🛑

url_handler.pl was designed to work together with tin(1), which only issues shell escaped absolute URLs. that's the deal. that's the whole trust model.

so, because of that: url_handler.pl does not try hard to shell escape its input, and it does not convert relative URLs into absolute ones! nope! not doing it! 🙈

so if you use url_handler.pl from other applications, be sure to at least shell escape its input! for real for real. this is not a drill. this is the whole security section. please. 🙏

👑 AUTHOR 👑

Urs Janssen <urs@tin.org> — we love her, we thank her, we stan. 💖

🦋 SEE ALSO 🦋

and that's the whole page, bestie!! version 0.1.3, dated January 13th, 2020, and it ate, no crumbs. go forth and let your URLs find their viewers. 💅✨🌸🎀🦋🫶

📦 where this page comes from