budb: Only have one build rule for budb_errs.c
[openafs.git] / 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 */