| 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. |