doc/man-pages/pod3/AFS.ukernel.pod

   1
   2 =head1 NAME
   3
   4 AFS::ukernel - Usermode cache manager for AFS
   5
   6 =head1 SYNOPSIS
   7
   8   use AFS::ukernel;
   9   use POSIX;
  10   AFS::ukernel::uafs_Setup("/afs");
  11   AFS::ukernel::uafs_ParseArgs($args);
  12   AFS::ukernel::uafs_Run();
  13   $fd = AFS::ukernel::uafs_open($path, POSIX::O_RDONLY);
  14
  15 =head1 DESCRIPTION
  16
  17 AFS::ukernel contains the Perl bindings for libuafs. It allows Perl
  18 scripts to access files in AFS just like a normal AFS client would
  19 (including cache management and all), without the need of a kernel
  20 module.
  21
  22 This documentation does not cover all subroutines in AFS::ukernel. It
  23 just serves to provide documentation on semantics or functionality that
  24 is specific to the AFS::ukernel, or differs from the semantics or
  25 functionality of libuafs proper in some way. See the libuafs API or
  26 documentation for the rest of the subroutines, as they will behave the
  27 same here as in libuafs.
  28
  29 =head1 SUBROUTINES
  30
  31 Any subroutine that returns an error should set errno. This is easily
  32 accessible in Perl for error messages via the C<$!> variable, which
  33 expands to the human-readable error string corresponding to the current
  34 value of errno.
  35
  36 =over
  37
  38 =item $code = AFS::ukernel::uafs_ParseArgs($args)
  39
  40 Call this after uafs_Setup() but before uafs_Run(). C<$args> is a single
  41 string of whitespace-separated arguments. The arguments accepted are the
  42 same as those accepted by the L<afsd(8)> program, and have the same
  43 meaning.
  44
  45 The C<$args> string is broken into individual arguments by libcmd,
  46 according to the normal shell-like quoting and whitespace rules.
  47
  48 uafs_ParseArgs() returns 0 on success, and nonzero otherwise.
  49
  50 =item $fd = AFS::ukernel::uafs_open($path, $flags[, $mode])
  51
  52 Opens C<$path> using open flags C<$flags>. The passed C<$flags> are
  53 interpreted just like L<open(2)>'s flags; symbolic constants can be
  54 found in the L<POSIX> module, for example C<POSIX::O_RDONLY>.
  55
  56 C<$mode> is the mode the specified C<$path> will be created with if you
  57 are creating a new file. If it is unspecified, it defaults to 0. If it
  58 is specified and the call does not create a new file, it is ignored.
  59
  60 Returns a nonnegative file descriptor on success, and -1 on error.
  61
  62 =item ($code, $data) = AFS::ukernel::uafs_read($fd, $len)
  63
  64 =item ($code, $data) = AFS::ukernel::uafs_pread($fd, $len, $offset)
  65
  66 Reads at most C<$len> bytes from the file correcponding to the file
  67 descriptor C<$fd>. On success, returns C<$data> as the string of data
  68 read, and C<$code> as the number of bytes read. On error, returns
  69 C<$data> as an empty string, and C<$code> as -1.
  70
  71 L<uafs_pread> reads starting from the offset C<$offset>.
  72
  73 =item ($code, @stats) = AFS::ukernel::uafs_stat($path)
  74
  75 =item ($code, @stats) = AFS::ukernel::uafs_lstat($path)
  76
  77 =item ($code, @stats) = AFS::ukernel::uafs_fstat($fd)
  78
  79 L<stat(2)>s, L<lstat(2)>s, or L<fstat(2)>s a file. On success, C<$code>
  80 is 0, and C<@stats> is a 13-element list that contains the stat
  81 information for the file. The order and meaning of the elements in
  82 C<@stats> is the same as those returned by the builtin Perl stat
  83 function. On error, C<$code> is nonzero.
  84
  85 =item ($code, $link) = AFS::ukernel::uafs_readlink($path, $len)
  86
  87 Reads the contents of the link in the symlink C<$path>. On success,
  88 C<$code> is 0, and the link data is returned in the string C<$link>,
  89 which will be at most C<$len> bytes long. On error, C<$code> is nonzero,
  90 and C<$link> is the empty string.
  91
  92 =item ($name, $ino, $off, $reclen) = AFS::ukernel::uafs_readdir($dir)
  93
  94 Reads a directory entry from the directory represented by the directory
  95 pointer C<$dir>. On success, the returned C<$name> is the name of the
  96 file entry, C<$ino> is the inode number, C<$off> is the offset of the
  97 entry, and C<$reclen> is the length of the entry name. On error,
  98 C<$name> is the empty string, and all other returned values are 0.
  99
 100 =back
 101
 102 =head1 EXAMPLES
 103
 104 Here is a small program to read the first 4096 bytes of
 105 /afs/localcell/user/adeason/file, and print them out:
 106
 107   use strict;
 108   use AFS::ukernel;
 109   use POSIX;
 110
 111   my $path = "/afs/localcell/user/adeason/afile";
 112   my $str;
 113   my $code;
 114   my $fd;
 115
 116   $code = AFS::ukernel::uafs_Setup("/afs");
 117   $code == 0 or die("uafs_Setup: $!\n");
 118
 119   $code = AFS::ukernel::uafs_ParseArgs("-afsdb -cachedir /tmp/mycache");
 120   $code == 0 or die("uafs_ParseArgs: $!\n");
 121
 122   $code = AFS::ukernel::uafs_Run();
 123   $code == 0 or due("uafs_Run: $!\n");
 124
 125   $fd = AFS::ukernel::uafs_open($path, POSIX::O_RDONLY);
 126   $fd >=0 or die("uafs_open: $fname: $!\n");
 127
 128   ($code, $str) = AFS::ukernel::uafs_read($fd, 4096);
 129   $code >= 0 or die("uafs_read: $!\n");
 130
 131   $code = AFS::ukernel::uafs_close($fd);
 132   $code == 0 or die("uafs_close: $!\n");
 133
 134   print "The first 4096 bytes of $path are:\n$str\n";
 135
 136   AFS::ukernel::uafs_Shutdown();
 137
 138 =head1 COPYRIGHT
 139
 140 Copyright 2010 Sine Nomine Associates <http://www.sinenomine.net/>
 141
 142 This documentation is covered by the BSD License as written in the
 143 doc/LICENSE file. This man page was written by Andrew Deason for
 144 OpenAFS.