autoconf: Remove/update obsolete autoconf macros
[openafs.git] / 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.