Commit | Line | Data |
---|---|---|
805e021f CE |
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. |