/* * Copyright (c) Zmanda, Inc. All Rights Reserved. * * This library is free software; you can redistribute it and/or modify it * under the terms of the GNU Lesser General Public License version 2.1 * as published by the Free Software Foundation. * * This library is distributed in the hope that it will be useful, but * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public * License for more details. * * You should have received a copy of the GNU Lesser General Public License * along with this library; if not, write to the Free Software Foundation, * Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. * * Contact information: Zmanda Inc., 505 N Mathlida Ave, Suite 120 * Sunnyvale, CA 94085, USA, or: http://www.zmanda.com */ %module "Amanda::Config" %include "amglue/amglue.swg" %include "exception.i" %{ #include "conffile.h" %} %perlcode %{ =head1 NAME Amanda::Config - access to Amanda configuration parameters =head1 SYNOPSIS use Amanda::Config qw( :init :getconf ); config_init($CONFIG_INIT_EXPLICIT_NAME, $ARGV[1]) or die("errors processing config file " . $Amanda::Config::get_config_filename()); print "tape device is ", getconf($CNF_TAPEDEV), "\n"; This API closely parallels the C API. See F for details on the functions and constants available here. =head1 API STATUS Stable =head1 INITIALIZATION The Amanda configuration is treated as a global state for the application. It is not possible to load two configurations simultaneously. All initialization-related symbols can be imported with the tag C<:init>. =head2 LOADING CONFIGURATION The Amanda configuration is loaded with the aptly named C. Because of the great variety in invocation method among Amanda applications, this function has a number of flags that affect its behavior. These flags can be OR'd together. =over =item If C is given, then the C<$name> parameter can contain the name of a configuration to load. =item If C is given, and if the current directory contains C, then that file is loaded. =item If C is given, then a client configuration is loaded. =item If C is given, then any existing configuration is not reset. =item If C is given, then any errors are considered fatal, and C does not return. =back See C for more detailed information on these flags and their interactions. C reverses the effects of C. It is not often used. Once the configuration is loaded, the configuration name (e.g., "DailySet1"), directory (C), and filename (C) are available from C, C, and C, respectively. =head2 CONFIG OVERWRITES Most Amanda applications accept the command-line option C<-o> to "overwrite" configuration values in C. In Perl applications, these options should be parsed with L, with the action being a call to C. For example: my $config_overwrites = new_config_overwrites($#ARGV+1); GetOptions( # ... 'o=s' => sub { add_config_overwrite_opt($config_overwrites, $_[1]); }, ) or usage(); my $cfg_ok = config_init($CONFIG_INIT_EXPLICIT_NAME | $CONFIG_INIT_USE_CWD, $config_name); apply_config_overwrites($config_overwrites); C creates a new overwrites object, using the given size as an estimate of the number of items it will contain (C<$#ARGC/2> is a good estimate). Individual configuration options are then added via C (which takes a key/value pair) or C, which parses a string following C<-o> on the command line. Once the overwrites are gathered, they are applied with C, which applies the overwrites to the active configuration. No further operations can be performed on the overwrites object after C has been called. The utility function C returns a list of command-line arguments to represent any overwrites that were used to generate the current configuration. (TODO: this function isn't available yet) =head1 PARAMETER ACCESS Amanda configurations consist of "global" parameters and several sets of "subsections" -- one set for dumptypes, one for tapetypes, and so on. All of the global parameters are represented by a constant beginning with C<$CNF_>, e.g., C<$CNF_LABELSTR>. The function C returns the value of parameter C<$cnf>, in whatever format is appropriate for the parameter. C returns a true value if C<$cnf> was seen in the configuration file. If it was not seen, then it will have its default value. Some parameters have enumerated types. The values for those enumerations are available from this module with the same name as in C. For example, C<$CNF_TAPERALGO> will yield a value from the enumeration C, the constants for which all begin with C<$ALGO_>. See C for the details. Each subsection type has the following functions: =over =item C which returns an opaque object (C<$ss>) representing the subsection, or C if no subsection with that name exists; =item C returning the name of the subsection; =item C which fetches a parameter value from C<$ss>; and =item C which returns a true value if <$cnf> was seen in the subsection. =back The subsections are: =over =item C with constants beginning with C<$TAPETYPE_> =item C with constants beginning with C<$DUMPTYPE_> =item C with constants beginning with C<$HOLDING_> =item C with constants beginning with C<$APPLICATION_> =item C