src/budb/budb.rg

   1 /*
   2  * Copyright 2000, International Business Machines Corporation and others.
   3  * All Rights Reserved.
   4  *
   5  * This software has been released under the terms of the IBM Public
   6  * License.  For details, see the LICENSE file in the top-level source
   7  * directory or online at http://www.openafs.org/dl/license10.html
   8  */
   9
  10 /* The backup database interface. */
  11 /* PA - these should not be defined here - import from bubasics */
  12 #define BU_MAXNAMELEN    32             /* names of objects: volumes */
  13 #define BU_MAXTAPELEN    32             /* names of objects: tapes */
  14 #define BU_MAXHOSTLEN    32             /* names of server machines */
  15 #define BU_MAXTOKENLEN   16             /* identifiers */
  16 #define BU_MAXUNAMELEN  256             /* length of user name */
  17 #define BU_MAXINAMELEN  128             /* length of user name */
  18 #define BU_MAXCELLLEN   256             /* length of a cell name */
  19 #define BU_MAXPATHLEN   256             /* length of schedule path name */
  20
  21 /* then some type definitions */
  22
  23 %#ifndef NEVERDATE
  24 %#define NEVERDATE 037777777777         /* a date that will never come */
  25 %#endif
  26 %#ifndef Date
  27 %#define Date afs_uint32
  28 %#endif
  29 #define Date afs_uint32
  30
  31 /* first some constants */
  32
  33 /* Bumped from 1 to 2 for changing nFrags in budb_VolumeEntry to tapeSeq */
  34 const BUDB_MAJORVERSION = 2;            /* version number of this interface */
  35
  36 /* then some type definitions */
  37
  38 %#ifndef dumpId
  39 %#define dumpId Date
  40 %#endif
  41 #define dumpId Date
  42
  43 /* types of text blocks */
  44 %#define        TB_DUMPSCHEDULE 0
  45 %#define        TB_VOLUMESET    1
  46 %#define        TB_TAPEHOSTS    2
  47
  48 %#define        TB_NUM          3       /* no. of block types */
  49 %#define        TB_MAX          6       /* unused items are spares */
  50
  51 /* TB_NUM must be <= TB_MAX */
  52
  53 struct budb_principal { /* identifies a principal identity */
  54     char name[BU_MAXUNAMELEN];
  55     char instance[BU_MAXINAMELEN];
  56     char cell[BU_MAXCELLLEN];
  57 };
  58
  59 struct budb_tapeSet { /* describes a tape sequence */
  60     afs_int32  id;                              /* id of tapeSet, assigned by budb */
  61     char  tapeServer[BU_MAXHOSTLEN];    /* name of server where this tape is (used by ADSM buta) */
  62     char  format[BU_MAXTAPELEN];        /* for  printf to make tape name */
  63     /* Sequence numbers are assumed to be relatively small and relatively
  64      * densely packed in 0<=seq<maxTapes. */
  65     afs_int32  maxTapes;                        /* maximum number of tapes in seq. */
  66     afs_int32  a; afs_int32 b;                  /* linear transforms for tape */
  67 };
  68   /* "function" that makes a tape name from a tapeSet and a sequence number.
  69      The resulting string must be less than BU_MAXTAPELEN. */
  70 %#define budb_MakeTapeName(name,set,seq) sprintf (name, (set)->format, (set)->a*(seq) + (set)->b)
  71
  72 struct budb_dumpEntry { /* describes a dump */
  73     dumpId id;                          /* identifier of this dump */
  74     dumpId parent;                      /* parent dump */
  75     afs_int32  level;                   /* level in multi-level incremental */
  76     afs_int32  flags;                   /* various bits described below */
  77     char  volumeSetName[BU_MAXNAMELEN]; /* volume set */
  78     char  dumpPath[BU_MAXPATHLEN];      /* full path of dump sched. node */
  79     char  name[BU_MAXNAMELEN];          /* volset.dump */
  80     Date  created;                      /* creation date of dump */
  81     Date  incTime;                      /* time for incrementals, 0 => full */
  82     afs_int32 nVolumes;                 /* number of vol fragments in dump */
  83     struct budb_tapeSet tapes;          /* tapes containing dump */
  84     struct budb_principal dumper;       /* name of person running doing dump */
  85     dumpId initialDumpID;               /* The dumpid of the initisl dump (for appended dumps) */
  86     dumpId appendedDumpID;              /* ID of the appended dump */
  87 };
  88 /* dump flag bit definitions */
  89 %#define BUDB_DUMP_INCOMPLETE (1<<0)    /* some vols omitted due to errors */
  90 %#define BUDB_DUMP_TAPEERROR  (1<<1)    /* tape error during dump */
  91 %#define BUDB_DUMP_INPROGRESS (1<<2)
  92 %#define BUDB_DUMP_ABORTED    (1<<3)    /* aborted: prob. dump unavailable */
  93 %#define BUDB_DUMP_XBSA_NSS   (1<<8)    /* dump was done with a client    */
  94                                         /* that doesn't support switching */
  95                                         /* of servers                     */
  96 %#define BUDB_DUMP_BUTA       (1<<11)   /* (used by ADSM buta) == 0x800 */
  97 %#define BUDB_DUMP_ADSM       (1<<12)   /* (used by XBSA/ADSM buta) == 0x1000 */
  98
  99
 100 struct budb_tapeEntry { /* describes a tape */
 101     char  name[BU_MAXTAPELEN];          /* identifies tape for humans */
 102     afs_int32  flags;                   /* various bits described below */
 103     Date  written;                      /* date tape was last written */
 104     Date  expires;                      /* expiration date */
 105     afs_uint32  nMBytes;                        /* number of Mbytes on tape */
 106     afs_uint32  nBytes;                 /* Megabyte remainder */
 107     afs_int32  nFiles;                  /* number of files on tape */
 108     afs_int32  nVolumes;                        /* number of vol fragments on tape */
 109     afs_int32  seq;                             /* sequence in tape set */
 110
 111     afs_int32  labelpos;                        /* position of tape label */
 112     afs_int32  useCount;                        /* # of times used */
 113     afs_int32  useKBytes;                    /* How much of tape is used (in KBytes) */
 114
 115     dumpId dump;                        /* dump on tape (set) */
 116 };
 117 /* tape flag bit definitions */
 118 %#define BUDB_TAPE_TAPEERROR    (1<<0)
 119 %#define BUDB_TAPE_DELETED      (1<<1)
 120 %#define BUDB_TAPE_BEINGWRITTEN (1<<2)  /* writing in progress */
 121 %#define BUDB_TAPE_ABORTED      (1<<3)  /* aborted: tape probably garbaged */
 122 %#define BUDB_TAPE_STAGED       (1<<4)  /* not yet on permanent media */
 123 %#define BUDB_TAPE_WRITTEN      (1<<5)  /* tape writing finished: all OK */
 124
 125 /* notes:
 126  *    The following fields can be considered spares.
 127  *      incTime is not used.
 128  *      startByte also appears to be effectively unused.
 129  */
 130
 131 struct budb_volumeEntry { /* describes a fragment of a volume */
 132
 133     /* volume information */
 134     char  name[BU_MAXNAMELEN];          /* unique name of volume */
 135     afs_int32  flags;                   /* various bits described below */
 136     afs_int32  id;                              /* volume uid */
 137     char  server[BU_MAXHOSTLEN];        /* server supporting volume */
 138     afs_int32  partition;                       /* partition on server */
 139     afs_int32  tapeSeq;                 /* Tape sequence number in this dump-set */
 140
 141     /* per fragment */
 142     afs_int32  position;                        /* position on tape */
 143     Date  clone;                        /* time volume was cloned for dump */
 144     Date  incTime;                      /* NOT USED */
 145     afs_int32  startByte;                       /* first byte of volume in this frag */
 146     afs_uint32  nBytes;         /* number of bytes in this frag */
 147     afs_int32   seq;                            /* sequence of frag in volume */
 148
 149     /* additional location info */
 150     dumpId dump;                        /* dump volume is part of */
 151     char  tape[BU_MAXTAPELEN];          /* tape containing this fragment */
 152 };
 153
 154 /* volume flag bit definitions */
 155 %#define BUDB_VOL_TAPEERROR    (1<<0)   /* tape problem during dump */
 156 %#define BUDB_VOL_FILEERROR    (1<<1)   /* voldump aborted during dump */
 157 %#define BUDB_VOL_BEINGWRITTEN (1<<2)
 158 %#define BUDB_VOL_FIRSTFRAG    (1<<3)   /* same as low bits of tape position */
 159 %#define BUDB_VOL_LASTFRAG     (1<<4)
 160 %#define BUDB_VOL_ABORTED      (1<<5)   /* aborted: vol probably undumped */
 161
 162 /* procedure interface */
 163
 164 package BUDB_
 165 prefix S
 166 statindex 17
 167
 168 /* All these procedures take a connection parameter since they may contact the
 169    database via RPC. */
 170
 171 /* To facilitate returning large large amounts of data some of these procedures
 172    expect to receive a pointer to an array of structures.  The majorVersion
 173    number implicitly specifies the size of each array element.  The progress
 174    parameter is set to the number of elements actually returned.  Since the
 175    caller may have limited buffer space, provisions are made to get the data in
 176    a series of calls.  The index parameter specifies starting point of a
 177    continued operation: for the first call it will be zero, a negative number
 178    will produce an error.  If more elements are available on a subsequent call
 179    nextIndex is set to the index of the next element.  Otherwise nextIndex is
 180    set to a negative number. */
 181
 182 /* The flag bits specify which entries are being requested.  They are search
 183    operations that use name, start, and end to select a subset of entries to be
 184    returned.  Not all combinations are meaning full or supported. */
 185
 186 /* These are NOT flags. These are values. PA */
 187
 188 %#define BUDB_OP_NAMES      (0x7)
 189 %#define BUDB_OP_STARTS     (0x7<<3)
 190 %#define BUDB_OP_ENDS       (0x7<<6)
 191 %#define BUDB_OP_TIMES      (0x3<<9)
 192 %#define BUDB_OP_MISC       (0xff<<16)
 193
 194 /* defining the meaning of "name" */
 195 %#define BUDB_OP_DUMPNAME   (1<<0)
 196 %#define BUDB_OP_VOLUMENAME (2<<0)
 197 %#define BUDB_OP_TAPENAME   (3<<0)
 198 %#define BUDB_OP_TAPESEQ    (4<<0)
 199
 200 /* "start" is a time value */
 201 %#define BUDB_OP_STARTTIME  (1<<3)
 202   /* "end" delimits a range of times */
 203 %#define BUDB_OP_RANGE      (1<<6)
 204   /* "end" specifies number of earlier entries */
 205 %#define BUDB_OP_NPREVIOUS  (2<<6)
 206   /* "end" specifies number of later entries */
 207 %#define BUDB_OP_NFOLLOWING (3<<6)
 208 /* start is dump id (name may be null), return all entries */
 209 %#define BUDB_OP_DUMPID     (2<<3)
 210
 211 /* defining the which type of time values */
 212 %#define BUDB_OP_CLONETIME  (1<<9)      /* use clone time */
 213 %#define BUDB_OP_DUMPTIME   (2<<9)      /* use dump time (create?) */
 214 %#define BUDB_OP_INCTIME    (3<<9)      /* use inc time */
 215
 216 /* Miscellaneous bits: */
 217   /* for volumes: return only first fragment */
 218 %#define BUDB_OP_FIRSTFRAG  (1<<16)
 219
 220 /* maximum number of elements returnable by these functions */
 221 const BUDB_MAX_RETURN_LIST = 1000;
 222
 223 typedef struct budb_volumeEntry budb_volumeList<BUDB_MAX_RETURN_LIST>;
 224 typedef struct budb_dumpEntry budb_dumpList<BUDB_MAX_RETURN_LIST>;
 225 typedef struct budb_tapeEntry budb_tapeList<BUDB_MAX_RETURN_LIST>;
 226 typedef afs_int32                  budb_dumpsList<BUDB_MAX_RETURN_LIST>;
 227 typedef char charListT<>;
 228
 229 %#define BUDB_TEXT_COMPLETE     1
 230
 231 /* structures for database dump generation and interpretation */
 232
 233 /* structure types */
 234 %#define        SD_DBHEADER             1
 235 %#define        SD_DUMP                 2
 236 %#define        SD_TAPE                 3
 237 %#define        SD_VOLUME               4
 238 %#define        SD_TEXT_DUMPSCHEDULE    5
 239 %#define        SD_TEXT_VOLUMESET       6
 240 %#define        SD_TEXT_TAPEHOSTS       7
 241 %#define        SD_END                  8
 242
 243 /* ListDumps in flags */
 244 %#define        BUDB_OP_DATES           (0x01)
 245 %#define        BUDB_OP_GROUPID         (0x02)
 246 /* ListDumps out flags */
 247 %#define        BUDB_OP_APPDUMP         (0x01)
 248 %#define        BUDB_OP_DBDUMP          (0x02)
 249
 250 /* database header - minimal version that is dumped. Allows values of important
 251  *      state variables to be saved/restored.
 252  */
 253
 254 struct DbHeader
 255 {
 256     afs_int32 dbversion;                        /* database version */
 257     afs_int32 created;                  /* creation time */
 258     char cell[BU_MAXCELLLEN];           /* whose database */
 259     dumpId lastDumpId;                  /* last dump id generated */
 260     afs_uint32 lastInstanceId;          /* last lock instance */
 261     afs_uint32 lastTapeId;                      /* last tape id */
 262 };
 263
 264 /* header prefix for each structure. Identifies the structure following */
 265 struct structDumpHeader
 266 {
 267      afs_int32 type;                    /* structure type */
 268      afs_int32 structversion;   /* version of following structure */
 269      afs_int32 size;                    /* size in bytes of following structure */
 270 };
 271
 272 /* General Interface routines - alphabetic order */
 273
 274 /* This adds a volume to particular dump and tape.  It is called after the
 275    volume has been written to tape and allows the database to attach the volume
 276    information to the structures for its containing dump and tape.  The
 277    description of the volume must be specified on input, including the vldb
 278    information, incTime, and a description of the volume's fragmention. */
 279
 280 AddVolume
 281  (INOUT struct budb_volumeEntry *vol);
 282
 283 /* This creates a new dump.  On input the dumpEntry specifies the containing
 284    tape set, the dump name, the incTime, and the identity of the dumper.  On
 285    output the dump's id is set. */
 286
 287 CreateDump
 288  (INOUT struct budb_dumpEntry *dump);
 289
 290 DeleteDump (IN dumpId id,               /* the dump ids to delete */
 291             IN Date   fromTime,         /* time to delete dump from */
 292             IN Date   toTime,           /* time to delete dumps to */
 293             INOUT budb_dumpsList *dumps);/* List of dumps deleted */
 294
 295 /* This is called, probably infrequently, to remove a tape from the database.
 296    The assumption is that sometimes tapes are retired or lost and this routine
 297    facilitates cleaning up the database. */
 298
 299 DeleteTape
 300  (IN struct budb_tapeEntry *tape);      /* tape info */
 301
 302 DeleteVDP
 303  ( IN string dsname<BU_MAXNAMELEN>,     /* dump name */
 304    IN string dumpPath<BU_MAXPATHLEN>,   /* dump node path name */
 305    IN afs_int32 curDumpId);                     /* current dump Id for exclusion */
 306
 307 FindClone
 308  ( IN afs_int32 dumpID,                 /* id of dump to start with */
 309    IN string volName<BU_MAXNAMELEN>,    /* clone time required for volName */
 310 INOUT afs_int32  *clonetime);           /* returned clone time */
 311
 312 FindDump
 313  ( IN string volumeName<BU_MAXNAMELEN>, /* name of volume to look for */
 314    IN afs_int32 beforeDate,                     /* must be before this date */
 315 INOUT struct budb_dumpEntry *deptr);    /* returned dump information */
 316
 317 FindLatestDump
 318  (IN  string vsname<BU_MAXNAMELEN>,   /* name of volumeset to look for */
 319   IN  string dname<BU_MAXPATHLEN>,    /* name of dump to look for */
 320   OUT budb_dumpEntry *dumpentry);
 321
 322 MakeDumpAppended
 323  (IN  afs_int32 appendedDumpID,            /* Append this dump to .... */
 324   IN  afs_int32 intialDumpID,              /* ... this initial dump */
 325   IN  afs_int32 startTapeSeq);             /* Tape sequence the dump starts at */
 326
 327 FindLastTape
 328  (IN  afs_int32 dumpID,                        /* id of dump to */
 329   OUT struct budb_dumpEntry   *dumpEntry, /* Dump   information to return */
 330   OUT struct budb_tapeEntry   *tapeEntry, /* Tape   information to return */
 331   OUT struct budb_volumeEntry *volEntry); /* Volume information to return */
 332
 333 /* This notifies the database that the dump is finished.  Some status bits can
 334    be specified on input. */
 335
 336 FinishDump
 337  (INOUT struct budb_dumpEntry *dump);
 338
 339 /* This is called when writing to the tape has been completed.  The tapeEntry
 340    includes some status bits on input, such as whether any tape errors were
 341    encountered.  Volumes and dumps on the tape are marked as safe if the status
 342    was good. */
 343
 344 FinishTape
 345  (INOUT struct budb_tapeEntry *tape);
 346
 347 GetDumps
 348  (IN  afs_int32  majorVersion,          /* version of interface structures */
 349   IN  afs_int32  flags,                 /* search & select controls */
 350   IN  string name<BU_MAXNAMELEN>,       /* s&s parameters */
 351   IN  afs_int32  start,
 352   IN  afs_int32  end,
 353   IN  afs_int32  index,                 /* start index of returned entries */
 354   OUT afs_int32 *nextIndex,                     /* output index for next call */
 355   OUT afs_int32 *dbUpdate,                      /* time of last db change */
 356   INOUT budb_dumpList *dumps);          /* structure list */
 357
 358 GetTapes
 359  (IN  afs_int32  majorVersion,          /* version of interface structures */
 360   IN  afs_int32  flags,                 /* search & select controls */
 361   IN  string name<BU_MAXNAMELEN>,       /* s&s parameters */
 362   IN  afs_int32  start,
 363   IN  afs_int32  end,                   /* reserved: MBZ */
 364   IN  afs_int32  index,                 /* start index of returned entries */
 365   OUT afs_int32 *nextIndex,                     /* output index for next call */
 366   OUT afs_int32 *dbUpdate,                      /* time of last db change */
 367   INOUT struct budb_tapeList *tapes);   /* structure list */
 368
 369 GetVolumes
 370  (IN  afs_int32  majorVersion,          /* version of interface structures */
 371   IN  afs_int32  flags,                 /* search & select controls */
 372   IN  string name<BU_MAXNAMELEN>,       /*  - parameters for search */
 373   IN  afs_int32  start,                 /*  - usage depends which BUDP_OP_* */
 374   IN  afs_int32  end,                   /*  - bits are set */
 375   IN  afs_int32  index,                 /* start index of returned entries */
 376   OUT afs_int32 *nextIndex,                     /* output index for next call */
 377   OUT afs_int32 *dbUpdate,                      /* time of last db change */
 378   INOUT budb_volumeList *volumes);      /* structure list */
 379
 380 /* Called when a tape is about to be used.  It deletes from the database the
 381    previous contents of the tape, if any, and marks it as "being written".  The
 382    tapeEntry identifies the tape name and dump on input.  The updated entry is
 383    returned on output. */
 384
 385 UseTape
 386  (INOUT struct budb_tapeEntry *tape,    /* tape info */
 387   OUT afs_int32 *new);                  /* set if tape is new */
 388
 389 /* text file management calls - alphabetic */
 390
 391 GetText
 392  (  IN  afs_uint32 lockHandle,
 393     IN  afs_int32 textType,                     /* which type of text */
 394     IN  afs_int32 maxLength,
 395     IN  afs_int32 offset,
 396     OUT afs_int32 *nextOffset,
 397     OUT charListT *charListPtr);
 398
 399 GetTextVersion
 400  (  IN afs_int32 textType,
 401    OUT afs_uint32 *tversion);
 402
 403 SaveText
 404  (  IN  afs_uint32 lockHandle,          /* which type of text */
 405     IN  afs_int32 textType,                     /* which type of text */
 406     IN  afs_int32 offset,                       /* offset into text block */
 407     IN  afs_int32 flags,
 408     IN  charListT *charListPtr);                /* text */
 409
 410 /* Lock management interface routines */
 411
 412 FreeAllLocks
 413  (  IN afs_uint32 instanceId );         /* identifies user */
 414
 415 FreeLock
 416  (  IN afs_uint32 lockHandle);          /* identifies lock */
 417
 418 GetInstanceId
 419  (  OUT afs_uint32 *instanceId );       /* instance of a user */
 420
 421 GetLock
 422  (  IN  afs_uint32 instanceId,          /* instance of user */
 423     IN  afs_int32 lockName,                     /* which lock */
 424     IN  afs_int32 expiration,           /* # secs after which lock released */
 425     OUT afs_uint32 *lockHandle);                /* returned lock handle */
 426
 427 /* database dump and reconstruction */
 428
 429 DbVerify
 430  (  OUT afs_int32 *status,                      /* 0=ok, 1=inconsistent */
 431     OUT afs_int32 *orphans,                     /* orphan block count */
 432     OUT afs_int32 *host                 /* host where checks done */
 433  );
 434
 435 DumpDB
 436  (  IN  int  firstcall,                 /* First call requesting data */
 437     IN  afs_int32 maxLength,                    /* max transfer size */
 438     OUT charListT *charListPtr,         /* byte stream out */
 439     OUT afs_int32       *flags );               /* status flags */
 440
 441 RestoreDbHeader
 442  (  IN  struct DbHeader *header );      /* restore database header */
 443
 444 /* Debug and test interface routines
 445  *
 446  * These routines provide a low level interface that can be used to test out
 447  * the backup database.
 448  */
 449
 450 T_GetVersion(OUT afs_int32 *majorVersion);
 451
 452 T_DumpHashTable (IN afs_int32 type, IN string filename<32>);
 453
 454 T_DumpDatabase (IN string filename<32>);
 455
 456 /* This adds a list of volumes to particular dump and tape.  It is
 457  * called after the volume has been written to tape and allows the
 458  * database to attach the volume information to the structures for its
 459  * containing dump and tape.  The description of the volume must be
 460  * specified on input, including the vldb information, incTime, and a
 461  * description of the volume's fragmention.
 462  */
 463 AddVolumes
 464  (IN struct budb_volumeList *vols);
 465
 466 ListDumps (IN afs_int32 sflags,           /* search flags */
 467            IN string    name<BU_MAXPATHLEN>, /* unused (reserved) */
 468            IN afs_int32 group,            /* group Id */
 469            IN Date      fromTime,         /* time to delete dump from */
 470            IN Date      toTime,           /* time to delete dumps to */
 471            INOUT budb_dumpsList *dumps,   /* List of dumps */
 472            INOUT budb_dumpsList *flags);  /* parallel flag for each dump */