From 6548cedbee4ea3e0f1769075717a3c05a5a0127f Mon Sep 17 00:00:00 2001 From: Andrew Deason Date: Tue, 22 Sep 2009 15:45:09 -0500 Subject: [PATCH] Add documentation for AFS::ukernel Add some documentation explaining some of the minor quirks in AFS::ukernel; specifically how some functions look a bit different than in plain libuafs. Change-Id: Ib8b18720c3fa6087de98d58ba8381f1ae4fb2f10 Reviewed-on: http://gerrit.openafs.org/3902 Tested-by: Derrick Brashear Reviewed-by: Derrick Brashear --- doc/man-pages/pod3/AFS.ukernel.pod | 144 +++++++++++++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 doc/man-pages/pod3/AFS.ukernel.pod diff --git a/doc/man-pages/pod3/AFS.ukernel.pod b/doc/man-pages/pod3/AFS.ukernel.pod new file mode 100644 index 000000000..dd869b650 --- /dev/null +++ b/doc/man-pages/pod3/AFS.ukernel.pod @@ -0,0 +1,144 @@ + +=head1 NAME + +AFS::ukernel - Usermode cache manager for AFS + +=head1 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); + +=head1 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. + +=head1 SUBROUTINES + +Any subroutine that returns an error should set errno. This is easily +accessible in Perl for error messages via the C<$!> variable, which +expands to the human-readable error string corresponding to the current +value of errno. + +=over + +=item $code = AFS::ukernel::uafs_ParseArgs($args) + +Call this after uafs_Setup() but before uafs_Run(). C<$args> is a single +string of whitespace-separated arguments. The arguments accepted are the +same as those accepted by the L program, and have the same +meaning. + +The C<$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. + +=item $fd = AFS::ukernel::uafs_open($path, $flags[, $mode]) + +Opens C<$path> using open flags C<$flags>. The passed C<$flags> are +interpreted just like L's flags; symbolic constants can be +found in the L module, for example C. + +C<$mode> is the mode the specified C<$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. + +=item ($code, $data) = AFS::ukernel::uafs_read($fd, $len) + +=item ($code, $data) = AFS::ukernel::uafs_pread($fd, $len, $offset) + +Reads at most C<$len> bytes from the file correcponding to the file +descriptor C<$fd>. On success, returns C<$data> as the string of data +read, and C<$code> as the number of bytes read. On error, returns +C<$data> as an empty string, and C<$code> as -1. + +L reads starting from the offset C<$offset>. + +=item ($code, @stats) = AFS::ukernel::uafs_stat($path) + +=item ($code, @stats) = AFS::ukernel::uafs_lstat($path) + +=item ($code, @stats) = AFS::ukernel::uafs_fstat($fd) + +Ls, Ls, or Ls a file. On success, C<$code> +is 0, and C<@stats> is a 13-element list that contains the stat +information for the file. The order and meaning of the elements in +C<@stats> is the same as those returned by the builtin Perl stat +function. On error, C<$code> is nonzero. + +=item ($code, $link) = AFS::ukernel::uafs_readlink($path, $len) + +Reads the contents of the link in the symlink C<$path>. On success, +C<$code> is 0, and the link data is returned in the string C<$link>, +which will be at most C<$len> bytes long. On error, C<$code> is nonzero, +and C<$link> is the empty string. + +=item ($name, $ino, $off, $reclen) = AFS::ukernel::uafs_readdir($dir) + +Reads a directory entry from the directory represented by the directory +pointer C<$dir>. On success, the returned C<$name> is the name of the +file entry, C<$ino> is the inode number, C<$off> is the offset of the +entry, and C<$reclen> is the length of the entry name. On error, +C<$name> is the empty string, and all other returned values are 0. + +=back + +=head1 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(); + +=head1 COPYRIGHT + +Copyright 2010 Sine Nomine Associates + +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. -- 2.39.5