# -*-cperl-*-
#------------------------------------------------------------------------------
# RCS-Id: "@(#)$Id: afsperlbase.pod 1059 2011-11-18 12:32:20Z nog $"
#
# © 2001-2010 Norbert E. Gruener <nog@MPA-Garching.MPG.de>
#
# This library is free software; you can redistribute it and/or modify it
# under the same terms as Perl itself.
#------------------------------------------------------------------------------

=head1 NAME

B<AFS> - Basic functions and variables of the B<AFS> module

=head1 SYNOPSIS

   use AFS qw (
              afsok checkafs constant
              error_message raise_exception
              );

   my $acl = getacl($path);
   if (afsok) ....
   checkafs('getacl');

   $old = raise_exception(1);
   ... make some calls you want to raise exceptions for
   ... there is an error
   raise_exception($old);

   $mess = error_message($code);

   $value = constant('PRIDEXIST'); # value = 267265
   $value = &AFS::PRIDEXIST;       # value = 267265, preferred method

   if ($AFS::CODE eq "User or group doesn't exist") ....
   if ($AFS::CODE == &AFS::PRNOENT) ....

=head1 DESCRIPTION

This document describes the special variables and convenience functions
available from the AFS module.  You can convert error codes into error
messages.  It is possible to activate exception handling for the AFS
system calls.  You can retrieve the values for AFS constants.  Any
function required must by explicitly listed by the C<use> statement to be
exported into the calling package.

=head1 COMPATIBILITY

B<This release does NOT support any features and interfaces
from version 1.>

=head1 Special Variables

=over 4

=item B<$AFS::CODE>

The special variable $AFS::CODE contains the status value of the last AFS
function call. A non-zero value indicates an error occurred, while a
zero indicates success. This variable is magical. (like the $! variable)
If you reference it as a string you will get an error message, and
if you reference it as a numeric value (use the int() function or add 0 to
it) it will equal the numeric error code.

=back

=head1 EXPORTS

=head2 Standard Exports

none

=head2 Optional Exports

The following functions will be exported into your namespace if you
specifically ask that they be imported.

=over 4

=item B<checkafs(CHECKPOINT);>

Convenience function that calls die and prints an error message if
$AFS::CODE is not equal to 0. Used mainly for debugging.

=item B<if (afsok) { ... }>

Convenience function that returns true if $AFS::CODE is equal to 0

=item B<$cur_raise_flg = raise_exception([NEW]);>

If NEW is set to 1, then a Perl exception will be raised whenever
an error is returned from an AFS function call. This is used mainly for
debugging and testing.

=item B<$msg = error_message(NUM_CODE);>

Converts numeric code NUM_CODE into an error string.

=item B<$val = constant(NAME);>

Converts a constant NAME (i.e, #define) into scaler. Returns undef for
unknown constants.

=item B<$val = &AFS::CONSTANT;>

All values referenced through the constant function can be referenced as
functions in the AFS package. This is the preferred way of accessing
constants.

=back

=head1 CURRENT AUTHOR

Norbert E. Gruener E<lt>nog@MPA-Garching.MPG.deE<gt>

=head1 AUTHOR EMERITUS

Roland Schemers E<lt>schemers@slapshot.stanford.eduE<gt>

=head1 COPYRIGHT AND DISCLAIMER

 Copyright (c) 2001-2010 Norbert E. Gruener <nog@MPA-Garching.MPG.de>.
 All rights reserved.

 Copyright (c) 1994 Board of Trustees, Leland Stanford Jr. University.
 All rights reserved.

This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.

=over 6

=item The original module is covered by the following copyright:

Copyright (c) 1994 Board of Trustees, Leland Stanford Jr. University

Redistribution and use in source and binary forms are permitted
provided that the above copyright notice and this paragraph are
duplicated in all such forms and that any documentation,
advertising materials, and other materials related to such
distribution and use acknowledge that the software was developed
by Stanford University.  The name of the University may not be used
to endorse or promote products derived from this software without
specific prior written permission.
THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

=back

=head1 DOCUMENT VERSION

Revision $Rev: 1059 $