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.