NAME

AFS::ukernel - Usermode cache manager for AFS

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 contains the Perl bindings for libuafs. It allows Perl scripts to access files in AFS just like a normal AFS client would (including cache management and all), without the need of a kernel module.

This documentation does not cover all subroutines in AFS::ukernel. It just serves to provide documentation on semantics or functionality that is specific to the AFS::ukernel, or differs from the semantics or functionality of libuafs proper in some way. See the libuafs API or documentation for the rest of the subroutines, as they will behave the same here as in libuafs.

SUBROUTINES

Any subroutine that returns an error should set errno. This is easily accessible in Perl for error messages via the $! variable, which expands to the human-readable error string corresponding to the current value of errno.

$code = AFS::ukernel::uafs_ParseArgs($args)

Call this after uafs_Setup() but before uafs_Run(). $args is a single string of whitespace-separated arguments. The arguments accepted are the same as those accepted by the afsd(8) program, and have the same meaning.

The $args string is broken into individual arguments by libcmd, according to the normal shell-like quoting and whitespace rules.

uafs_ParseArgs() returns 0 on success, and nonzero otherwise.

$fd = AFS::ukernel::uafs_open($path, $flags[, $mode])

Opens $path using open flags $flags. The passed $flags are interpreted just like open(2)'s flags; symbolic constants can be found in the POSIX module, for example "POSIX::O_RDONLY".

$mode is the mode the specified $path will be created with if you are creating a new file. If it is unspecified, it defaults to 0. If it is specified and the call does not create a new file, it is ignored.

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 correcponding to the file descriptor $fd. On success, returns $data as the string of data read, and $code as the number of bytes read. On error, returns $data as an empty string, and $code as -1.

uafs_pread reads 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 that contains the stat information for the file. The order and meaning of the elements in @stats is the same as those returned by the builtin Perl stat function. 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 is returned 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, the returned $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 all other returned values are 0.

EXAMPLES

Here is a small program to read the first 4096 bytes of /afs/localcell/user/adeason/file, and print them out:

  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.