.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "AFS.ukernel 3"
.TH AFS.ukernel 3 "2022-12-22" "OpenAFS" "AFS Library Reference"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
AFS::ukernel \- Usermode cache manager for AFS
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 6
\&  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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
AFS::ukernel contains the Perl bindings for libuafs. It allows Perl
scripts to access files in \s-1AFS\s0 just like a normal \s-1AFS\s0 client would
(including cache management and all), without the need of a kernel
module.
.PP
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 \s-1API\s0 or
documentation for the rest of the subroutines, as they will behave the
same here as in libuafs.
.SH "SUBROUTINES"
.IX Header "SUBROUTINES"
Any subroutine that returns an error should set errno. This is easily
accessible in Perl for error messages via the \f(CW$!\fR variable, which
expands to the human-readable error string corresponding to the current
value of errno.
.ie n .IP "$code = AFS::ukernel::uafs_ParseArgs($args)" 4
.el .IP "\f(CW$code\fR = AFS::ukernel::uafs_ParseArgs($args)" 4
.IX Item "$code = AFS::ukernel::uafs_ParseArgs($args)"
Call this after \fBuafs_Setup()\fR but before \fBuafs_Run()\fR. \f(CW$args\fR is a single
string of whitespace-separated arguments. The arguments accepted are the
same as those accepted by the \fBafsd\fR\|(8) program, and have the same
meaning.
.Sp
The \f(CW$args\fR string is broken into individual arguments by libcmd,
according to the normal shell-like quoting and whitespace rules.
.Sp
\&\fBuafs_ParseArgs()\fR returns 0 on success, and nonzero otherwise.
.ie n .IP "$fd = AFS::ukernel::uafs_open($path, $flags[, $mode])" 4
.el .IP "\f(CW$fd\fR = AFS::ukernel::uafs_open($path, \f(CW$flags\fR[, \f(CW$mode\fR])" 4
.IX Item "$fd = AFS::ukernel::uafs_open($path, $flags[, $mode])"
Opens \f(CW$path\fR using open flags \f(CW$flags\fR. The passed \f(CW$flags\fR are
interpreted just like \fBopen\fR\|(2)'s flags; symbolic constants can be
found in the \s-1POSIX\s0 module, for example \f(CW\*(C`POSIX::O_RDONLY\*(C'\fR.
.Sp
\&\f(CW$mode\fR is the mode the specified \f(CW$path\fR 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.
.Sp
Returns a nonnegative file descriptor on success, and \-1 on error.
.ie n .IP "($code, $data) = AFS::ukernel::uafs_read($fd, $len)" 4
.el .IP "($code, \f(CW$data\fR) = AFS::ukernel::uafs_read($fd, \f(CW$len\fR)" 4
.IX Item "($code, $data) = AFS::ukernel::uafs_read($fd, $len)"
.PD 0
.ie n .IP "($code, $data) = AFS::ukernel::uafs_pread($fd, $len, $offset)" 4
.el .IP "($code, \f(CW$data\fR) = AFS::ukernel::uafs_pread($fd, \f(CW$len\fR, \f(CW$offset\fR)" 4
.IX Item "($code, $data) = AFS::ukernel::uafs_pread($fd, $len, $offset)"
.PD
Reads at most \f(CW$len\fR bytes from the file correcponding to the file
descriptor \f(CW$fd\fR. On success, returns \f(CW$data\fR as the string of data
read, and \f(CW$code\fR as the number of bytes read. On error, returns
\&\f(CW$data\fR as an empty string, and \f(CW$code\fR as \-1.
.Sp
uafs_pread reads starting from the offset \f(CW$offset\fR.
.ie n .IP "($code, @stats) = AFS::ukernel::uafs_stat($path)" 4
.el .IP "($code, \f(CW@stats\fR) = AFS::ukernel::uafs_stat($path)" 4
.IX Item "($code, @stats) = AFS::ukernel::uafs_stat($path)"
.PD 0
.ie n .IP "($code, @stats) = AFS::ukernel::uafs_lstat($path)" 4
.el .IP "($code, \f(CW@stats\fR) = AFS::ukernel::uafs_lstat($path)" 4
.IX Item "($code, @stats) = AFS::ukernel::uafs_lstat($path)"
.ie n .IP "($code, @stats) = AFS::ukernel::uafs_fstat($fd)" 4
.el .IP "($code, \f(CW@stats\fR) = AFS::ukernel::uafs_fstat($fd)" 4
.IX Item "($code, @stats) = AFS::ukernel::uafs_fstat($fd)"
.PD
\&\fBstat\fR\|(2)s, \fBlstat\fR\|(2)s, or \fBfstat\fR\|(2)s a file. On success, \f(CW$code\fR
is 0, and \f(CW@stats\fR is a 13\-element list that contains the stat
information for the file. The order and meaning of the elements in
\&\f(CW@stats\fR is the same as those returned by the builtin Perl stat
function. On error, \f(CW$code\fR is nonzero.
.ie n .IP "($code, $link) = AFS::ukernel::uafs_readlink($path, $len)" 4
.el .IP "($code, \f(CW$link\fR) = AFS::ukernel::uafs_readlink($path, \f(CW$len\fR)" 4
.IX Item "($code, $link) = AFS::ukernel::uafs_readlink($path, $len)"
Reads the contents of the link in the symlink \f(CW$path\fR. On success,
\&\f(CW$code\fR is 0, and the link data is returned in the string \f(CW$link\fR,
which will be at most \f(CW$len\fR bytes long. On error, \f(CW$code\fR is nonzero,
and \f(CW$link\fR is the empty string.
.ie n .IP "($name, $ino, $off, $reclen) = AFS::ukernel::uafs_readdir($dir)" 4
.el .IP "($name, \f(CW$ino\fR, \f(CW$off\fR, \f(CW$reclen\fR) = AFS::ukernel::uafs_readdir($dir)" 4
.IX Item "($name, $ino, $off, $reclen) = AFS::ukernel::uafs_readdir($dir)"
Reads a directory entry from the directory represented by the directory
pointer \f(CW$dir\fR. On success, the returned \f(CW$name\fR is the name of the
file entry, \f(CW$ino\fR is the inode number, \f(CW$off\fR is the offset of the
entry, and \f(CW$reclen\fR is the length of the entry name. On error,
\&\f(CW$name\fR is the empty string, and all other returned values are 0.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Here is a small program to read the first 4096 bytes of
/afs/localcell/user/adeason/file, and print them out:
.PP
.Vb 3
\&  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: $!\en");
\&
\&  $code = AFS::ukernel::uafs_ParseArgs("\-afsdb \-cachedir /tmp/mycache");
\&  $code == 0 or die("uafs_ParseArgs: $!\en");
\&
\&  $code = AFS::ukernel::uafs_Run();
\&  $code == 0 or due("uafs_Run: $!\en");
\&
\&  $fd = AFS::ukernel::uafs_open($path, POSIX::O_RDONLY);
\&  $fd >=0 or die("uafs_open: $fname: $!\en");
\&
\&  ($code, $str) = AFS::ukernel::uafs_read($fd, 4096);
\&  $code >= 0 or die("uafs_read: $!\en");
\&
\&  $code = AFS::ukernel::uafs_close($fd);
\&  $code == 0 or die("uafs_close: $!\en");
\&
\&  print "The first 4096 bytes of $path are:\en$str\en";
\&
\&  AFS::ukernel::uafs_Shutdown();
.Ve
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2010 Sine Nomine Associates <http://www.sinenomine.net/>
.PP
This documentation is covered by the \s-1BSD\s0 License as written in the
doc/LICENSE file. This man page was written by Andrew Deason for
OpenAFS.