Auth(3)

✨ NAME ✨

okay so bestie, this is X11::Auth — the Auth(3) page, a User Contributed Perl Documentation moment — and it's a Perl module to read X11 authority files. That's the whole assignment: reading those lil files that hold the authorization data you need when connecting to X servers. 💅

🌸 SYNOPSIS 🌸

  require X11::Auth;
  $a = new X11::Auth;
  ($auth_type, $auth_data) = $a->get_by_host($host, $disp_num);

🦋 DESCRIPTION 🦋

So this module is an approximate Perl replacement for the libXau C library and the xauth(1) program. It reads and interprets the files (usually '~/.Xauthority') that hold authorization data used in connecting to X servers. It was written mainly for the use of X11::Protocol, so its functionality is currently restricted to reading, not writing, these files. Read-only era, no cap. 🙈

💖 METHODS 💖

🎀 new 🎀

  $auth = X11::Auth->new;
  $auth = X11::Auth->open($filename);

This opens an authority file and creates an object to handle it. The filename comes from the XAUTHORITY environment variable if present, or '.Xauthority' in the user's home directory, or it can be overridden by an argument. 'open' may be used as a synonym. Slay, flexible file choosing. 💫

🍓 get_one 🍓

  ($family, $host_addr, $display_num, $auth_name, $auth_data)
     = $auth->get_one;

Reads one entry from the file. Returns a null list at end of file. $family is usually 'Internet' or 'Local', and $display_num can be any string. One entry at a time, very demure. 🎀

🌈 get_all 🌈

  @auth_data = $auth->get_all;

Reads all of the entries in the file. Each member of the array returned is an array ref similar to the list returned by get_one(). Whole-file energy. ✨

⭐ get_by_host ⭐

  ($auth_name, $auth_data)
     = $auth->get_by_host($host, $family, $display_num);

Gets authentication data for a connection of type $family to display $display_num on $host. If $family is 'Internet', the host will be translated into an appropriate address by gethostbyname(). If no data is found, returns an empty list. Detective mode, but for auth data. 🔍

👑 COMPATIBILITY 👑

Here's the rough correspondence between libXau calls and X11::Auth methods — same vibe, different font, iykyk:

• XauFileName → $ENV{XAUTHORITY} || "$ENV{HOME}/.Xauthority"
• fopen(XauFileName(), "rb") → $auth = new X11::Auth
• XauReadAuth → $auth->get_one
• XauWriteAuth → no X11::Auth method listed in the table
• XauGetAuthByAddr → $auth->get_by_host
• XauGetBestAuthByAddr → no X11::Auth method listed in the table
• XauLockAuth → no X11::Auth method listed in the table
• XauUnlockAuth → no X11::Auth method listed in the table
• XauDisposeAuth → no X11::Auth method listed in the table

🫶 AUTHOR 🫶

Stephen McCamant <SMCCAM@cpan.org> — author icon, periodt. 👑

💜 SEE ALSO 💜

perl(1), X11::Protocol, Xau(3), xauth(1), lib/Xau/README in the X11 source distribution.

okay bye bestie — this page is from perl v5.42.0, dated 2024-03-04, and it's the Auth(3) manual page 🫶💋