git.gag.com Git - debian/amanda/blob - common-src/conffile.h

   1 /*
   2  * Amanda, The Advanced Maryland Automatic Network Disk Archiver
   3  * Copyright (c) 1991-2000 University of Maryland at College Park
   4  * All Rights Reserved.
   5  *
   6  * Permission to use, copy, modify, distribute, and sell this software and its
   7  * documentation for any purpose is hereby granted without fee, provided that
   8  * the above copyright notice appear in all copies and that both that
   9  * copyright notice and this permission notice appear in supporting
  10  * documentation, and that the name of U.M. not be used in advertising or
  11  * publicity pertaining to distribution of the software without specific,
  12  * written prior permission.  U.M. makes no representations about the
  13  * suitability of this software for any purpose.  It is provided "as is"
  14  * without express or implied warranty.
  15  *
  16  * U.M. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL
  17  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL U.M.
  18  * BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  19  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
  20  * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
  21  * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  22  *
  23  * Author: James da Silva, Systems Design and Analysis Group
  24  *                         Computer Science Department
  25  *                         University of Maryland at College Park
  26  */
  27 /*
  28  * $Id: conffile.h,v 1.72 2006/07/26 15:17:37 martinea Exp $
  29  *
  30  * interface for config file reading code
  31  */
  32 #ifndef CONFFILE_H
  33 #define CONFFILE_H
  34
  35 #include "amanda.h"
  36 #include "util.h"
  37
  38 /* Getting Configuration Values
  39  * ============================
  40  *
  41  * Amanda configurations consist of a number of "global" parameters, as well as
  42  * named subsections of several types.  The global parameters are fetched with
  43  * the getconf_CONFTYPE functions, keyed by a confparam_t constant (with prefix
  44  * CNF_).  The subsection parameters are fetched with SUBSEC_get_PARAM()
  45  * macros, e.g., tapetype_get_blocksize(ttyp), where the argument comes from
  46  * lookup_SUBSEC(), in this case lookup_tapetype(name).
  47  *
  48  * Types
  49  * =====
  50  *
  51  * This module juggles two kinds of types: C types and conftypes.  Conftypes include
  52  * everything from integers through property lists, and are specific to the needs of
  53  * the configuration system.  Each conftype has a corresponding C type, which is of course
  54  * necessary to actually use the data.
  55  *
  56  * The val_t__CONFTYPE macros represent the canonical correspondance of conftypes to C
  57  * types, but in general the relationship is obvious: ints, strings, reals, and so forth
  58  * are represented directly.  Enumerated conftypes are represented by the corresponding
  59  * C enum type.  The 'rate' conftype is represented as a 2-element array of doubles, and
  60  * the 'intrange' conftype is represented as a 2-element array of ints.  exincludes are
  61  * a exinclude_t *, and a proplist is represented as a GHashTable *.
  62  *
  63  * Memory
  64  * ======
  65  * Note that, unless specified, all memory in this module is managed by the module
  66  * itself; return strings should not be freed by the caller.
  67  *
  68  * Error Handling
  69  * ==============
  70  * All errors and warnings generated by this module are available from get_config_errors().
  71  * It is up to the caller to route these messages to the user.  The function
  72  * config_print_errors() will print the errors to stderr, as a convenience.
  73  */
  74
  75 /*
  76  * Generic values
  77  *
  78  * This module uses a generic val_t type to hold values of various types -- it's basically
  79  * a union with type information and a 'seen' flag.  In a way, it's a very simple equivalent
  80  * to Glib's GValue.  It's worth considering rewriting this with GValue, but for the moment,
  81  * this works and it's here.
  82  */
  83
  84 /* holdingdisk types */
  85 typedef enum {
  86     HOLD_NEVER,                 /* Always direct to tape  */
  87     HOLD_AUTO,                  /* If possible            */
  88     HOLD_REQUIRED               /* Always to holding disk */
  89 } dump_holdingdisk_t;
  90
  91 /* Compression types */
  92 typedef enum {
  93     COMP_NONE,          /* No compression */
  94     COMP_FAST,          /* Fast compression on client */
  95     COMP_BEST,          /* Best compression on client */
  96     COMP_CUST,          /* Custom compression on client */
  97     COMP_SERVER_FAST,   /* Fast compression on server */
  98     COMP_SERVER_BEST,   /* Best compression on server */
  99     COMP_SERVER_CUST    /* Custom compression on server */
 100 } comp_t;
 101
 102 /* Encryption types */
 103 typedef enum {
 104     ENCRYPT_NONE,               /* No encryption */
 105     ENCRYPT_CUST,               /* Custom encryption on client */
 106     ENCRYPT_SERV_CUST           /* Custom encryption on server */
 107 } encrypt_t;
 108
 109 /* Estimate strategies */
 110 typedef enum {
 111     ES_CLIENT,          /* client estimate */
 112     ES_SERVER,          /* server estimate */
 113     ES_CALCSIZE,        /* calcsize estimate */
 114     ES_ES /* sentinel */
 115 } estimate_t;
 116
 117 /* Dump strategies */
 118 typedef enum {
 119     DS_SKIP,        /* Don't do any dumps at all */
 120     DS_STANDARD,    /* Standard (0 1 1 1 1 2 2 2 ...) */
 121     DS_NOFULL,      /* No full's (1 1 1 ...) */
 122     DS_NOINC,       /* No inc's (0 0 0 ...) */
 123     DS_4,           /* ? (0 1 2 3 4 5 6 7 8 9 10 11 ...) */
 124     DS_5,           /* ? (0 1 1 1 1 1 1 1 1 1 1 1 ...) */
 125     DS_HANOI,       /* Tower of Hanoi (? ? ? ? ? ...) */
 126     DS_INCRONLY,    /* Forced fulls (0 1 1 2 2 FORCE0 1 1 ...) */
 127     DS_DS /* sentinel */
 128 } strategy_t;
 129
 130 typedef enum {
 131     ALGO_FIRST,
 132     ALGO_FIRSTFIT,
 133     ALGO_LARGEST,
 134     ALGO_LARGESTFIT,
 135     ALGO_SMALLEST,
 136     ALGO_LAST,
 137     ALGO_ALGO /* sentinel */
 138 } taperalgo_t;
 139
 140 /* execute_on types */
 141 #define EXECUTE_ON_PRE_DLE_AMCHECK     1<<0
 142 #define EXECUTE_ON_PRE_HOST_AMCHECK    1<<1
 143 #define EXECUTE_ON_POST_DLE_AMCHECK    1<<2
 144 #define EXECUTE_ON_POST_HOST_AMCHECK   1<<3
 145 #define EXECUTE_ON_PRE_DLE_ESTIMATE    1<<4
 146 #define EXECUTE_ON_PRE_HOST_ESTIMATE   1<<5
 147 #define EXECUTE_ON_POST_DLE_ESTIMATE   1<<6
 148 #define EXECUTE_ON_POST_HOST_ESTIMATE  1<<7
 149 #define EXECUTE_ON_PRE_DLE_BACKUP      1<<8
 150 #define EXECUTE_ON_PRE_HOST_BACKUP     1<<9
 151 #define EXECUTE_ON_POST_DLE_BACKUP     1<<10
 152 #define EXECUTE_ON_POST_HOST_BACKUP    1<<11
 153 #define EXECUTE_ON_PRE_RECOVER         1<<12
 154 #define EXECUTE_ON_POST_RECOVER        1<<13
 155 #define EXECUTE_ON_PRE_LEVEL_RECOVER   1<<14
 156 #define EXECUTE_ON_POST_LEVEL_RECOVER  1<<15
 157 #define EXECUTE_ON_INTER_LEVEL_RECOVER 1<<16
 158 typedef int execute_on_t;
 159
 160 typedef int execute_where_t;
 161
 162 typedef enum {
 163     SEND_AMREPORT_ALL,
 164     SEND_AMREPORT_STRANGE,
 165     SEND_AMREPORT_ERROR,
 166     SEND_AMREPORT_NEVER
 167 } send_amreport_t;
 168
 169 typedef struct exinclude_s {
 170     sl_t *sl_list;
 171     sl_t *sl_file;
 172     int  optional;
 173 } exinclude_t;
 174
 175 typedef struct {
 176     int append;
 177     int priority;
 178     GSList* values;
 179 } property_t;
 180
 181 typedef GHashTable* proplist_t;
 182 typedef GSList* pp_scriptlist_t;
 183
 184 /* Names for the type of value in a val_t.  Mostly for internal use, but useful
 185  * for wrapping val_t's, too. */
 186 typedef enum {
 187     CONFTYPE_INT,
 188     CONFTYPE_INT64,
 189     CONFTYPE_REAL,
 190     CONFTYPE_STR,
 191     CONFTYPE_IDENT,
 192     CONFTYPE_TIME,
 193     CONFTYPE_SIZE,
 194     CONFTYPE_BOOLEAN,
 195     CONFTYPE_COMPRESS,
 196     CONFTYPE_ENCRYPT,
 197     CONFTYPE_HOLDING,
 198     CONFTYPE_ESTIMATE,
 199     CONFTYPE_STRATEGY,
 200     CONFTYPE_TAPERALGO,
 201     CONFTYPE_PRIORITY,
 202     CONFTYPE_RATE,
 203     CONFTYPE_INTRANGE,
 204     CONFTYPE_EXINCLUDE,
 205     CONFTYPE_PROPLIST,
 206     CONFTYPE_APPLICATION,
 207     CONFTYPE_EXECUTE_ON,
 208     CONFTYPE_EXECUTE_WHERE,
 209     CONFTYPE_SEND_AMREPORT_ON,
 210     CONFTYPE_PP_SCRIPTLIST
 211 } conftype_t;
 212
 213 /* A "seen" struct.  Rather than allocate strings all over the place, this
 214  * string is in the "parsed_filenames" GSList and will be freed when that
 215  * GSList is freed.  This struct should be opaque to other modules. */
 216 typedef struct seen_s {
 217     char *filename;
 218     int linenum;
 219 } seen_t;
 220
 221 /* This should be considered an opaque type for any other modules.  The complete
 222  * struct is included here to allow quick access via macros. Access it *only* through
 223  * those macros. */
 224 typedef struct val_s {
 225     union {
 226         int             i;
 227         gint64          int64;
 228         double          r;
 229         char            *s;
 230         ssize_t         size;
 231         time_t          t;
 232         float           rate[2];
 233         exinclude_t     exinclude;
 234         int             intrange[2];
 235         proplist_t      proplist;
 236         struct application_s  *application;
 237         pp_scriptlist_t pp_scriptlist;
 238     } v;
 239     seen_t seen;
 240     conftype_t type;
 241 } val_t;
 242
 243 /* Functions to typecheck and extract a particular type of
 244  * value from a val_t.  All call error() if the type is incorrect,
 245  * as this is a programming error.  */
 246 int                   val_t_to_int      (val_t *);
 247 gint64                val_t_to_int64    (val_t *);
 248 float                 val_t_to_real     (val_t *);
 249 char                 *val_t_to_str      (val_t *); /* (also converts CONFTYPE_IDENT) */
 250 char                 *val_t_to_ident    (val_t *); /* (also converts CONFTYPE_STR) */
 251 time_t                val_t_to_time     (val_t *);
 252 ssize_t               val_t_to_size     (val_t *);
 253 int                   val_t_to_boolean  (val_t *);
 254 comp_t                val_t_to_compress (val_t *);
 255 encrypt_t             val_t_to_encrypt  (val_t *);
 256 dump_holdingdisk_t    val_t_to_holding  (val_t *);
 257 estimate_t            val_t_to_estimate (val_t *);
 258 strategy_t            val_t_to_strategy (val_t *);
 259 taperalgo_t           val_t_to_taperalgo(val_t *);
 260 int                   val_t_to_priority (val_t *);
 261 float                *val_t_to_rate     (val_t *); /* array of two floats */
 262 exinclude_t           val_t_to_exinclude(val_t *);
 263 int                  *val_t_to_intrange (val_t *); /* array of two ints */
 264 proplist_t            val_t_to_proplist (val_t *);
 265 struct application_s *val_t_to_application(val_t *);
 266 pp_scriptlist_t       val_t_to_pp_scriptlist(val_t *);
 267 execute_on_t          val_t_to_execute_on(val_t *);
 268 execute_where_t       val_t_to_execute_where(val_t *);
 269 send_amreport_t       val_t_to_send_amreport(val_t *);
 270
 271 /* Has the given val_t been seen in a configuration file or config overwrite?
 272  *
 273  * @param val: val_t* to examine
 274  * @returns: boolean
 275  */
 276 #define val_t_seen(val) ((val)->seen.linenum)
 277
 278 /* What is the underlying type of this val_t?
 279  *
 280  * @param val: val_t* to examine
 281  * @returns: conftype_t
 282  */
 283 #define val_t_type(val) ((val)->type)
 284
 285 /* Macros to convert val_t's to a particular type without the benefit of
 286  * a typecheck.  Use these only if you really know what you're doing!
 287  *
 288  * Implementation note: these macros encode the relationship of conftypes
 289  * (in the macro name) to the corresponding union field.  The macros work
 290  * as lvalues, too.
 291  */
 292 #define val_t__seen(val)          ((val)->seen)
 293 #define val_t__int(val)           ((val)->v.i)
 294 #define val_t__int64(val)         ((val)->v.int64)
 295 #define val_t__real(val)          ((val)->v.r)
 296 #define val_t__str(val)           ((val)->v.s)
 297 #define val_t__ident(val)         ((val)->v.s)
 298 #define val_t__time(val)          ((val)->v.t)
 299 #define val_t__size(val)          ((val)->v.size)
 300 #define val_t__boolean(val)       ((val)->v.i)
 301 #define val_t__compress(val)      ((val)->v.i)
 302 #define val_t__encrypt(val)       ((val)->v.i)
 303 #define val_t__holding(val)       ((val)->v.i)
 304 #define val_t__estimate(val)      ((val)->v.i)
 305 #define val_t__strategy(val)      ((val)->v.i)
 306 #define val_t__taperalgo(val)     ((val)->v.i)
 307 #define val_t__send_amreport(val) ((val)->v.i)
 308 #define val_t__priority(val)      ((val)->v.i)
 309 #define val_t__rate(val)          ((val)->v.rate)
 310 #define val_t__exinclude(val)     ((val)->v.exinclude)
 311 #define val_t__intrange(val)      ((val)->v.intrange)
 312 #define val_t__proplist(val)      ((val)->v.proplist)
 313 #define val_t__pp_scriptlist(val) ((val)->v.pp_scriptlist)
 314 #define val_t__application(val)   ((val)->v.application)
 315 #define val_t__execute_on(val)    ((val)->v.i)
 316 #define val_t__execute_where(val) ((val)->v.i)
 317 /*
 318  * Parameters
 319  *
 320  * Programs get val_t's by giving the index of the parameters they're interested in.
 321  * For global parameters, these start with CNF; for subsections, they start with the
 322  * name of the subsection.
 323  */
 324
 325 /*
 326  * Global parameter access
 327  */
 328 typedef enum {
 329     CNF_ORG,
 330     CNF_CONF,
 331     CNF_INDEX_SERVER,
 332     CNF_TAPE_SERVER,
 333     CNF_AUTH,
 334     CNF_SSH_KEYS,
 335     CNF_AMANDAD_PATH,
 336     CNF_CLIENT_USERNAME,
 337     CNF_GNUTAR_LIST_DIR,
 338     CNF_AMANDATES,
 339     CNF_MAILTO,
 340     CNF_DUMPUSER,
 341     CNF_TAPEDEV,
 342     CNF_RAWTAPEDEV,
 343     CNF_DEVICE_PROPERTY,
 344     CNF_PROPERTY,
 345     CNF_APPLICATION,
 346     CNF_APPLICATION_TOOL,
 347     CNF_EXECUTE_ON,
 348     CNF_PP_SCRIPT,
 349     CNF_PP_SCRIPT_TOOL,
 350     CNF_PLUGIN,
 351     CNF_CHANGERDEV,
 352     CNF_CHANGERFILE,
 353     CNF_LABELSTR,
 354     CNF_TAPELIST,
 355     CNF_DISKFILE,
 356     CNF_INFOFILE,
 357     CNF_LOGDIR,
 358     CNF_INDEXDIR,
 359     CNF_TAPETYPE,
 360     CNF_DUMPCYCLE,
 361     CNF_RUNSPERCYCLE,
 362     CNF_TAPECYCLE,
 363     CNF_NETUSAGE,
 364     CNF_INPARALLEL,
 365     CNF_DUMPORDER,
 366     CNF_BUMPPERCENT,
 367     CNF_BUMPSIZE,
 368     CNF_BUMPMULT,
 369     CNF_BUMPDAYS,
 370     CNF_TPCHANGER,
 371     CNF_RUNTAPES,
 372     CNF_MAXDUMPS,
 373     CNF_ETIMEOUT,
 374     CNF_DTIMEOUT,
 375     CNF_CTIMEOUT,
 376     CNF_TAPEBUFS,
 377     CNF_DEVICE_OUTPUT_BUFFER_SIZE,
 378     CNF_PRINTER,
 379     CNF_MAILER,
 380     CNF_AUTOFLUSH,
 381     CNF_RESERVE,
 382     CNF_MAXDUMPSIZE,
 383     CNF_COLUMNSPEC,
 384     CNF_AMRECOVER_DO_FSF,
 385     CNF_AMRECOVER_CHECK_LABEL,
 386     CNF_AMRECOVER_CHANGER,
 387     CNF_TAPERALGO,
 388     CNF_SEND_AMREPORT_ON,
 389     CNF_FLUSH_THRESHOLD_DUMPED,
 390     CNF_FLUSH_THRESHOLD_SCHEDULED,
 391     CNF_TAPERFLUSH,
 392     CNF_DISPLAYUNIT,
 393     CNF_KRB5KEYTAB,
 394     CNF_KRB5PRINCIPAL,
 395     CNF_LABEL_NEW_TAPES,
 396     CNF_USETIMESTAMPS,
 397     CNF_REP_TRIES,
 398     CNF_CONNECT_TRIES,
 399     CNF_REQ_TRIES,
 400     CNF_DEBUG_AMANDAD,
 401     CNF_DEBUG_AMIDXTAPED,
 402     CNF_DEBUG_AMINDEXD,
 403     CNF_DEBUG_AMRECOVER,
 404     CNF_DEBUG_AUTH,
 405     CNF_DEBUG_EVENT,
 406     CNF_DEBUG_HOLDING,
 407     CNF_DEBUG_PROTOCOL,
 408     CNF_DEBUG_PLANNER,
 409     CNF_DEBUG_DRIVER,
 410     CNF_DEBUG_DUMPER,
 411     CNF_DEBUG_CHUNKER,
 412     CNF_DEBUG_TAPER,
 413     CNF_DEBUG_SELFCHECK,
 414     CNF_DEBUG_SENDSIZE,
 415     CNF_DEBUG_SENDBACKUP,
 416     CNF_RESERVED_UDP_PORT,
 417     CNF_RESERVED_TCP_PORT,
 418     CNF_UNRESERVED_TCP_PORT,
 419     CNF_CNF /* sentinel */
 420 } confparm_key;
 421
 422 /* Given a confparm_key, return a pointer to the corresponding val_t.
 423  *
 424  * @param key: confparm_key
 425  * @returns: pointer to value
 426  */
 427 val_t *getconf(confparm_key key);
 428
 429 /* (convenience macro) has this global parameter been seen?
 430  *
 431  * @param key: confparm_key
 432  * @returns: boolean
 433  */
 434 #define getconf_seen(key)       (val_t_seen(getconf((key))))
 435
 436 /* (convenience macros)
 437  * Fetch a gloabl parameter of a specific type.  Note that these
 438  * convenience macros have a different form from those for the
 439  * subsections: here you specify a type and a key, while for the
 440  * subsections you specify only a key.  The difference is historical.
 441  *
 442  * @param key: confparm_key
 443  * @returns: various
 444  */
 445 #define getconf_int(key)          (val_t_to_int(getconf((key))))
 446 #define getconf_int64(key)        (val_t_to_int64(getconf((key))))
 447 #define getconf_real(key)         (val_t_to_real(getconf((key))))
 448 #define getconf_str(key)          (val_t_to_str(getconf((key))))
 449 #define getconf_ident(key)        (val_t_to_ident(getconf((key))))
 450 #define getconf_time(key)         (val_t_to_time(getconf((key))))
 451 #define getconf_size(key)         (val_t_to_size(getconf((key))))
 452 #define getconf_boolean(key)      (val_t_to_boolean(getconf((key))))
 453 #define getconf_compress(key)     (val_t_to_compress(getconf((key))))
 454 #define getconf_encrypt(key)      (val_t_to_encrypt(getconf((key))))
 455 #define getconf_holding(key)      (val_t_to_holding(getconf((key))))
 456 #define getconf_estimate(key)     (val_t_to_estimate(getconf((key))))
 457 #define getconf_strategy(key)     (val_t_to_strategy(getconf((key))))
 458 #define getconf_taperalgo(key)    (val_t_to_taperalgo(getconf((key))))
 459 #define getconf_priority(key)     (val_t_to_priority(getconf((key))))
 460 #define getconf_rate(key)         (val_t_to_rate(getconf((key))))
 461 #define getconf_exinclude(key)    (val_t_to_exinclude(getconf((key))))
 462 #define getconf_intrange(key)     (val_t_to_intrange(getconf((key))))
 463 #define getconf_proplist(key)     (val_t_to_proplist(getconf((key))))
 464 #define getconf_send_amreport(key) (val_t_to_send_amreport(getconf((key))))
 465
 466 /* Get a list of names for subsections of the given type
 467  *
 468  * @param listname: the desired type of subsection
 469  * @returns: list of subsection names; caller is responsible for freeing
 470  * this list, but not the strings it points to, using g_slist_free().
 471  */
 472 GSList *getconf_list(char *listname);
 473
 474 /* Get a configuration value by name, supporting the TYPE:SUBSEC:KEYWORD.
 475  * Returns NULL if the configuration value doesnt exist.
 476  */
 477 val_t *getconf_byname(char *key);
 478
 479 /*
 480  * Derived values
 481  *
 482  * Values which aren't directly specified by the configuration, but which
 483  * are derived from it.
 484  */
 485
 486 /* Return a divisor which will convert a value in units of kilo-whatevers
 487  * to the user's selected display unit.
 488  *
 489  * @returns: long integer divisor
 490  */
 491 long int getconf_unit_divisor(void);
 492
 493 /* If any of these globals are true, the corresponding component will
 494  * send verbose debugging output to the debug file.  The options are
 495  * set during config_init, but can be modified at will after that if
 496  * desired.  */
 497
 498 extern int debug_amandad;
 499 extern int debug_amidxtaped;
 500 extern int debug_amindexd;
 501 extern int debug_amrecover;
 502 extern int debug_auth;
 503 extern int debug_event;
 504 extern int debug_holding;
 505 extern int debug_protocol;
 506 extern int debug_planner;
 507 extern int debug_driver;
 508 extern int debug_dumper;
 509 extern int debug_chunker;
 510 extern int debug_taper;
 511 extern int debug_selfcheck;
 512 extern int debug_sendsize;
 513 extern int debug_sendbackup;
 514
 515 /*
 516  * Tapetype parameter access
 517  */
 518
 519 typedef enum {
 520     TAPETYPE_COMMENT,
 521     TAPETYPE_LBL_TEMPL,
 522     TAPETYPE_BLOCKSIZE,
 523     TAPETYPE_READBLOCKSIZE,
 524     TAPETYPE_LENGTH,
 525     TAPETYPE_FILEMARK,
 526     TAPETYPE_SPEED,
 527     TAPETYPE_FILE_PAD,
 528     TAPETYPE_TAPETYPE /* sentinel */
 529 } tapetype_key;
 530
 531 /* opaque object */
 532 typedef struct tapetype_s tapetype_t;
 533
 534 /* Given the name of the tapetype, return a tapetype object.  Returns NULL
 535  * if no matching tapetype exists.  Note that the match is case-insensitive.
 536  *
 537  * @param identifier: name of the desired tapetype
 538  * @returns: object or NULL
 539  */
 540 tapetype_t *lookup_tapetype(char *identifier);
 541
 542 /* Given a tapetype and a key, return a pointer to the corresponding val_t.
 543  *
 544  * @param ttyp: the tapetype to examine
 545  * @param key: tapetype_key (one of the TAPETYPE_* constants)
 546  * @returns: pointer to value
 547  */
 548 val_t *tapetype_getconf(tapetype_t *ttyp, tapetype_key key);
 549
 550 /* Get the name of this tapetype.
 551  *
 552  * @param ttyp: the tapetype to examine
 553  * @returns: name of the tapetype
 554  */
 555 char *tapetype_name(tapetype_t *ttyp);
 556
 557 /* (convenience macro) has this parameter been seen in this tapetype?  This
 558  * applies to the specific parameter *within* the tapetype.
 559  *
 560  * @param key: tapetype_key
 561  * @returns: boolean
 562  */
 563 #define tapetype_seen(ttyp, key)       (val_t_seen(tapetype_getconf((ttyp), (key))))
 564
 565 /* (convenience macros)
 566  * fetch a particular parameter; caller must know the correct type.
 567  *
 568  * @param ttyp: the tapetype to examine
 569  * @returns: various
 570  */
 571 #define tapetype_get_comment(ttyp)         (val_t_to_str(tapetype_getconf((ttyp), TAPETYPE_COMMENT)))
 572 #define tapetype_get_lbl_templ(ttyp)       (val_t_to_str(tapetype_getconf((ttyp), TAPETYPE_LBL_TEMPL)))
 573 #define tapetype_get_blocksize(ttyp)       (val_t_to_size(tapetype_getconf((ttyp), TAPETYPE_BLOCKSIZE)))
 574 #define tapetype_get_readblocksize(ttyp)   (val_t_to_size(tapetype_getconf((ttyp), TAPETYPE_READBLOCKSIZE)))
 575 #define tapetype_get_length(ttyp)          (val_t_to_int64(tapetype_getconf((ttyp), TAPETYPE_LENGTH)))
 576 #define tapetype_get_filemark(ttyp)        (val_t_to_int64(tapetype_getconf((ttyp), TAPETYPE_FILEMARK)))
 577 #define tapetype_get_speed(ttyp)           (val_t_to_int(tapetype_getconf((ttyp), TAPETYPE_SPEED)))
 578 #define tapetype_get_file_pad(ttyp)        (val_t_to_boolean(tapetype_getconf((ttyp), TAPETYPE_FILE_PAD)))
 579
 580 /*
 581  * Dumptype parameter access
 582  */
 583
 584 typedef enum {
 585     DUMPTYPE_COMMENT,
 586     DUMPTYPE_PROGRAM,
 587     DUMPTYPE_SRVCOMPPROG,
 588     DUMPTYPE_CLNTCOMPPROG,
 589     DUMPTYPE_SRV_ENCRYPT,
 590     DUMPTYPE_CLNT_ENCRYPT,
 591     DUMPTYPE_AMANDAD_PATH,
 592     DUMPTYPE_CLIENT_USERNAME,
 593     DUMPTYPE_SSH_KEYS,
 594     DUMPTYPE_SECURITY_DRIVER,
 595     DUMPTYPE_EXCLUDE,
 596     DUMPTYPE_INCLUDE,
 597     DUMPTYPE_PRIORITY,
 598     DUMPTYPE_DUMPCYCLE,
 599     DUMPTYPE_MAXDUMPS,
 600     DUMPTYPE_MAXPROMOTEDAY,
 601     DUMPTYPE_BUMPPERCENT,
 602     DUMPTYPE_BUMPSIZE,
 603     DUMPTYPE_BUMPDAYS,
 604     DUMPTYPE_BUMPMULT,
 605     DUMPTYPE_STARTTIME,
 606     DUMPTYPE_STRATEGY,
 607     DUMPTYPE_ESTIMATE,
 608     DUMPTYPE_COMPRESS,
 609     DUMPTYPE_ENCRYPT,
 610     DUMPTYPE_SRV_DECRYPT_OPT,
 611     DUMPTYPE_CLNT_DECRYPT_OPT,
 612     DUMPTYPE_COMPRATE,
 613     DUMPTYPE_TAPE_SPLITSIZE,
 614     DUMPTYPE_FALLBACK_SPLITSIZE,
 615     DUMPTYPE_SPLIT_DISKBUFFER,
 616     DUMPTYPE_RECORD,
 617     DUMPTYPE_SKIP_INCR,
 618     DUMPTYPE_SKIP_FULL,
 619     DUMPTYPE_HOLDINGDISK,
 620     DUMPTYPE_KENCRYPT,
 621     DUMPTYPE_IGNORE,
 622     DUMPTYPE_INDEX,
 623     DUMPTYPE_APPLICATION,
 624     DUMPTYPE_PP_SCRIPTLIST,
 625     DUMPTYPE_PROPERTY,
 626     DUMPTYPE_DUMPTYPE /* sentinel */
 627 } dumptype_key;
 628
 629 /* opaque object */
 630 typedef struct dumptype_s dumptype_t;
 631
 632 /* Given the name of the dumptype, return a dumptype object.  Returns NULL
 633  * if no matching dumptype exists.  Note that the match is case-insensitive.
 634  *
 635  * @param identifier: name of the desired dumptype
 636  * @returns: object or NULL
 637  */
 638 dumptype_t *lookup_dumptype(char *identifier);
 639
 640 /* Given a dumptype and a key, return a pointer to the corresponding val_t.
 641  *
 642  * @param dtyp: the dumptype to examine
 643  * @param key: dumptype_key (one of the TAPETYPE_* constants)
 644  * @returns: pointer to value
 645  */
 646 val_t *dumptype_getconf(dumptype_t *dtyp, dumptype_key key);
 647
 648 /* Get the name of this dumptype.
 649  *
 650  * @param dtyp: the dumptype to examine
 651  * @returns: name of the dumptype
 652  */
 653 char *dumptype_name(dumptype_t *dtyp);
 654
 655 /* (convenience macro) has this parameter been seen in this dumptype?  This
 656  * applies to the specific parameter *within* the dumptype.
 657  *
 658  * @param key: dumptype_key
 659  * @returns: boolean
 660  */
 661 #define dumptype_seen(dtyp, key)       (val_t_seen(dumptype_getconf((dtyp), (key))))
 662
 663 /* (convenience macros)
 664  * fetch a particular parameter; caller must know the correct type.
 665  *
 666  * @param dtyp: the dumptype to examine
 667  * @returns: various
 668  */
 669 #define dumptype_get_comment(dtyp)             (val_t_to_str(dumptype_getconf((dtyp), DUMPTYPE_COMMENT)))
 670 #define dumptype_get_program(dtyp)             (val_t_to_str(dumptype_getconf((dtyp), DUMPTYPE_PROGRAM)))
 671 #define dumptype_get_srvcompprog(dtyp)         (val_t_to_str(dumptype_getconf((dtyp), DUMPTYPE_SRVCOMPPROG)))
 672 #define dumptype_get_clntcompprog(dtyp)        (val_t_to_str(dumptype_getconf((dtyp), DUMPTYPE_CLNTCOMPPROG)))
 673 #define dumptype_get_srv_encrypt(dtyp)         (val_t_to_str(dumptype_getconf((dtyp), DUMPTYPE_SRV_ENCRYPT)))
 674 #define dumptype_get_clnt_encrypt(dtyp)        (val_t_to_str(dumptype_getconf((dtyp), DUMPTYPE_CLNT_ENCRYPT)))
 675 #define dumptype_get_amandad_path(dtyp)        (val_t_to_str(dumptype_getconf((dtyp), DUMPTYPE_AMANDAD_PATH)))
 676 #define dumptype_get_client_username(dtyp)     (val_t_to_str(dumptype_getconf((dtyp), DUMPTYPE_CLIENT_USERNAME)))
 677 #define dumptype_get_ssh_keys(dtyp)            (val_t_to_str(dumptype_getconf((dtyp), DUMPTYPE_SSH_KEYS)))
 678 #define dumptype_get_security_driver(dtyp)     (val_t_to_str(dumptype_getconf((dtyp), DUMPTYPE_SECURITY_DRIVER)))
 679 #define dumptype_get_exclude(dtyp)             (val_t_to_exinclude(dumptype_getconf((dtyp), DUMPTYPE_EXCLUDE)))
 680 #define dumptype_get_include(dtyp)             (val_t_to_exinclude(dumptype_getconf((dtyp), DUMPTYPE_INCLUDE)))
 681 #define dumptype_get_priority(dtyp)            (val_t_to_priority(dumptype_getconf((dtyp), DUMPTYPE_PRIORITY)))
 682 #define dumptype_get_dumpcycle(dtyp)           (val_t_to_int(dumptype_getconf((dtyp), DUMPTYPE_DUMPCYCLE)))
 683 #define dumptype_get_maxcycle(dtyp)            (val_t_to_int(dumptype_getconf((dtyp), DUMPTYPE_MAXCYCLE)))
 684 #define dumptype_get_frequency(dtyp)           (val_t_to_int(dumptype_getconf((dtyp), DUMPTYPE_FREQUENCY)))
 685 #define dumptype_get_maxdumps(dtyp)            (val_t_to_int(dumptype_getconf((dtyp), DUMPTYPE_MAXDUMPS)))
 686 #define dumptype_get_maxpromoteday(dtyp)       (val_t_to_int(dumptype_getconf((dtyp), DUMPTYPE_MAXPROMOTEDAY)))
 687 #define dumptype_get_bumppercent(dtyp)         (val_t_to_int(dumptype_getconf((dtyp), DUMPTYPE_BUMPPERCENT)))
 688 #define dumptype_get_bumpsize(dtyp)            (val_t_to_int64(dumptype_getconf((dtyp), DUMPTYPE_BUMPSIZE)))
 689 #define dumptype_get_bumpdays(dtyp)            (val_t_to_int(dumptype_getconf((dtyp), DUMPTYPE_BUMPDAYS)))
 690 #define dumptype_get_bumpmult(dtyp)            (val_t_to_real(dumptype_getconf((dtyp), DUMPTYPE_BUMPMULT)))
 691 #define dumptype_get_starttime(dtyp)           (val_t_to_time(dumptype_getconf((dtyp), DUMPTYPE_STARTTIME)))
 692 #define dumptype_get_strategy(dtyp)            (val_t_to_strategy(dumptype_getconf((dtyp), DUMPTYPE_STRATEGY)))
 693 #define dumptype_get_estimate(dtyp)            (val_t_to_estimate(dumptype_getconf((dtyp), DUMPTYPE_ESTIMATE)))
 694 #define dumptype_get_compress(dtyp)            (val_t_to_compress(dumptype_getconf((dtyp), DUMPTYPE_COMPRESS)))
 695 #define dumptype_get_encrypt(dtyp)             (val_t_to_encrypt(dumptype_getconf((dtyp), DUMPTYPE_ENCRYPT)))
 696 #define dumptype_get_srv_decrypt_opt(dtyp)     (val_t_to_str(dumptype_getconf((dtyp), DUMPTYPE_SRV_DECRYPT_OPT)))
 697 #define dumptype_get_clnt_decrypt_opt(dtyp)    (val_t_to_str(dumptype_getconf((dtyp), DUMPTYPE_CLNT_DECRYPT_OPT)))
 698 #define dumptype_get_comprate(dtyp)            (val_t_to_rate(dumptype_getconf((dtyp), DUMPTYPE_COMPRATE)))
 699 #define dumptype_get_tape_splitsize(dtyp)      (val_t_to_int64(dumptype_getconf((dtyp), DUMPTYPE_TAPE_SPLITSIZE)))
 700 #define dumptype_get_fallback_splitsize(dtyp)  (val_t_to_int64(dumptype_getconf((dtyp), DUMPTYPE_FALLBACK_SPLITSIZE)))
 701 #define dumptype_get_split_diskbuffer(dtyp)    (val_t_to_str(dumptype_getconf((dtyp), DUMPTYPE_SPLIT_DISKBUFFER)))
 702 #define dumptype_get_record(dtyp)              (val_t_to_boolean(dumptype_getconf((dtyp), DUMPTYPE_RECORD)))
 703 #define dumptype_get_skip_incr(dtyp)           (val_t_to_boolean(dumptype_getconf((dtyp), DUMPTYPE_SKIP_INCR)))
 704 #define dumptype_get_skip_full(dtyp)           (val_t_to_boolean(dumptype_getconf((dtyp), DUMPTYPE_SKIP_FULL)))
 705 #define dumptype_get_to_holdingdisk(dtyp)      (val_t_to_holding(dumptype_getconf((dtyp), DUMPTYPE_HOLDINGDISK)))
 706 #define dumptype_get_kencrypt(dtyp)            (val_t_to_boolean(dumptype_getconf((dtyp), DUMPTYPE_KENCRYPT)))
 707 #define dumptype_get_ignore(dtyp)              (val_t_to_boolean(dumptype_getconf((dtyp), DUMPTYPE_IGNORE)))
 708 #define dumptype_get_index(dtyp)               (val_t_to_boolean(dumptype_getconf((dtyp), DUMPTYPE_INDEX)))
 709 #define dumptype_get_application(dtyp)         (val_t_to_application(dumptype_getconf((dtyp), DUMPTYPE_APPLICATION)))
 710 #define dumptype_get_pp_scriptlist(dtyp)       (val_t_to_pp_scriptlist(dumptype_getconf((dtyp), DUMPTYPE_PP_SCRIPTLIST)))
 711 #define dumptype_get_property(dtyp)            (val_t_to_proplist(dumptype_getconf((dtyp), DUMPTYPE_PROPERTY)))
 712
 713 /*
 714  * Interface parameter access
 715  */
 716
 717 typedef enum {
 718     INTER_COMMENT,
 719     INTER_MAXUSAGE,
 720     INTER_INTER /* sentinel */
 721 } interface_key;
 722
 723 /* opaque object */
 724 typedef struct interface_s interface_t;
 725
 726 /* Given the name of the interface, return a interface object.  Returns NULL
 727  * if no matching interface exists.  Note that the match is case-insensitive.
 728  *
 729  * @param identifier: name of the desired interface
 730  * @returns: object or NULL
 731  */
 732 interface_t *lookup_interface(char *identifier);
 733
 734 /* Given a interface and a key, return a pointer to the corresponding val_t.
 735  *
 736  * @param iface: the interface to examine
 737  * @param key: interface_key (one of the TAPETYPE_* constants)
 738  * @returns: pointer to value
 739  */
 740 val_t *interface_getconf(interface_t *iface, interface_key key);
 741
 742 /* Get the name of this interface.
 743  *
 744  * @param iface: the interface to examine
 745  * @returns: name of the interface
 746  */
 747 char *interface_name(interface_t *iface);
 748
 749 /* (convenience macro) has this parameter been seen in this interface?  This
 750  * applies to the specific parameter *within* the interface.
 751  *
 752  * @param key: interface_key
 753  * @returns: boolean
 754  */
 755 #define interface_seen(iface, key)       (val_t_seen(interface_getconf((iface), (key))))
 756
 757 /* (convenience macros)
 758  * fetch a particular parameter; caller must know the correct type.
 759  *
 760  * @param iface: the interface to examine
 761  * @returns: various
 762  */
 763 #define interface_get_comment(iface)    (val_t_to_str(interface_getconf((iface), INTER_COMMENT)))
 764 #define interface_get_maxusage(iface)   (val_t_to_int(interface_getconf((iface), INTER_MAXUSAGE)))
 765
 766 /*
 767  * Holdingdisk parameter access
 768  */
 769
 770 typedef enum {
 771     HOLDING_COMMENT,
 772     HOLDING_DISKDIR,
 773     HOLDING_DISKSIZE,
 774     HOLDING_CHUNKSIZE,
 775     HOLDING_HOLDING /* sentinel */
 776 } holdingdisk_key;
 777
 778 /* opaque object */
 779 typedef struct holdingdisk_s holdingdisk_t;
 780
 781 /* Given the name of the holdingdisk, return a holdingdisk object.  Returns NULL
 782  * if no matching holdingdisk exists.  Note that the match is case-insensitive.
 783  *
 784  * @param identifier: name of the desired holdingdisk
 785  * @returns: object or NULL
 786  */
 787 holdingdisk_t *lookup_holdingdisk(char *identifier);
 788
 789 /* Return the whole linked list of holdingdisks.  Use holdingdisk_next
 790  * to traverse the list.
 791  *
 792  * @returns: first holding disk
 793  */
 794 holdingdisk_t *getconf_holdingdisks(void);
 795
 796 /* Return the next holdingdisk in the list.
 797  *
 798  * @param hdisk: holding disk
 799  * @returns: NULL if hdisk is the last disk, otherwise the next holding
 800  * disk
 801  */
 802 holdingdisk_t *holdingdisk_next(holdingdisk_t *hdisk);
 803
 804 /* Given a holdingdisk and a key, return a pointer to the corresponding val_t.
 805  *
 806  * @param hdisk: the holdingdisk to examine
 807  * @param key: holdingdisk_key (one of the TAPETYPE_* constants)
 808  * @returns: pointer to value
 809  */
 810 val_t *holdingdisk_getconf(holdingdisk_t *hdisk, holdingdisk_key key);
 811
 812 /* Get the name of this holdingdisk.
 813  *
 814  * @param hdisk: the holdingdisk to examine
 815  * @returns: name of the holdingdisk
 816  */
 817 char *holdingdisk_name(holdingdisk_t *hdisk);
 818
 819 /* (convenience macro) has this parameter been seen in this holdingdisk?  This
 820  * applies to the specific parameter *within* the holdingdisk.
 821  *
 822  * @param key: holdingdisk_key
 823  * @returns: boolean
 824  */
 825 #define holdingdisk_seen(hdisk, key)       (val_t_seen(holdingdisk_getconf((hdisk), (key))))
 826
 827 /* (convenience macros)
 828  * fetch a particular parameter; caller must know the correct type.
 829  *
 830  * @param hdisk: the holdingdisk to examine
 831  * @returns: various
 832  */
 833 #define holdingdisk_get_comment(hdisk)   (val_t_to_str(holdingdisk_getconf((hdisk), HOLDING_COMMENT)))
 834 #define holdingdisk_get_diskdir(hdisk)   (val_t_to_str(holdingdisk_getconf((hdisk), HOLDING_DISKDIR)))
 835 #define holdingdisk_get_disksize(hdisk)  (val_t_to_int64(holdingdisk_getconf((hdisk), HOLDING_DISKSIZE)))
 836 #define holdingdisk_get_chunksize(hdisk) (val_t_to_int64(holdingdisk_getconf((hdisk), HOLDING_CHUNKSIZE)))
 837
 838 /* A application-tool interface */
 839 typedef enum application_e  {
 840     APPLICATION_COMMENT,
 841     APPLICATION_PLUGIN,
 842     APPLICATION_PROPERTY,
 843     APPLICATION_APPLICATION
 844 } application_key;
 845
 846 /* opaque object */
 847 typedef struct application_s application_t;
 848
 849 /* Given the name of the application, return a application object.  Returns NULL
 850  * if no matching application exists.  Note that the match is case-insensitive.
 851  *
 852  * @param identifier: name of the desired application
 853  * @returns: object or NULL
 854  */
 855
 856 application_t *lookup_application(char *identifier);
 857
 858 /* Given a application and a key, return a pointer to the corresponding val_t.
 859  *
 860  * @param ttyp: the application to examine
 861  * @param key: application (one of the APPLICATION_* constants)
 862  * @returns: pointer to value
 863  */
 864 val_t *application_getconf(application_t *app, application_key key);
 865
 866 /* Get the name of this application.
 867  *
 868  * @param ttyp: the application to examine
 869  * @returns: name of the application
 870  */
 871 char *application_name(application_t *app);
 872
 873 /* (convenience macro) has this parameter been seen in this application?  This
 874  * applies to the specific parameter *within* the application.
 875  *
 876  * @param key: application_key
 877  * @returns: boolean
 878  */
 879 #define application_seen(app, key)       (val_t_seen(application_getconf((app), (key))))
 880
 881 /* (convenience macros)
 882  * fetch a particular parameter; caller must know the correct type.
 883  *
 884  * @param ttyp: the application to examine
 885  * @returns: various
 886  */
 887 #define application_get_comment(application)  (val_t_to_str(application_getconf((application), APPLICATION_COMMENT))
 888 #define application_get_plugin(application)   (val_t_to_str(application_getconf((application), APPLICATION_PLUGIN)))
 889 #define application_get_property(application) (val_t_to_proplist(application_getconf((application), APPLICATION_PROPERTY)))
 890
 891 application_t *read_application(char *name, FILE *from, char *fname, int *linenum);
 892
 893 /* A pp-script-tool interface */
 894 typedef enum pp_script_e  {
 895     PP_SCRIPT_COMMENT,
 896     PP_SCRIPT_PLUGIN,
 897     PP_SCRIPT_PROPERTY,
 898     PP_SCRIPT_EXECUTE_ON,
 899     PP_SCRIPT_EXECUTE_WHERE,
 900     PP_SCRIPT_PP_SCRIPT
 901 } pp_script_key;
 902
 903 /* opaque object */
 904 typedef struct pp_script_s pp_script_t;
 905
 906 /* Given the name of the pp_script, return a pp_script object.  Returns NULL
 907  * if no matching pp_script exists.  Note that the match is case-insensitive.
 908  *
 909  * @param identifier: name of the desired pp_script
 910  * @returns: object or NULL
 911  */
 912
 913 pp_script_t *lookup_pp_script(char *identifier);
 914
 915 /* Given a pp_script and a key, return a pointer to the corresponding val_t.
 916  *
 917  * @param ttyp: the pp_script to examine
 918  * @param key: pp_script (one of the PP_SCRIPT_* constants)
 919  * @returns: pointer to value
 920  */
 921 val_t *pp_script_getconf(pp_script_t *pps, pp_script_key key);
 922
 923 /* Get the name of this pp_script.
 924  *
 925  * @param ttyp: the pp_script to examine
 926  * @returns: name of the pp_script
 927  */
 928 char *pp_script_name(pp_script_t *pps);
 929
 930 /* (convenience macro) has this parameter been seen in this pp_script?  This
 931  * applies to the specific parameter *within* the pp_script.
 932  *
 933  * @param key: pp_script_key
 934  * @returns: boolean
 935  */
 936 #define pp_script_seen(pps, key)       (val_t_seen(pp_script_getconf((pps), (key))))
 937
 938 /* (convenience macros)
 939  * fetch a particular parameter; caller must know the correct type.
 940  *
 941  * @param ttyp: the pp_script to examine
 942  * @returns: various
 943  */
 944
 945 #define pp_script_get_comment(pp_script)   (val_t_to_str(pp_script_getconf((pp_script), PP_SCRIPT_COMMENT)))
 946 #define pp_script_get_plugin(pp_script)   (val_t_to_str(pp_script_getconf((pp_script), PP_SCRIPT_PLUGIN)))
 947 #define pp_script_get_property(pp_script)   (val_t_to_proplist(pp_script_getconf((pp_script), PP_SCRIPT_PROPERTY)))
 948 #define pp_script_get_execute_on(pp_script)   (val_t_to_execute_on(pp_script_getconf((pp_script), PP_SCRIPT_EXECUTE_ON)))
 949 #define pp_script_get_execute_where(pp_script)   (val_t_to_execute_where(pp_script_getconf((pp_script), PP_SCRIPT_EXECUTE_WHERE)))
 950
 951 pp_script_t *read_pp_script(char *name, FILE *from, char *fname, int *linenum);
 952 pp_script_t *lookup_pp_script(char *identifier);
 953
 954 /* A device definition */
 955 typedef enum {
 956     DEVICE_CONFIG_COMMENT,
 957     DEVICE_CONFIG_TAPEDEV,
 958     DEVICE_CONFIG_DEVICE_PROPERTY,
 959     DEVICE_CONFIG_DEVICE_CONFIG
 960 } device_config_key;
 961
 962 /* opaque object */
 963 typedef struct device_config_s device_config_t;
 964
 965 /* Given the name of the device, return a device_config_t object.  Returns NULL
 966  * if no matching device exists.  Note that the match is case-insensitive.
 967  *
 968  * @param identifier: name of the desired device
 969  * @returns: object or NULL
 970  */
 971
 972 device_config_t *lookup_device_config(char *identifier);
 973
 974 /* Given a device_config and a key, return a pointer to the corresponding val_t.
 975  *
 976  * @param ttyp: the device_config to examine
 977  * @param key: device_config (one of the DEVICE_CONFIG_* constants)
 978  * @returns: pointer to value
 979  */
 980 val_t *device_config_getconf(device_config_t *devconf, device_config_key key);
 981
 982 /* Get the name of this device_config.
 983  *
 984  * @param ttyp: the device_config to examine
 985  * @returns: name of the device_config
 986  */
 987 char *device_config_name(device_config_t *devconf);
 988
 989 /* (convenience macro) has this parameter been seen in this device_config?  This
 990  * applies to the specific parameter *within* the device_config.
 991  *
 992  * @param key: device_config_key
 993  * @returns: boolean
 994  */
 995 #define device_config_seen(devconf, key)       (val_t_seen(device_config_getconf((devconf), (key))))
 996
 997 /* (convenience macros)
 998  * fetch a particular parameter; caller must know the correct type.
 999  *
1000  * @param devconf: the device_config to examine
1001  * @returns: various
1002  */
1003
1004 #define device_config_get_comment(devconf)   (val_t_to_str(device_config_getconf((devconf), DEVICE_CONFIG_COMMENT)))
1005 #define device_config_get_tapedev(devconf)   (val_t_to_str(device_config_getconf((devconf), DEVICE_CONFIG_TAPEDEV)))
1006 #define device_config_get_property(devconf)   (val_t_to_proplist(device_config_getconf((devconf), DEVICE_CONFIG_DEVICE_PROPERTY)))
1007
1008 device_config_t *read_device_config(char *name, FILE *from, char *fname, int *linenum);
1009 device_config_t *lookup_device_config(char *identifier);
1010
1011 /* A changer definition */
1012 typedef enum {
1013     CHANGER_CONFIG_COMMENT,
1014     CHANGER_CONFIG_TAPEDEV,
1015     CHANGER_CONFIG_TPCHANGER,
1016     CHANGER_CONFIG_CHANGERDEV,
1017     CHANGER_CONFIG_CHANGERFILE,
1018     CHANGER_CONFIG_CHANGER_CONFIG
1019 } changer_config_key;
1020
1021 /* opaque object */
1022 typedef struct changer_config_s changer_config_t;
1023
1024 /* Given the name of the changer, return a changer_config_t object.  Returns NULL
1025  * if no matching changer exists.  Note that the match is case-insensitive.
1026  *
1027  * @param identifier: name of the desired changer
1028  * @returns: object or NULL
1029  */
1030
1031 changer_config_t *lookup_changer_config(char *identifier);
1032
1033 /* Given a changer_config and a key, return a pointer to the corresponding val_t.
1034  *
1035  * @param ttyp: the changer_config to examine
1036  * @param key: changer_config (one of the DEVICE_CONFIG_* constants)
1037  * @returns: pointer to value
1038  */
1039 val_t *changer_config_getconf(changer_config_t *devconf, changer_config_key key);
1040
1041 /* Get the name of this changer_config.
1042  *
1043  * @param ttyp: the changer_config to examine
1044  * @returns: name of the changer_config
1045  */
1046 char *changer_config_name(changer_config_t *devconf);
1047
1048 /* (convenience macro) has this parameter been seen in this changer_config?  This
1049  * applies to the specific parameter *within* the changer_config.
1050  *
1051  * @param key: changer_config_key
1052  * @returns: boolean
1053  */
1054 #define changer_config_seen(devconf, key)       (val_t_seen(changer_config_getconf((devconf), (key))))
1055
1056 /* (convenience macros)
1057  * fetch a particular parameter; caller must know the correct type.
1058  *
1059  * @param devconf: the changer_config to examine
1060  * @returns: various
1061  */
1062
1063 #define changer_config_get_comment(devconf)   (val_t_to_str(changer_config_getconf((devconf), DEVICE_CONFIG_COMMENT)))
1064 #define changer_config_get_tapedev(devconf)   (val_t_to_str(changer_config_getconf((devconf), DEVICE_CONFIG_TAPEDEV)))
1065 #define changer_config_get_tpchanger(devconf)   (val_t_to_str(changer_config_getconf((devconf), DEVICE_CONFIG_TPCHANGER)))
1066 #define changer_config_get_changerdev(devconf)   (val_t_to_str(changer_config_getconf((devconf), DEVICE_CONFIG_CHANGERDEV)))
1067 #define changer_config_get_changerfile(devconf)   (val_t_to_str(changer_config_getconf((devconf), DEVICE_CONFIG_CHANGERFILE)))
1068
1069 changer_config_t *read_changer_config(char *name, FILE *from, char *fname, int *linenum);
1070 changer_config_t *lookup_changer_config(char *identifier);
1071
1072 /*
1073  * Error Handling
1074  */
1075
1076 typedef enum {
1077     /* No errors or warnings */
1078     CFGERR_OK = 0,
1079
1080     /* warnings were encountered */
1081     CFGERR_WARNINGS = 1,
1082
1083     /* errors (and maybe some warnings too, who knows) were encountered */
1084     CFGERR_ERRORS = 2,
1085 } cfgerr_level_t;
1086
1087 /*
1088  * Errors
1089  */
1090
1091 /* Get a GSList of all error and warning messages accumulated so far.
1092  *
1093  * @param (output) errlist: pointer to the list of error strings; allocated
1094  * memory remains the responsibility of the config module.  If errlist is
1095  * NULL, the list is not returned.
1096  * @returns: current error level
1097  */
1098 cfgerr_level_t config_errors(GSList **errlist);
1099
1100 /* Clear any error conditions.
1101  */
1102 void config_clear_errors(void);
1103
1104 /* Print the list of current error and warning messages, one per line,
1105  * to stderr. This is a convenience function for command-line
1106  * applications.
1107  */
1108 void config_print_errors(void);
1109
1110 /* Add an error message to the list of errors, and make sure tha the
1111  * error level is at least LEVEL.  This is used by the diskfile module
1112  * to insert its errors into this module's error list.
1113  *
1114  * @param level: level for this error
1115  * @param errmsg: error message; conffile takes responsibility for freeing
1116  *   this string.
1117  */
1118 void config_add_error(cfgerr_level_t level, char *errmsg);
1119
1120 /*
1121  * Command-line handling
1122  */
1123
1124 /* opaque type */
1125 typedef struct config_overwrites_s config_overwrites_t;
1126
1127 /* Create a new, empty config_overwrites object.
1128  *
1129  * @param size_estimate: a guess at the number of overwrites; argc/2 is a
1130  *  good estimate.
1131  * @returns: new object
1132  */
1133 config_overwrites_t *new_config_overwrites(int size_estimate);
1134
1135 /* Free a config_overwrites object.  This usually won't be needed, as
1136  * apply_config_overwrites takes ownership of the overwrites for you.
1137  *
1138  * @param co: config_overwrites object
1139  */
1140 void free_config_overwrites(config_overwrites_t *co);
1141
1142 /* Add an overwrite to a config_overwrites object.
1143  *
1144  * @param co: the config_overwrites object
1145  * @param key: the configuration parameter's key, possibly with the format
1146  * SUBTYPE:NAME:KEYWORD
1147  * @param value: the value for the parameter, as would be seen in amanda.conf
1148  */
1149 void add_config_overwrite(config_overwrites_t *co,
1150                          char *key,
1151                          char *value);
1152
1153 /* Add an overwrite option from the command line to a config_overwrites
1154  * object.  Calls error() with any errors
1155  *
1156  * @param co: the config_overwrites object
1157  * @param optarg: the value of the command-line option
1158  */
1159 void add_config_overwrite_opt(config_overwrites_t *co,
1160                               char *optarg);
1161
1162 /* Given a command line, represented as argc/argv, extract any -o options
1163  * as config overwrites.  This function modifies argc and argv in place.
1164  *
1165  * This is the deprecated way to extract config overwrites, for applications
1166  * which do not use getopt.  The preferred method is to use getopt and
1167  * call add_config_overwrite_opt for any -o options.
1168  *
1169  * @param argc: (in/out) command-line length
1170  * @param argv: (in/out) command-line strings
1171  * @returns: newly allocated config_overwrites object
1172  */
1173 config_overwrites_t *
1174 extract_commandline_config_overwrites(int *argc,
1175                                       char ***argv);
1176
1177 /* Apply configuration overwrites to the current configuration and take
1178  * ownership of the config_overwrites object.  It is the caller's
1179  * responsibility to handle any errors.
1180  *
1181  * @param co: the config_overwrites object
1182  * @returns: current error level
1183  */
1184 cfgerr_level_t apply_config_overwrites(config_overwrites_t *co);
1185
1186 /*
1187  * Initialization
1188  */
1189
1190 /* Constants for config_init */
1191 typedef enum {
1192     /* Use arg_config_name, if not NULL */
1193     CONFIG_INIT_EXPLICIT_NAME = 1 << 0,
1194
1195     /* Use the current working directory if an explicit name is not available */
1196     CONFIG_INIT_USE_CWD = 1 << 1,
1197
1198     /* This is a client application (server is default) */
1199     CONFIG_INIT_CLIENT = 1 << 2,
1200
1201     /* New configuration should "overlay" existing configuration; this
1202      * is used by clients to load multiple amanda-client.conf files. */
1203     CONFIG_INIT_OVERLAY = 1 << 3,
1204 } config_init_flags;
1205
1206 /* Initialize this application's configuration, with the specific actions
1207  * based on 'flags':
1208  *  - if CONFIG_INIT_OVERLAY is not set, configuration values are reset
1209  *    to their defaults
1210  *  - if CONFIG_INIT_EXPLICIT_NAME and arg_config_name is not NULL,
1211  *    use CONFIG_DIR/arg_config_name as config_dir arg_config_name as
1212  *    config_name.
1213  *  - otherwise, if CONFIG_USE_CWD is set, use the directory in which
1214  *    the application was started as config_dir, and its filename as
1215  *    config_name.
1216  *  - otherwise, for the client only, se config_dir to CONFIG_DIR and
1217  *    config_name to NULL.
1218  *  - depending on CONFIG_INIT_CLIENT, read amanda.conf or amanda-client.conf
1219  *
1220  * @param flags: flags indicating desired behavior, as above
1221  * @param arg_config_name: config name to use (from e.g., argv[1])
1222  * @returns: current error level
1223  */
1224 cfgerr_level_t config_init(
1225          config_init_flags flags,
1226          char *arg_config_name);
1227
1228 /* Free all memory allocated for the configuration.  This effectively
1229  * reverses the effects of config_init().
1230  */
1231 void config_uninit(void);
1232
1233 /* Encode any applied config_overwrites into a strv format suitale for
1234  * executing another Amanda tool.
1235  *
1236  * The * result is dynamically allocated and NULL terminated.  There is no
1237  * provision to free the result, as this function is always called just
1238  * before execve(..).
1239  *
1240  * First gives the number of array elements to leave for the caller to
1241  * fill in.  The usual calling pattern is this:
1242  *   command_line = get_config_options(3);
1243  *   command_line[0] = "appname";
1244  *   command_line[1] = config_name;
1245  *   command_line[2] = "--foo";
1246  *   execve(command_line[0], command_line, safe_env());
1247  *
1248  * @param first: number of unused elements to leave at the beginning of
1249  * the array.
1250  * @returns: NULL-terminated string array suitable for execve
1251  */
1252 char **get_config_options(int first);
1253
1254 /* Get the config name */
1255 char *get_config_name(void);
1256
1257 /* Get the config directory */
1258 char *get_config_dir(void);
1259
1260 /* Get the config filename */
1261 char *get_config_filename(void);
1262
1263 /*
1264  * Utilities
1265  */
1266
1267 /* Security plugins get their configuration information through a callback
1268  * with the signature:
1269  *   char *callback(char *key, void *userpointer);
1270  * where key is the name of the desired parameter, which may not match the
1271  * name used in this module.  See the implementations of these functions
1272  * to learn which keys they support, or to add new keys.
1273  */
1274 char *generic_client_get_security_conf(char *, void *);
1275 char *generic_get_security_conf(char *, void *);
1276
1277 /* Dump the current configuration information to stdout, in a format
1278  * that can be re-read by this module.  The results will include any
1279  * command-line overwrites.
1280  *
1281  * This function only dumps the server configuration, and will fail on
1282  * clients.
1283  */
1284 void dump_configuration(void);
1285
1286 /* Return a sequence of strings giving the printable representation
1287  * of the given val_t.  If str_needs_quotes is true and each string is
1288  * prefixed by the relevant configuration keyword, these strings will
1289  * be parseable by this module, and will reproduce exactly the same
1290  * configuration value.  See the implementation of dump_configuration
1291  * for details.
1292  *
1293  * If str_needs_quotes is provided, a CONFTYPE_STR value will be returned with
1294  * quotes.
1295  *
1296  * The result is a NULL-terminated strv, which can be freed with g_strfreev or
1297  * joined with g_strjoinv.  Caller is responsible for freeing the memory.
1298  *
1299  * @param val: the value to analyze
1300  * @param str_needs_quotes: add quotes to CONFTYPE_STR values?
1301  * @returns: NULL-terminated string vector
1302  */
1303 char **val_t_display_strs(val_t *val, int str_needs_quotes);
1304
1305 /* Read a dumptype; this is used by this module as well as by diskfile.c to
1306  * read the disklist.  The two are carefully balanced in their parsing process.
1307  *
1308  * Nobody else should use this function.  Seriously.
1309  */
1310 dumptype_t *read_dumptype(char *name, FILE *from, char *fname, int *linenum);
1311
1312 /* Every call return a pointer to a string with an increasing number; this is
1313  * used by this module as well as by diskfile.c to read the disklist.
1314  *
1315  * Nobody else should use this function.  Seriously.
1316  *
1317  * @returns: a pointer to a static string.
1318  */
1319 char *anonymous_value(void);
1320
1321 /* Extend a relative filename with the current config_dir; if filename is already
1322  * absolute, this is equivalent to stralloc.
1323  *
1324  * @param filename: filename to extend
1325  * @returns: newly allocated filename
1326  */
1327 char *config_dir_relative(char *filename);
1328
1329 /* Convert from a symbol back to a name for logging and for dumping
1330  * config values
1331  *
1332  * @param taperalgo: the constant value
1333  * @returns: statically allocated string
1334  */
1335 char *taperalgo2str(taperalgo_t taperalgo);
1336
1337 /* Looks for a unit value like b, byte, bytes, bps, etc. Technically
1338  * the return value should never be < 1, but we return a signed value
1339  * to help mitigate bad C promotion semantics. Returns 0 on error.
1340  *
1341  * This is here in this module because it uses the numb_keytable.
1342  *
1343  * @param casestr: the unit string
1344  * @returns: the corresponding multiplier (e.g., 'M' => 1024*1024)
1345  */
1346 gint64 find_multiplier(char * casestr);
1347
1348 /* Compute the size needed in an ARGV to pass all properties
1349  *
1350  * @param proplist: The property list
1351  * @returns: The size required for an ARGV
1352  */
1353 int property_argv_size(proplist_t proplist);
1354
1355 /* Add all properties to an ARGV
1356  *
1357  * @param argvchild: Pointer to the ARGV.
1358  * @param proplist: The property list
1359  */
1360 int property_add_to_argv(char **argvchild, proplist_t proplist);
1361
1362 #endif /* ! CONFFILE_H */