=head1 NAME

AFS - Perl interface to AFS programming APIs

=head1 SYNOPSIS

    use AFS;                    # import all exported names
    use AFS 'getacl', 'setacl'; # selective import
    use AFS @AFS::XX;     
    # where XX is ALL, PTS,CELL, MISC, ACL, CM, KA, or KTC

=head1 LAYOUT

For ease of access, the afsperl manual has been split up into a number
of sections:

    afsperl        AFS module overview (this section)
    afsperlmisc    Miscellaneous ($AFS::CODE, setpag, etc)
    afsperlcell    Cell configuration (localcell, etc)
    afsperlobj     Objects used by the AFS module
    afsperlacl     ACL related functions (setacl, getacl)
    afsperlcm      cache manager functions (fs command suite)
    afsperlka      ka routines (ka_UserAuthenticateGeneral, kas commands)
    afsperlktc     ktc functions (ktc_ListTokens, etc)
    afsperlpts     pts functions (pts command suite)
    afsperlcons    AFS constants (#defines) included in the AFS module

=head1 INTRO

The AFS module is a dynamically loadable (where available) extension to Perl 5.
It gives the AFS user and administrator access to many of the AFS programming
APIs, allowing you to make these calls directly from Perl, rather than
processing the output of a command.

The AFS module is a thin layer above the low-level AFS APIs. When possible, 
function names are similar to the actual API names, or to the AFS command 
suite names. The ordering of function parameters is not always the same 
though. In general, least used parameters are last and have reasonable 
(IMHO) defaults so they can be left off. 

The AFS module includes the following features:

=over 5

=item * Use of Perl 5 objects and references

Perl 5 objects and references are used for hiding complex data structures 
from users. There are objects for ACLs, Principals, Tokens, DES Keys, 
connections to the Protection Servers (pts), and connections to the Kerberos
Server. 

=item * Access to cache manager routines

Functions that deal with the cache manager (i.e, the fs command).

=item * Access to Protection Server routines

Functions that deal with the protection server (i.e, the pts command).

=item * Access to ktc routines

Functions which handle token management (i.e, the tokens command).

=item * Access to the Authentication Server Routines

(i.e, the "kas" command, or the ka_UserAthenticateGeneral function). 

=item * Access to error codes from AFS functions

The perl variable $AFS::CODE will be set to 0 or the return value from
the last non-successful AFS function call. You also have the ability
to raise a perl exception when any AFS function call fails (useful for
debugging).

=item * Access to constants from AFS include files

Access to constants from AFS include files. See the afsperlcons man
page for a complete list.

=back

=head1 EXAMPLES

 use AFS;

 $pts = newpts;

 @members = $pts->members("foo:bar");

 foreach $mem (sort @members) {
        printf("  $mem\n");
 }

 $acl = getacl("/afs");

 $user = ktc_principal(shift);

 $password = ka_UserReadPassword("password:");

 $ok = ka_UserAthenticateGeneral($user, $password, 300, 
          &AFS::KA_USERAUTH_VERSION | &AFS::KA_USERAUTH_DOSETPAG,
          $pw,$reason);

=head1 AUTHOR

Roland Schemers <schemers@slapshot.stanford.edu>

=head1 SEE ALSO

 The AFS command suite (fs, pts, kas)
 The AFS source tree :-)

=head1 CAVEATS

This module has been written with the help of AFS 3.3a source. It
might not work on earlier versions of AFS. Not all of the AFS commands
have been implemented (yet), most noticeably the vos commands.

=head1 BUGS

Probably too many to count at this point in time.

=head1 NOTES

The Perl motto is "There's more than one way to do it." The AFS module's
motto is "There's probably some way to do it, I just have to figure out what
the hell Roland called it!"

