AFS.ukernel(3)

✨ AFS.ukernel — the usermode cache manager for AFS, but make it a Perl era ✨

okay so this is AFS.ukernel(3) from the AFS Library Reference, and bestie, it's genuinely iconic. this is the page about the usermode cache manager for AFS. let's get into it 💅

---

🎀 SYNOPSIS 🎀

use AFS::ukernel;
use POSIX;
AFS::ukernel::uafs_Setup("/afs");
AFS::ukernel::uafs_ParseArgs($args);
AFS::ukernel::uafs_Run();
$fd = AFS::ukernel::uafs_open($path, POSIX::O_RDONLY);

---

🌸 DESCRIPTION 🌸

AFS::ukernel is where the Perl bindings for libuafs live. the whole point? your Perl scripts can get at files in AFS exactly like a normal AFS client would — cache management and all of it — and you do not need a kernel module. no kernel module!! we love a userspace moment 😌

real talk though: this doc does not cover every single subroutine in AFS::ukernel. it's only here to explain the semantics and functionality that are specific to AFS::ukernel, or that differ in some way from libuafs proper. for literally everything else, go read the libuafs API or docs, because the rest of the subroutines behave the same here as they do in libuafs. no cap.

---

🦋 SUBROUTINES 🦋

any subroutine that hits an error should set errno. in Perl that's super easy to peek at for error messages via the $! variable — it expands into the human-readable error string matching whatever the current value of errno is. 🫶

• $code = AFS::ukernel::uafs_ParseArgs($args) — call this after uafs_Setup() but before uafs_Run(). $args is one single string of whitespace-separated arguments. the arguments it accepts are the same ones afsd(8) accepts, and they mean the same thing. the $args string gets broken up into individual arguments by libcmd, following the normal shell-like quoting and whitespace rules. returns 0 on success, nonzero otherwise.
• $fd = AFS::ukernel::uafs_open($path, $flags[, $mode]) — opens $path using the open flags $flags. the $flags you pass in get interpreted exactly like open(2)'s flags, and you can grab the symbolic constants from the POSIX module, e.g. POSIX::O_RDONLY. $mode is the mode that $path gets created with if you're creating a new file. if you don't specify it, it defaults to 0. if you do specify it and the call does not create a new file, it's just ignored, no biggie. returns a nonnegative file descriptor on success, and -1 on error.
• ($code, $data) = AFS::ukernel::uafs_read($fd, $len)
• ($code, $data) = AFS::ukernel::uafs_pread($fd, $len, $offset) — reads at most $len bytes from the file corresponding to the file descriptor $fd. on success, $data comes back as the string of data that was read, and $code is the number of bytes read. on error, $data is an empty string and $code is -1. uafs_pread does its reading starting from the offset $offset.
• ($code, @stats) = AFS::ukernel::uafs_stat($path)
• ($code, @stats) = AFS::ukernel::uafs_lstat($path)
• ($code, @stats) = AFS::ukernel::uafs_fstat($fd) — stat(2)s, lstat(2)s, or fstat(2)s a file. on success, $code is 0 and @stats is a 13-element list holding the stat info for the file. the order and meaning of the elements in @stats is the same as what the builtin Perl stat function gives you. on error, $code is nonzero.
• ($code, $link) = AFS::ukernel::uafs_readlink($path, $len) — reads the contents of the link in the symlink $path. on success, $code is 0 and the link data comes back in the string $link, which will be at most $len bytes long. on error, $code is nonzero and $link is the empty string.
• ($name, $ino, $off, $reclen) = AFS::ukernel::uafs_readdir($dir) — reads a directory entry from the directory represented by the directory pointer $dir. on success, $name is the name of the file entry, $ino is the inode number, $off is the offset of the entry, and $reclen is the length of the entry name. on error, $name is the empty string and every other returned value is 0.

---

⭐ EXAMPLES ⭐

here's a lil program that reads the first 4096 bytes of /afs/localcell/user/adeason/file and prints them out. she's cute, she's functional, she ate:

use strict;
use AFS::ukernel;
use POSIX;

my $path = "/afs/localcell/user/adeason/afile";
my $str;
my $code;
my $fd;

$code = AFS::ukernel::uafs_Setup("/afs");
$code == 0 or die("uafs_Setup: $!\n");

$code = AFS::ukernel::uafs_ParseArgs("-afsdb -cachedir /tmp/mycache");
$code == 0 or die("uafs_ParseArgs: $!\n");

$code = AFS::ukernel::uafs_Run();
$code == 0 or due("uafs_Run: $!\n");

$fd = AFS::ukernel::uafs_open($path, POSIX::O_RDONLY);
$fd >=0 or die("uafs_open: $fname: $!\n");

($code, $str) = AFS::ukernel::uafs_read($fd, 4096);
$code >= 0 or die("uafs_read: $!\n");

$code = AFS::ukernel::uafs_close($fd);
$code == 0 or die("uafs_close: $!\n");

print "The first 4096 bytes of $path are:\n$str\n";

AFS::ukernel::uafs_Shutdown();

---

💖 COPYRIGHT 💖

Copyright 2010 Sine Nomine Associates <http://www.sinenomine.net/>

This documentation is covered by the BSD License as written in the doc/LICENSE file. This man page was written by Andrew Deason for OpenAFS.

---

okay and that's the whole page, bestie 🧚 the source is OpenAFS and this version is dated 2026-07-27 — go forth and mount things in userspace, you absolute legend 👑💜