mirror of
https://git.openafs.org/openafs.git
synced 2025-01-19 07:20:11 +00:00
6548cedbee
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 <shadow@dementia.org> Reviewed-by: Derrick Brashear <shadow@dementia.org>
145 lines
4.8 KiB
Plaintext
145 lines
4.8 KiB
Plaintext
|
|
=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<afsd(8)> 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<open(2)>'s flags; symbolic constants can be
|
|
found in the L<POSIX> module, for example C<POSIX::O_RDONLY>.
|
|
|
|
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<uafs_pread> 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)
|
|
|
|
L<stat(2)>s, L<lstat(2)>s, or L<fstat(2)>s 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 <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.
|