source: gpfs_3.1_ker2.6.20/lpp/mmfs/include/gpfs.h @ 91

Last change on this file since 91 was 16, checked in by rock, 17 years ago
File size: 52.3 KB
Line 
1/* IBM_PROLOG_BEGIN_TAG                                                   */
2/* This is an automatically generated prolog.                             */
3/*                                                                        */
4/*                                                                        */
5/*                                                                        */
6/* Licensed Materials - Property of IBM                                   */
7/*                                                                        */
8/* (C) COPYRIGHT International Business Machines Corp. 1998,2007          */
9/* All Rights Reserved                                                    */
10/*                                                                        */
11/* US Government Users Restricted Rights - Use, duplication or            */
12/* disclosure restricted by GSA ADP Schedule Contract with IBM Corp.      */
13/*                                                                        */
14/* IBM_PROLOG_END_TAG                                                     */
15/* @(#)42 1.1.5.1  src/avs/fs/mmfs/ts/util/gpfs.h, mmfs, avs_rgpfs24, rgpfs24s011a 3/13/07 10:16:05 */
16/*
17 *  Library calls for GPFS interfaces
18 */
19#ifndef H_GPFS
20#define H_GPFS
21
22#ifdef __cplusplus
23extern "C" {
24#endif
25
26#include <sys/types.h>
27#include <sys/stat.h>
28
29/* Define maximum length of the name for a GPFS named object, such
30   as a snapshot, storage pool or fileset. The name is a null-terminated
31   character string, which is not include in the max length */
32#define GPFS_MAXNAMLEN       255
33
34/* Define maximum length of the path to a GPFS named object
35   such as a snapshot or fileset. If the absolute path name exceeds
36   this limit, then use a relative path name. The path is a null-terminated
37   character string, which is not included in the max length */
38#define GPFS_MAXPATHLEN     1023
39
40/* ASCII code for "GPFS" in the struct statfs f_type field */
41#define GPFS_SUPER_MAGIC     0x47504653
42
43/* GPFS inode attributes */
44typedef unsigned int gpfs_mode_t;
45typedef unsigned int gpfs_uid_t;
46typedef unsigned int gpfs_gid_t;
47typedef unsigned int gpfs_ino_t;
48typedef unsigned int gpfs_gen_t;
49typedef unsigned int gpfs_dev_t;
50typedef unsigned int gpfs_mask_t;
51typedef unsigned int gpfs_pool_t;
52typedef long long gpfs_off64_t;
53typedef struct stat64 stat64_t;
54
55/* open source interfaces */
56#include <gpfs_gpl.h>
57
58typedef struct gpfs_timestruc
59{
60  unsigned int tv_sec;
61  unsigned int tv_nsec;
62} gpfs_timestruc_t;
63
64
65/* Define a version number for the directory entry data to allow
66   future changes in this structure. Careful callers should also use
67   the d_reclen field for the size of the structure rather than sizeof,
68   to allow some degree of forward compatibility */
69#define GPFS_D_VERSION 1
70
71typedef struct gpfs_direntx
72{
73  int            d_version;     /* this struct's version */
74  unsigned short d_reclen;      /* actual size of this struct including
75                                   null terminated variable length d_name */
76  unsigned short d_type;        /* Types are defined below */
77  gpfs_ino_t     d_ino;         /* File inode number */
78  gpfs_gen_t     d_gen;         /* Generation number for the inode */
79  char           d_name[256];   /* null terminated variable length name */
80} gpfs_direntx_t;
81
82/* File types for d_type field in gpfs_direntx_t */
83#define GPFS_DE_OTHER    0
84#define GPFS_DE_DIR      4
85#define GPFS_DE_REG      8
86#define GPFS_DE_LNK     10
87
88
89/* Define a version number for the iattr data to allow future changes
90   in this structure. Careful callers should also use the ia_reclen field
91   for the size of the structure rather than sizeof, to allow some degree
92   of forward compatibility */
93#define GPFS_IA_VERSION 1
94
95typedef struct gpfs_iattr
96{
97  int              ia_version;    /* this struct version */
98  int              ia_reclen;     /* sizeof this structure */
99  int              ia_checksum;   /* validity check on iattr struct */
100  gpfs_mode_t      ia_mode;       /* access mode */
101  gpfs_uid_t       ia_uid;        /* owner uid */
102  gpfs_gid_t       ia_gid;        /* owner gid */
103  gpfs_ino_t       ia_inode;      /* file inode number */
104  gpfs_gen_t       ia_gen;        /* inode generation number */
105  short            ia_nlink;      /* number of links */
106  short            ia_flags;      /* Flags (defined below) */
107  int              ia_blocksize;  /* preferred block size for io */
108  gpfs_mask_t      ia_mask;       /* Initial attribute mask (not used) */
109  gpfs_off64_t     ia_size;       /* file size in bytes */
110  gpfs_off64_t     ia_blocks;     /* 512 byte blocks of disk held by file */
111  gpfs_timestruc_t ia_atime;      /* time of last access */
112  gpfs_timestruc_t ia_mtime;      /* time of last data modification */
113  gpfs_timestruc_t ia_ctime;      /* time of last status change */
114  gpfs_dev_t       ia_rdev;       /* id of device */
115  unsigned int     ia_xperm;      /* extended attributes (defined below) */
116  int              ia_modsnapid;
117  unsigned int     ia_filesetid;  /* fileset ID */
118  unsigned int     ia_datapoolid; /* storage pool ID for data */
119} gpfs_iattr_t;
120
121/* Define flags for inode attributes */
122#define GPFS_IAFLAG_SNAPDIR        0x0001 /* (obsolete) */
123#define GPFS_IAFLAG_USRQUOTA       0x0002 /* inode is a user quota file */
124#define GPFS_IAFLAG_GRPQUOTA       0x0004 /* inode is a group quota file */
125#define GPFS_IAFLAG_ERROR          0x0008 /* error reading inode */
126/* Define flags for inode replication attributes */
127#define GPFS_IAFLAG_FILESET_ROOT   0x0010 /* root dir of a fileset */
128#define GPFS_IAFLAG_NO_SNAP_RESTORE 0x0020 /* don't restore from snapshots */
129#define GPFS_IAFLAG_FILESETQUOTA   0x0040 /* inode is a fileset quota file */
130#define GPFS_IAFLAG_COMANAGED      0x0080 /* file data is co-managed */
131#define GPFS_IAFLAG_ILLPLACED      0x0100 /* may not be properly placed */
132#define GPFS_IAFLAG_REPLMETA       0x0200 /* metadata replication set */
133#define GPFS_IAFLAG_REPLDATA       0x0400 /* data replication set */
134#define GPFS_IAFLAG_EXPOSED        0x0800 /* may have data on suspended disks */
135#define GPFS_IAFLAG_ILLREPLICATED  0x1000 /* may not be properly replicated */
136#define GPFS_IAFLAG_UNBALANCED     0x2000 /* may not be properly balanced */
137#define GPFS_IAFLAG_DATAUPDATEMISS 0x4000 /* has stale data blocks on
138                                             unavailable disk */
139#define GPFS_IAFLAG_METAUPDATEMISS 0x8000 /* has stale metadata on
140                                             unavailable disk */
141/* Define flags for extended attributes */
142#define GPFS_IAXPERM_ACL           0x0001 /* file has acls */
143#define GPFS_IAXPERM_XATTR         0x0002 /* file has extended attributes */
144#define GPFS_IAXPERM_DMATTR        0x0004 /* file has dm attributes */
145#define GPFS_IAXPERM_DOSATTR       0x0008 /* file has non-default dos attrs */
146#define GPFS_IAXPERM_RPATTR        0x0010 /* file has restore policy attrs */
147
148
149
150/* Define pointers to interface types */
151typedef struct gpfs_fssnap_handle gpfs_fssnap_handle_t;
152typedef struct gpfs_iscan gpfs_iscan_t;
153typedef struct gpfs_ifile gpfs_ifile_t;
154typedef struct gpfs_restore gpfs_restore_t;
155
156typedef struct gpfs_fssnap_id
157{
158  char opaque[48];
159} gpfs_fssnap_id_t;
160
161
162/* Define extended return codes for gpfs backup & restore
163   calls without an explicit return code will return the value in errno */
164#define GPFS_ERRNO_BASE  190
165#define GPFS_E_INVAL_FSSNAPID  (GPFS_ERRNO_BASE+0) /* invalid fssnap id */
166#define GPFS_E_INVAL_ISCAN   (GPFS_ERRNO_BASE+1) /* invalid iscan pointer */
167#define GPFS_E_INVAL_IFILE   (GPFS_ERRNO_BASE+2) /* invalid ifile pointer */
168#define GPFS_E_INVAL_IATTR   (GPFS_ERRNO_BASE+3) /* invalid iattr structure */
169#define GPFS_E_INVAL_RESTORE (GPFS_ERRNO_BASE+4) /* invalid restore pointer */
170#define GPFS_E_INVAL_FSSNAPHANDLE (GPFS_ERRNO_BASE+5) /* invalid fssnap handle */
171#define GPFS_E_INVAL_SNAPNAME (GPFS_ERRNO_BASE+6) /* invalid snapshot name */
172#define GPFS_E_FS_NOT_RESTORABLE   (GPFS_ERRNO_BASE+7) /* FS is not clean */
173#define GPFS_E_RESTORE_NOT_ENABLED (GPFS_ERRNO_BASE+8) /* Restore was not enabled */
174#define GPFS_E_RESTORE_STARTED     (GPFS_ERRNO_BASE+9) /* Restore is running */
175
176/* Define flags parameter for get/put file attributes.
177   Used by gpfs_fgetattr, gpfs_fputattr, gpfs_fputattrwithpath
178   and gpfs_iputattrwithpath
179*/
180#define GPFS_ATTRFLAG_DEFAULT       0 /* default behavior */
181#define GPFS_ATTRFLAG_NO_PLACEMENT  1 /* exclude file placement attributes */
182
183
184/* Define structure used by gpfs_statfspool */
185typedef struct gpfs_statfspool_s
186{
187  gpfs_off64_t f_blocks;     /* total data blocks in pool */
188  gpfs_off64_t f_bfree;      /* free blocks in pool */
189  gpfs_off64_t f_bavail;     /* free blocks avail to non-superuser */
190  gpfs_off64_t f_mblocks;    /* total metadata blocks in pool */
191  gpfs_off64_t f_mfree;      /* free blocks avail for system metadata */
192  int          f_bsize;      /* optimal storage pool block size */
193  int          f_files;      /* total file nodes assigned to pool */
194  gpfs_pool_t  f_poolid;     /* storage pool id */
195  int          f_fsize;      /* fundamental file system block size */
196  unsigned int f_usage;      /* data and/or metadata stored in pool */
197  int          f_reserved[7];/* Current unused and set to  zero */
198} gpfs_statfspool_t;
199
200#define STATFSPOOL_USAGE_DATA      0x0001 /* Pool stores user data */
201#define STATFSPOOL_USAGE_METADATA  0x0002 /* Pool stores system metadata */
202
203
204
205
206/* NAME:        gpfs_fstat(), gpfs_stat()
207 *
208 * FUNCTION:    Get exact stat information for a file descriptor (or filename).
209 *              Forces all other nodes to flush dirty data and metadata to disk.
210 * Returns:      0      Successful
211 *              -1      Failure
212 *
213 * Errno:       ENOSYS  function not available
214 *              EBADF   Bad file desc
215 *              EINVAL  Not a GPFS file
216 */
217int 
218gpfs_fstat(int fileDesc,
219           stat64_t *buffer);
220
221int 
222gpfs_stat(char *pathname, /* File pathname */
223          stat64_t *buffer);
224
225
226/* NAME:        gpfs_fgetattrs()
227 *
228 * FUNCTION:    Retrieves all extended file attributes in opaque format.
229 *              This function together with gpfs_fputattrs is intended for
230 *              use by a backup program to save (gpfs_fgetattrs) and
231 *              restore (gpfs_fputattrs) all extended file attributes
232 *              (ACLs, dmapi attributes, ...) in one call.
233 *
234 * Input:       flags   Define behavior of get attributes
235 *                      See flag definition above.
236 *
237 * Returns:      0      Successful
238 *              -1      Failure
239 *
240 * Errno:       ENOSYS  function not available
241 *              ENOSPC  buffer too small to return all attributes
242 *                      *attrSizeP will be set to the size necessary
243 */
244int 
245gpfs_fgetattrs(int fileDesc,
246               int flags,
247               void *buffer,
248               int bufferSize,
249               int *attrSize);
250
251
252/* NAME:        gpfs_fputattrs()
253 *
254 * FUNCTION:    Sets all extended file attributes of a file
255 *              and sets the file's storage pool and data replication
256 *              to the values saved in the extended attributes.
257 *              The buffer passed in should contain extended attribute data
258 *              that was obtained by a previous call to gpfs_fgetattrs.
259 *
260 * Input:       flags   Define behavior of put attributes
261 *                      See flag definition above.
262 *
263 * Returns:      0      Successful
264 *              -1      Failure
265 *
266 * Errno:       ENOSYS  function not available
267 *              EINVAL  the buffer does not contain valid attribute data
268 */
269int 
270gpfs_fputattrs(int fileDesc,
271               int flags,
272               void *buffer);
273
274
275/* NAME:        gpfs_fputattrswithpathname()
276 *
277 * FUNCTION:    Sets all extended file attributes of a file and
278 *              invokes the policy engine using the file's attributes
279 *              saved in the extended attributes to set the file's
280 *              storage pool and data replication. The caller should
281 *              include the full path to the file, including the file name,
282 *              to allow rule selection based on file name or path.
283 *              The buffer passed in should contain extended attribute data
284 *              that was obtained by a previous call to gpfs_fgetattrs.
285 *              The flags parameter must be zero (reserved for future use).
286 *
287 * Input:       flags   Define behavior of put attributes
288 *                      See flag definition above.
289 *
290 * Returns:      0      Successful
291 *              -1      Failure
292 *
293 * Errno:       ENOSYS  function not available
294 *              EINVAL  the buffer does not contain valid attribute data
295 */
296int 
297gpfs_fputattrswithpathname(int fileDesc,
298                           int flags,
299                           void *buffer,
300                           const char *pathName);
301
302
303/* NAME:        gpfs_get_fssnaphandle_by_path()
304 *
305 * FUNCTION:    Get a volatile handle to uniquely identify a filesystem
306 *              and snapshot by the path to the file system and snapshot
307 *
308 * Input:       pathName: path to a file or directory in a gpfs file system
309 *                        or to one of its snapshots
310 *
311 * Returns:     pointer to gpfs_fssnap_handle_t (Successful)
312 *              NULL and errno is set (Failure)
313 *
314 * Errno:       ENOSYS function not available
315 *              ENOENT invalid pathname
316 *              see system calls open(), fstatfs(), and malloc() ERRORS
317 */
318gpfs_fssnap_handle_t *
319gpfs_get_fssnaphandle_by_path(const char *pathName);
320
321
322/* NAME:        gpfs_get_fssnaphandle_by_name()
323 *
324 * FUNCTION:    Get a volatile handle to uniquely identify a filesystem
325 *              and snapshot by the file system name and snapshot name.
326 *
327 * Input:       fsName: unique name for gpfs file system (may be specified
328 *                      as fsName or /dev/fsName)
329 *              snapName: name for snapshot within that file system
330 *                        or NULL to access the active file system rather
331 *                        than a snapshot within the file system.
332 *
333 * Returns:     pointer to gpfs_fssnap_handle_t (Successful)
334 *              NULL and errno is set (Failure)
335 *
336 * Errno:       ENOSYS function not available
337 *              ENOENT invalid file system name
338 *              GPFS_E_INVAL_SNAPNAME invalid snapshot name
339 *              see system calls open(), fstatfs(), and malloc() ERRORS
340 */
341gpfs_fssnap_handle_t *
342gpfs_get_fssnaphandle_by_name(const char *fsName, 
343                              const char *snapName);
344
345
346/* NAME:        gpfs_get_fssnaphandle_by_fssnapid()
347 *
348 * FUNCTION:    Get a volatile handle to uniquely identify a filesystem
349 *              and snapshot by a fssnapId created from a previous handle.
350 *
351 * Input:       fssnapId: unique id for a file system and snapshot
352 *
353 * Returns:     pointer to gpfs_fssnaphandle_t (Successful)
354 *              NULL and errno is set (Failure)
355 *
356 * Errno:       ENOSYS function not available
357 *              GPFS_E_INVAL_FSSNAPID invalid snapshot id
358 *              see system calls open(), fstatfs(), and malloc() ERRORS
359 */
360gpfs_fssnap_handle_t *
361gpfs_get_fssnaphandle_by_fssnapid(const gpfs_fssnap_id_t *fssnapId);
362
363
364/* NAME:        gpfs_get_pathname_from_fssnaphandle()
365 *
366 * FUNCTION:    Get the mountpoint and path to a file system
367 *              and snapshot identified by a fssnapHandle
368 *
369 * Input:       fssnapHandle: ptr to file system & snapshot handle
370 *
371 * Returns:     ptr to path name to the file system  (Successful)
372 *              NULL and errno is set (Failure)
373 *
374 * Errno:       ENOSYS function not available
375 *              GPFS_E_INVAL_FSSNAPHANDLE invalid fssnapHandle
376 */
377const char *
378gpfs_get_pathname_from_fssnaphandle(gpfs_fssnap_handle_t *fssnapHandle);
379
380
381/* NAME:        gpfs_get_fsname_from_fssnaphandle()
382 *
383 * FUNCTION:    Get the unique name for the file system
384 *              identified by a fssnapHandle
385 *
386 * Input:       fssnapHandle: ptr to file system & snapshot handle
387 *
388 * Returns:     ptr to name of the file system  (Successful)
389 *              NULL and errno is set (Failure)
390 *
391 * Errno:       ENOSYS function not available
392 *              GPFS_E_INVAL_FSSNAPHANDLE invalid fssnapHandle
393 */
394const char *
395gpfs_get_fsname_from_fssnaphandle(gpfs_fssnap_handle_t *fssnapHandle);
396
397
398/* NAME:        gpfs_get_snapname_from_fssnaphandle()
399 *
400 * FUNCTION:    Get the name for the snapshot
401 *              uniquely identified by a fssnapHandle
402 *
403 * Input:       fssnapHandle: ptr to file system & snapshot handle
404 *
405 * Returns:     ptr to name assigned to the snapshot (Successful)
406 *              NULL and errno is set (Failure)
407 *
408 * Errno:       ENOSYS function not available
409 *              GPFS_E_INVAL_FSSNAPHANDLE invalid fssnaphandle
410 *              GPFS_E_INVAL_SNAPNAME snapshot has been deleted
411 *
412 * Notes:       If the snapshot has been deleted from the file system
413 *              the snapId may still be valid, but the call will fail
414 *              with errno set to GPFS_E_INVAL_SNAPNAME.
415 */
416const char *
417gpfs_get_snapname_from_fssnaphandle(gpfs_fssnap_handle_t *fssnapHandle);
418
419
420/* NAME:        gpfs_get_fssnapid_from_fssnaphandle()
421 *
422 * FUNCTION:    Get a unique, non-volatile file system and snapshot id
423 *              for the file system and snapshot identified by a
424 *              volatile fssnap handle.
425 *
426 * Input:       fssnapHandle: ptr to file system & snapshot handle
427 *              fssnapId: returned fssnapId uniquely identifying the
428 *                        file system and snapshot being scanned
429 *
430 * Returns:     0 and fssnapId is set with id (Successful)
431 *              -1 and errno is set (Failure)
432 *
433 * Errno:       GPFS_E_INVAL_FSSNAPHANDLE invalid fssnaphandle
434 *              EINVAL null ptr given for returned fssnapId
435 *              EFAULT size mismatch for fssnapId
436 */
437int 
438gpfs_get_fssnapid_from_fssnaphandle(gpfs_fssnap_handle_t *fssnapHandle,
439                                    gpfs_fssnap_id_t *fssnapId);
440
441
442/* NAME:        gpfs_get_restore_fssnapid_from_fssnaphandle()
443 *
444 * FUNCTION:    Get the unique, non-volatile file system and snapshot id
445 *              used for the last complete restore of a mirrored file
446 *              system. The file system must been a previous restore
447 *              target and ready for additional incremental restore.
448 *
449 * Input:       fssnapHandle: ptr to file system & snapshot handle
450 *              fssnapId: returned fssnapId uniquely identifying the
451 *                        last complete restored file system.
452 *
453 * Returns:     0 and fssnapId is set with id (Successful)
454 *              -1 and errno is set (Failure)
455 *
456 * Errno:       GPFS_E_INVAL_FSSNAPHANDLE invalid fssnaphandle
457 *              EINVAL null ptr given for returned fssnapId
458 *              EFAULT size mismatch for fssnapId
459 *              EPERM caller must have superuser priviledges
460 *              ENOMEM unable to allocate memory for request
461 *              GPFS_E_FS_NOT_RESTORABLE fs is not clean for restore
462 */
463int 
464gpfs_get_restore_fssnapid_from_fssnaphandle(gpfs_fssnap_handle_t *fssnapHandle,
465                                            gpfs_fssnap_id_t *fssnapId);
466
467
468/* NAME:        gpfs_free_fssnaphandle()
469 *
470 * FUNCTION:    Free a fssnapHandle
471 *
472 * Input:       fssnapHandle: ptr to file system & snapshot handle
473 *
474 * Returns:     void
475 *
476 * Errno:       None
477 */
478void 
479gpfs_free_fssnaphandle(gpfs_fssnap_handle_t *fssnapHandle);
480
481
482/* NAME:        gpfs_get_snapdirname()
483 *
484 * FUNCTION:    Get the name of the directory containing snapshots.
485 *
486 * Input:       fssnapHandle: handle for the file system
487 *              snapdirName: buffer into which the name of the snapshot
488 *                directory will be copied
489 *              bufLen: the size of the provided buffer
490 *
491 * Returns:     0 (Successful)
492 *              -1 and errno is set (Failure)
493 *
494 * Errno:       ENOSYS function not available
495 *              EPERM caller must have superuser priviledges
496 *              ESTALE cached fs information was invalid
497 *              ENOMEM unable to allocate memory for request
498 *              GPFS_E_INVAL_FSSNAPHANDLE fssnapHandle is invalid
499 *              E2BIG buffer too small to return the snapshot directory name
500 */
501int
502gpfs_get_snapdirname(gpfs_fssnap_handle_t *fssnapHandle,
503                     char *snapdirName,
504                     int bufLen);
505
506
507/* NAME:        gpfs_open_inodescan()
508 *
509 * FUNCTION:    Open inode file for inode scan.
510 *
511 * Input:       fssnapHandle: handle for file system and snapshot
512 *                            to be scanned
513 *              prev_fssnapId: if NULL, all inodes of existing file will
514 *                be returned; if non-null, only returns inodes of files
515 *                that have changed since the specified previous snapshot
516 *              maxIno: if non-null, returns the maximum inode number
517 *                available in the inode file being scanned.
518 *
519 * Returns:     pointer to gpfs_iscan_t (Successful)
520 *              NULL and errno is set (Failure)
521 *
522 * Errno:       ENOSYS function not available
523 *              EINVAL bad parameters
524 *              EPERM caller must have superuser priviledges
525 *              ESTALE cached fs information was invalid
526 *              ENOMEM unable to allocate memory for request
527 *              GPFS_E_INVAL_FSSNAPHANDLE fssnapHandle is invalid
528 *              GPFS_E_INVAL_FSSNAPID prev_fssnapId is invalid
529 *              EDOM prev_fssnapId is from a different fs
530 *              ERANGE prev_fssnapId is same as or more recent than snapId
531 *                     being scanned
532 *              see system calls dup() and malloc() ERRORS
533 */
534gpfs_iscan_t *
535gpfs_open_inodescan(gpfs_fssnap_handle_t *fssnapHandle,
536                    const gpfs_fssnap_id_t *prev_fssnapId,
537                    gpfs_ino_t *maxIno);
538
539
540/* NAME:        gpfs_next_inode()
541 *
542 * FUNCTION:    Get next inode from inode scan. Scan terminates before
543 *              the last inode specified or the last inode in the
544 *              inode file being scanned.
545 *
546 * Input:       iscan: ptr to inode scan descriptor
547 *              termIno: scan terminates before this inode number
548 *                caller may specify maxIno from gpfs_open_inodescan()
549 *                or 0 to scan the entire inode file.
550 *              iattr: pointer to returned pointer to file's iattr.
551 *
552 * Returns:     0 and *iattr set to point to gpfs_iattr_t (Successful)
553 *              0 and *iattr set to NULL for no more inodes before termIno
554 *              -1 and errno is set (Failure)
555 *
556 * Errno:       ENOSYS function not available
557 *              EPERM caller must have superuser priviledges
558 *              ESTALE cached fs information was invalid
559 *              ENOMEM buffer too small
560 *              GPFS_E_INVAL_ISCAN bad parameters
561 *
562 * Notes:       The data returned by gpfs_next_inode() is overwritten by
563 *              subsequent calls to gpfs_next_inode() or gpfs_seek_inode().
564 *
565 *              The termIno parameter provides a means to partition an
566 *              inode scan such that it may be executed on more than one node.
567 */
568int 
569gpfs_next_inode(gpfs_iscan_t *iscan,
570                gpfs_ino_t termIno,
571                const gpfs_iattr_t **iattr);
572
573
574/* NAME:        gpfs_seek_inode()
575 *
576 * FUNCTION:    Seek to a given inode number.
577 *
578 * Input:       iscan: ptr to inode scan descriptor
579 *              ino: next inode number to be scanned
580 *
581 * Returns:     0      Successful
582 *              -1     Failure and errno is set
583 *
584 * Errno:       ENOSYS function not available
585 *              GPFS_E_INVAL_ISCAN bad parameters
586 */
587int 
588gpfs_seek_inode(gpfs_iscan_t *iscan, 
589                gpfs_ino_t ino);
590
591
592/* NAME:        gpfs_close_inodescan()
593 *
594 * FUNCTION:    Close inode file.
595 *
596 * Input:       iscan: ptr to inode scan descriptor
597 *
598 * Returns:     void
599 *
600 * Errno:       None
601 */
602void 
603gpfs_close_inodescan(gpfs_iscan_t *iscan);
604
605
606/* NAME:        gpfs_cmp_fssnapid()
607 *
608 * FUNCTION:    Compare two fssnapIds for the same file system to
609 *              determine the order in which the two snapshots were taken.
610 *              The 'result' variable will be set as follows:
611 *                *result < 0:  snapshot 1 was taken before snapshot 2
612 *                *result == 0: snapshot 1 and 2 are the same
613 *                *result > 0:  snapshot 1 was taken after snapshot 2
614 *
615 * Input:      fssnapId1: ptr to fssnapId 1
616 *             fssnapId2: ptr to fssnapId id 2
617 *             result: ptr to returned results
618 *
619 * Returns:     0 and *result is set as described above (Successful)
620 *              -1 and errno is set (Failure)
621 *
622 * Errno:       ENOSYS function not available
623 *              GPFS_E_INVAL_FSSNAPID fssnapid1 or fssnapid2 is not a
624 *                valid snapshot id
625 *              EDOM the two snapshots cannot be compared because
626 *                they were taken from two different file systems.
627 */
628int 
629gpfs_cmp_fssnapid(const gpfs_fssnap_id_t *fssnapId1, 
630                  const gpfs_fssnap_id_t *fssnapId2,
631                  int *result);
632
633
634/* NAME:        gpfs_iopen()
635 *
636 * FUNCTION:    Open a file or directory by inode number.
637 *
638 * Input: fssnapHandle: handle for file system and snapshot
639 *                      being scanned
640 *        ino: inode number
641 *        open_flags: O_RDONLY for gpfs_iread()
642 *                    O_WRONLY for gpfs_iwrite()
643 *                    O_CREAT create the file if it doesn't exist
644 *                    O_TRUNC if the inode already exists delete it
645 *           caller may use GPFS_O_BACKUP to read files for backup
646 *                      and GPFS_O_RESTORE to write files for restore
647 *        statxbuf: used only with O_CREAT/GPFS_O_BACKUP
648 *                  all other cases set to NULL
649 *        symLink: used only with O_CREAT/GPFS_O_BACKUP for a symbolic link
650 *                 all other cases set to NULL
651 *
652 * Returns:     pointer to gpfs_ifile_t (Successful)
653 *              NULL and errno is set (Failure)
654 *
655 * Errno:       ENOSYS function not available
656 *              EINVAL missing or bad parameter
657 *              EPERM caller must have superuser priviledges
658 *              ESTALE cached fs information was invalid
659 *              ENOMEM unable to allocate memory for request
660 *              EFORMAT invalid fs version number
661 *              EIO error reading original inode
662 *              GPFS_E_INVAL_IATTR iattr structure was corrupted
663 *              see dup() and malloc() ERRORS
664 */
665gpfs_ifile_t *
666gpfs_iopen(gpfs_fssnap_handle_t *fssnapHandle, 
667           gpfs_ino_t ino, 
668           int open_flags,
669           const gpfs_iattr_t *statxbuf, 
670           const char *symLink);
671
672/* Define gpfs_iopen flags as used by the backup & restore by inode.
673   The backup code will only read the source files.
674   The restore code writes the target files & creates them if they
675   don't already exist. The file length is set by the inode attributes.
676   Consequently, to restore a user file it is unnecessary to include
677   the O_TRUNC flag. */
678#define GPFS_O_BACKUP  (O_RDONLY)
679#define GPFS_O_RESTORE (O_WRONLY | O_CREAT)
680
681
682/* NAME:        gpfs_iread()
683 *
684 * FUNCTION:    Read file opened by gpfs_iopen.
685 *
686 * Input:       ifile:      pointer to gpfs_ifile_t from gpfs_iopen
687 *              buffer:     buffer for data to be read
688 *              bufferSize: size of buffer (ie amount of data to be read)
689 * In/Out       offset:     offset of where within the file to read
690 *                          if successful, offset will be updated to the
691 *                          next byte after the last one that was read
692 *
693 * Returns:     number of bytes read (Successful)
694 *              -1 and errno is set (Failure)
695 *
696 * Errno:       ENOSYS function not available
697 *              EISDIR file is a directory
698 *              EPERM caller must have superuser priviledges
699 *              ESTALE cached fs information was invalid
700 *              GPFS_E_INVAL_IFILE bad ifile parameters
701 *              see system call read() ERRORS
702 */
703int 
704gpfs_iread(gpfs_ifile_t *ifile, 
705           void *buffer, 
706           int bufferSize, 
707           gpfs_off64_t *offset);
708
709
710/* NAME:        gpfs_iwrite()
711 *
712 * FUNCTION:    Write file opened by gpfs_iopen.
713 *
714 * Input:       ifile:    pointer to gpfs_ifile_t from gpfs_iopen
715 *              buffer:   the data to be written
716 *              writeLen: how much to write
717 * In/Out       offset:   offset of where within the file to write
718 *                        if successful, offset will be updated to the
719 *                        next byte after the last one that was written
720 *
721 * Returns:     number of bytes written (Successful)
722 *              -1 and errno is set (Failure)
723 *
724 * Errno:       ENOSYS function not available
725 *              EISDIR file is a directory
726 *              EPERM caller must have superuser priviledges
727 *              ESTALE cached fs information was invalid
728 *              GPFS_E_INVAL_IFILE bad ifile parameters
729 *              see system call write() ERRORS
730 */
731int 
732gpfs_iwrite(gpfs_ifile_t *ifile, 
733            void *buffer, 
734            int writeLen, 
735            gpfs_off64_t *offset);
736
737
738/* NAME:        gpfs_ireaddir()
739 *
740 * FUNCTION:    Get next directory entry.
741 *
742 * Input:       idir:   pointer to gpfs_ifile_t from gpfs_iopen
743 *              dirent: pointer to returned pointer to directory entry
744 *
745 * Returns:     0 and pointer to gpfs_direntx set (Successful)
746 *              0 and pointer to gpfs_direntx set to NULL (End of directory)
747 *              -1 and errno is set (Failure)
748 *
749 * Errno:       ENOSYS function not available
750 *              ENOTDIR file is not a directory
751 *              EPERM caller must have superuser priviledges
752 *              ESTALE cached fs information was invalid
753 *              GPFS_E_INVAL_IFILE bad ifile parameter
754 *              ENOMEM unable to allocate memory for request
755 *
756 * Notes:       The data returned by gpfs_ireaddir() is overwritten by
757 *              subsequent calls to gpfs_ireaddir().
758 */
759int 
760gpfs_ireaddir(gpfs_ifile_t *idir,
761              const gpfs_direntx_t **dirent);
762
763
764/* NAME:        gpfs_iwritedir()
765 *
766 * FUNCTION:    Create a directory entry in a directory opened by gpfs_iopen.
767 *
768 * Input:       idir:   pointer to gpfs_ifile_t from gpfs_iopen
769 *              dirent: directory entry to be written
770 *
771 * Returns:     0 (Successful)
772 *              -1 and errno is set (Failure)
773 *
774 * Errno:       ENOSYS function not available
775 *              GPFS_E_INVAL_IFILE bad file pointer
776 *              ENOTDIR file is not a directory
777 *              EPERM caller must have superuser priviledges
778 *              ESTALE cached fs information was invalid
779 *              ENOMEM unable to allocate memory for request
780 *              EFORMAT invalid dirent version number
781 *              see system call write() ERRORS
782 */
783int 
784gpfs_iwritedir(gpfs_ifile_t *idir, 
785               const gpfs_direntx_t *dirent);
786
787
788/* NAME:        gpfs_igetattrs()
789 *
790 * FUNCTION:    Retrieves all extended file attributes in opaque format.
791 *              This function together with gpfs_iputattrs is intended for
792 *              use by a backup program to save (gpfs_igetattrs) and
793 *              restore (gpfs_iputattrs) all extended file attributes
794 *              (ACLs, dmapi attributes, ...) in one call.
795 *
796 * Input:       ifile:      pointer to gpfs_ifile_t from gpfs_iopen
797 *              buffer:     pointer to buffer for returned attributes
798 *              bufferSize: size of buffer
799 *              attrSize:   ptr to returned size of attributes
800 *
801 * Returns:      0      Successful
802 *              -1      Failure and errno is set
803 *
804 * Errno:       ENOSYS  function not available
805 *              EPERM caller must have superuser priviledges
806 *              ESTALE cached fs information was invalid
807 *              ENOSPC  buffer too small to return all attributes
808 *                      *attrSizeP will be set to the size necessary
809 *              GPFS_E_INVAL_IFILE bad ifile parameters
810 */
811int 
812gpfs_igetattrs(gpfs_ifile_t *ifile, 
813               void *buffer, 
814               int bufferSize, 
815               int *attrSize);
816
817
818/* NAME:        gpfs_iputattrs()
819 *
820 * FUNCTION:    Sets all extended file attributes of a file.
821 *              The buffer passed in should contain extended attribute data
822 *              that was obtained by a previous call to gpfs_igetattrs.
823 *
824 * Input:       ifile:  pointer to gpfs_ifile_t from gpfs_iopen
825 *              buffer: pointer to buffer for returned attributes
826 *
827 * Returns:      0      Successful
828 *              -1      Failure and errno is set
829 *
830 * Errno:       ENOSYS  function not available
831 *              EINVAL  the buffer does not contain valid attribute data
832 *              EPERM caller must have superuser priviledges
833 *              ESTALE cached fs information was invalid
834 *              GPFS_E_INVAL_IFILE bad ifile parameters
835 */
836int 
837gpfs_iputattrs(gpfs_ifile_t *ifile, 
838               void *buffer);
839
840
841/* NAME:        gpfs_igetfilesetname()
842 *
843 * FUNCTION:    Retrieves the name of the fileset which contains this file.
844 *              The fileset name is a null-terminated string, with a
845 *              a maximum length of GPFS_MAXNAMLEN.
846 *
847 * Input:       iscan:      ptr to gpfs_iscan_t from gpfs_open_inodescan()
848 *              filesetId:  ia_filesetId returned in an iattr from the iscan
849 *              buffer:     pointer to buffer for returned fileset name
850 *              bufferSize: size of buffer
851 *
852 * Returns:      0      Successful
853 *              -1      Failure and errno is set
854 *
855 * Errno:       ENOSYS  function not available
856 *              EPERM caller must have superuser priviledges
857 *              ESTALE cached fs information was invalid
858 *              ENOSPC  buffer too small to return fileset name
859 *              GPFS_E_INVAL_ISCAN bad iscan parameter
860 */
861int 
862gpfs_igetfilesetname(gpfs_iscan_t *iscan,
863                     unsigned int filesetId,
864                     void *buffer, 
865                     int bufferSize);
866
867
868/* NAME:        gpfs_igetstoragepool()
869 *
870 * FUNCTION:    Retrieves the name of the storage pool assigned for
871 *              this file's data. The storage pool name is a null-terminated
872 *              string, with a maximum length of GPFS_MAXNAMLEN.
873 *
874 * Input:       iscan:      ptr to gpfs_iscan_t from gpfs_open_inodescan()
875 *              dataPoolId: ia_dataPoolId returned in an iattr from the iscan
876 *              buffer:     pointer to buffer for returned attributes
877 *              bufferSize: size of buffer
878 *
879 * Returns:      0      Successful
880 *              -1      Failure and errno is set
881 *
882 * Errno:       ENOSYS  function not available
883 *              EPERM caller must have superuser priviledges
884 *              ESTALE cached fs information was invalid
885 *              ENOSPC  buffer too small to return all storage pool name
886 *              GPFS_E_INVAL_ISCAN bad iscan parameters
887 */
888int 
889gpfs_igetstoragepool(gpfs_iscan_t *iscan,
890                     unsigned int dataPoolId,
891                     void *buffer, 
892                     int bufferSize);
893
894
895/* NAME:        gpfs_iclose()
896 *
897 * FUNCTION:    Close file opened by inode and update dates.
898 *
899 * Input:       ifile:   pointer to gpfs_ifile_t from gpfs_iopen
900 *
901 * Returns:     void
902 *
903 * Errno:       ENOSYS function not available
904 *              EPERM caller must have superuser priviledges
905 *              ESTALE cached fs information was invalid
906 */
907void 
908gpfs_iclose(gpfs_ifile_t *ifile);
909
910
911/* NAME:        gpfs_ireadlink()
912 *
913 * FUNCTION:    Read symbolic link by inode number.
914 *
915 * Input:       fssnapHandle: handle for file system & snapshot being scanned
916 *              ino:        inode number of link file to read
917 *              buffer:     pointer to buffer for returned link data
918 *              bufferSize: size of the buffer
919 *
920 * Returns:     number of bytes read (Successful)
921 *              -1 and errno is set (Failure)
922 *
923 * Errno:       ENOSYS function not available
924 *              EPERM caller must have superuser priviledges
925 *              ESTALE cached fs information was invalid
926 *              GPFS_E_INVAL_FSSNAPHANDLE invalid fssnap handle
927 *              see system call readlink() ERRORS
928 */
929int 
930gpfs_ireadlink(gpfs_fssnap_handle_t *fssnapHandle,
931               gpfs_ino_t ino, 
932               char *buffer, 
933               int bufferSize);
934
935
936/* NAME:        gpfs_sync_fs()
937 *
938 * FUNCTION:    sync file system.
939 *
940 * Input:       fssnapHandle: handle for file system being restored
941 *
942 * Returns:      0 all data flushed to disk (Successful)
943 *              -1 and errno is set (Failure)
944 *
945 * Errno:       ENOSYS  function not available
946 *              ENOMEM unable to allocate memory for request
947 *              EPERM caller must have superuser priviledges
948 *              ESTALE cached fs information was invalid
949 *              GPFS_E_INVAL_FSSNAPHANDLE invalid fssnapHandle
950 */
951int 
952gpfs_sync_fs(gpfs_fssnap_handle_t *fssnapHandle);
953
954
955/* NAME:        gpfs_enable_restore()
956 *
957 * FUNCTION:    Mark file system as enabled for restore on/off
958 *
959 * Input:       fssnapHandle: handle for file system to be enabled
960 *                            or disabled for restore
961 *              on_off:   flag set to 1 to enable restore
962 *                                    0 to disable restore
963 *
964 * Returns:      0 (Successful)
965 *              -1 and errno is set (Failure)
966 *
967 * Errno:       ENOSYS function not available
968 *              EINVAL bad parameters
969 *              GPFS_E_INVAL_FSSNAPHANDLE invalid fssnapHandle
970 *              EPERM caller must have superuser priviledges
971 *              ESTALE cached fs information was invalid
972 *              ENOMEM unable to allocate memory for request
973 *              E_FS_NOT_RESTORABLE fs is not clean
974 *              EALREADY fs already marked as requested
975 *              E_RESTORE_STARTED restore in progress
976 *
977 * Notes: EALREADY indicates enable/disable restore was already called
978 * for this fs. The caller must decide if EALREADY represents an
979 * error condition.
980 */
981int 
982gpfs_enable_restore(gpfs_fssnap_handle_t *fssnapHandle, 
983                    int on_off);
984
985
986/* NAME:        gpfs_start_restore()
987 *
988 * FUNCTION:    Start a restore session.
989 *
990 * Input:       fssnapHandle: handle for file system to be restored
991 *              restore_flags: Flag to indicate the restore should be started
992 *                             even if a prior restore has not completed.
993 *              old_fssnapId: fssnapId of last restored snapshot
994 *              new_fssnapId: fssnapId of snapshot being restored
995 *
996 * Returns:     pointer to gpfs_restore_t (Successful)
997 *              NULL and errno is set (Failure)
998 *
999 * Errno:       ENOSYS function not available
1000 *              ENOMEM unable to allocate memory for request
1001 *              EINVAL missing parameter
1002 *              EPERM caller must have superuser priviledges
1003 *              ESTALE cached fs information was invalid
1004 *              EDOM restore fs does not match existing fs
1005 *              ERANGE restore is missing updates
1006 *              EFORMAT invalid fs version number
1007 *              GPFS_E_INVAL_FSSNAPHANDLE invalid fssnaphandle
1008 *              GPFS_E_INVAL_FSSNAPID bad fssnapId parameter
1009 *              E_FS_NOT_RESTORABLE fs is not clean for restore
1010 *              E_RESTORE_NOT_ENABLED fs is not enabled for restore
1011 *              EALREADY Restore already in progress
1012 *
1013 * Note: EALREADY indicates start restore was already called for
1014 * this fs. This could be due to a prior restore process that failed
1015 * or it could be due to a concurrent restore process still running.
1016 * The caller must decide if EALREADY represents an error condition.
1017 */
1018gpfs_restore_t *
1019gpfs_start_restore(gpfs_fssnap_handle_t *fssnapHandle,
1020                   int restore_flags,
1021                   const gpfs_fssnap_id_t *old_fssnapId,
1022                   const gpfs_fssnap_id_t *new_fssnapId);
1023
1024#define GPFS_RESTORE_NORMAL 0   /* Restore not started if prior restore
1025                                   has not completed. */
1026#define GPFS_RESTORE_FORCED 1   /* Restore starts even if prior restore
1027                                   has not completed. */
1028
1029
1030/* NAME:        gpfs_end_restore()
1031 *
1032 * FUNCTION:    End a restore session.
1033 *
1034 * Input:       restoreId: ptr to gpfs_restore_t
1035 *
1036 * Returns:     0 (Successful)
1037 *              -1 and errno is set (Failure)
1038 *
1039 * Errno:       ENOSYS function not available
1040 *              EINVAL bad parameters
1041 *              EPERM caller must have superuser priviledges
1042 *              ESTALE cached fs information was invalid
1043 *              GPFS_E_INVAL_RESTORE bad restoreId parameter
1044 *              GPFS_E_FS_NOT_RESTORABLE fs is not clean for restore
1045 *              GPFS_E_RESTORE_NOT_ENABLED fs is not enabled for restore
1046 *              EALREADY Restore already ended
1047 *
1048 * Note: EALREADY indicates end restore was already called for
1049 * this fs. This could be due to a concurrent restore process that
1050 * already completed. The caller must decide if EALREADY represents
1051 * an error condition.
1052 */
1053int 
1054gpfs_end_restore(gpfs_restore_t *restoreId);
1055
1056
1057
1058/* NAME:        gpfs_ireadx()
1059 *
1060 * FUNCTION:    Block level incremental read on a file opened by gpfs_iopen
1061 *              with a given incremental scan opened via gpfs_open_inodescan.
1062 *
1063 * Input:       ifile:      ptr to gpfs_file_t returned from gpfs_iopen()
1064 *              iscan:      ptr to gpfs_iscan_t from gpfs_open_inodescan()
1065 *              buffer:     ptr to buffer for returned data
1066 *              bufferSize: size of buffer for returned data
1067 *              offset:     ptr to offset value
1068 *              termOffset: read terminates before reading this offset
1069 *                caller may specify ia_size for the file's gpfs_iattr_t
1070 *                or 0 to scan the entire file.
1071 *              hole:       ptr to returned flag to indicate a hole in the file
1072 *
1073 * Returns:     number of bytes read and returned in buffer
1074 *              or size of hole encountered in the file. (Success)
1075 *              -1 and errno is set (Failure)
1076 *
1077 *              On input, *offset contains the offset in the file
1078 *              at which to begin reading to find a difference same file
1079 *              in a previous snapshot specified when the inodescan was opened.
1080 *              On return, *offset contains the offset of the first
1081 *              difference.
1082 *
1083 *              On return, *hole indicates if the change in the file
1084 *              was data (*hole == 0) and the data is returned in the
1085 *              buffer provided. The function's value is the amount of data
1086 *              returned. If the change is a hole in the file,
1087 *              *hole != 0 and the size of the changed hole is returned
1088 *              as the function value.
1089 *
1090 *              A call with a NULL buffer pointer will query the next increment
1091 *              to be read from the current offset. The *offset, *hole and
1092 *              returned length will be set for the next increment to be read,
1093 *              but no data will be returned. The bufferSize parameter is
1094 *              ignored, but the termOffset parameter will limit the
1095 *              increment returned.
1096 *
1097 * Errno:       ENOSYS function not available
1098 *              EINVAL missing or bad parameter
1099 *              EISDIR file is a directory
1100 *              EPERM caller must have superuser priviledges
1101 *              ESTALE cached fs information was invalid
1102 *              ENOMEM unable to allocate memory for request
1103 *              EDOM fs snapId does match local fs
1104 *              ERANGE previous snapId is more recent than scanned snapId
1105 *              GPFS_E_INVAL_IFILE bad ifile parameter
1106 *              GPFS_E_INVAL_ISCAN bad iscan parameter
1107 *              see system call read() ERRORS
1108 *
1109 * Notes:       The termOffset parameter provides a means to partition a
1110 *              file's data such that it may be read on more than one node.
1111 */
1112gpfs_off64_t
1113gpfs_ireadx(gpfs_ifile_t *ifile,      /* in only  */
1114            gpfs_iscan_t *iscan,      /* in only  */
1115            void *buffer,             /* in only  */
1116            int bufferSize,           /* in only  */
1117            gpfs_off64_t *offset,     /* in/out   */
1118            gpfs_off64_t termOffset,  /* in only */
1119            int *hole);               /* out only */
1120
1121
1122/* NAME:        gpfs_iwritex()
1123 *
1124 * FUNCTION:    Write file opened by gpfs_iopen.
1125 *              If parameter hole == 0, then write data
1126 *              addressed by buffer to the given offset for the
1127 *              given length. If hole != 0, then write
1128 *              a hole at the given offset for the given length.
1129 *
1130 * Input:       ifile :   ptr to gpfs_file_t returned from gpfs_iopen()
1131 *              buffer:   ptr to data buffer
1132 *              writeLen: length of data to write
1133 *              offset:   offset in file to write data
1134 *              hole:     flag =1 to write a "hole"
1135 *                             =0 to write data
1136 *
1137 * Returns:     number of bytes/size of hole written (Success)
1138 *              -1 and errno is set (Failure)
1139 *
1140 * Errno:       ENOSYS function not available
1141 *              EINVAL missing or bad parameter
1142 *              EISDIR file is a directory
1143 *              EPERM caller must have superuser priviledges
1144 *              ESTALE cached fs information was invalid
1145 *              GPFS_E_INVAL_IFILE bad ifile parameter
1146 *              see system call write() ERRORS
1147 */
1148gpfs_off64_t
1149gpfs_iwritex(gpfs_ifile_t *ifile,    /* in only */
1150             void *buffer,           /* in only */
1151             gpfs_off64_t writeLen,  /* in only */
1152             gpfs_off64_t offset,    /* in only */
1153             int hole);              /* in only */
1154
1155
1156/* NAME:        gpfs_statfspool()
1157 *
1158 * FUNCTION:    Obtain status information about the storage pools
1159 *
1160 * Input:       pathname   : path to any file in the file system
1161 *              poolId     : id of first pool to return
1162 *                           on return set to next poolId or -1
1163 *                           to indicate there are no more pools.
1164 *              options    : option flags (currently not used)
1165 *              nPools     : number of stat structs requested or 0
1166 *                           on return number of stat structs in buffer
1167 *                           or if nPools was 0 its value is the max number
1168 *                           of storage pools currently defined
1169 *              buffer     :  ptr to return stat structures
1170 *              bufferSize : sizeof stat buffer
1171 *             
1172 *              The user is expected to issue two or more calls. On the first
1173 *              call the user should pass nPools set to 0 and gpfs will
1174 *              return in nPools the total number of storage pools currently
1175 *              defined for the file system indicated by the pathname
1176 *              and it returns in poolId the id of the first storage pool.
1177 *              The buffer parameter may be set to NULL for this call.
1178 *
1179 *              The user may then allocate a buffer large enough to contain
1180 *              a gpfs_statpool_t structure for each of the pools and issue
1181 *              a second call to obtain stat information about each pool.
1182 *              Parameter nPools should be set the number of pools requested.
1183 *              On return, nPools will be set to the number of stat structs
1184 *              contained in the buffer, and poolId will be set to the id
1185 *              of the next storage pool or -1 to indicate there are no
1186 *              additional storage pools defined.
1187 *
1188 *              Alternatively, if the user has a valid poolId from a previous
1189 *              call, the user may provide that poolId and a buffer large
1190 *              enough for a single gpfs_statpool_t structure, and the call
1191 *              will return the status for a single storage pool.
1192 *
1193 *
1194 * Returns:      0      Successful
1195 *              -1      Failure
1196 *
1197 * Errno:       Specific error indication
1198 *              EINVAL 
1199 */
1200int 
1201gpfs_statfspool(const char *pathname, /* in only: path to file system*/
1202                gpfs_pool_t *poolId,  /* in out: id of first pool to return
1203                                         on return set to next poolId
1204                                         or -1 when there are no more pools */
1205                unsigned int options, /* in only: option flags */
1206                int *nPools,          /* in out: number of pool stats requested
1207                                         on return number of stat structs
1208                                         returned in buffer or if nPools was
1209                                         set to 0, the return value is the
1210                                         number of pools currently defined */
1211                void *buffer,         /* ptr to return stat structures */
1212                int bufferSize);      /* sizeof stat buffer or 0 */
1213             
1214
1215
1216/* NAME:        gpfs_getpoolname()
1217 *
1218 * FUNCTION:    Retrieves the name of the storage pool assigned for
1219 *              this file's data. The storage pool name is a null-terminated
1220 *              string, with a maximum length of GPFS_MAXNAMLEN.
1221 *
1222 * Input:       pathname:   path to any file in the file system
1223 *              poolId:     f_poolid returned in gpfs_statfspool_t
1224 *              buffer:     pointer to buffer for returned name
1225 *              bufferSize: size of buffer
1226 *
1227 * Returns:      0      Successful
1228 *              -1      Failure and errno is set
1229 *
1230 * Errno:       ENOSYS function not available
1231 *              ESTALE file system was unmounted
1232 *              E_FORMAT_INCOMPAT file system does not support pools
1233 *              E2BIG  buffer too small to return storage pool name
1234 */
1235int 
1236gpfs_getpoolname(const char *pathname,
1237                 gpfs_pool_t poolId,
1238                 void *buffer, 
1239                 int bufferSize);
1240
1241
1242/* GPFS QUOTACTL */
1243
1244/*
1245 * Command definitions for the 'gpfs_quotactl' system call.
1246 * The commands are broken into a main command defined below
1247 * and a subcommand that is used to convey the type of
1248 * quota that is being manipulated (see above).
1249 */
1250
1251#define SUBCMDMASK      0x00ff
1252#define SUBCMDSHIFT     8
1253#define QCMD(cmd, type) (((cmd) << SUBCMDSHIFT) | ((type) & SUBCMDMASK))
1254
1255#define Q_QUOTAON       0x0100  /* enable quotas */
1256#define Q_QUOTAOFF      0x0200  /* disable quotas */
1257#define Q_GETQUOTA      0x0300  /* get limits and usage */
1258#ifndef _LINUX_SOURCE_COMPAT
1259 /* Standard AIX definitions of quota commands */
1260#define Q_SETQUOTA      0x0400  /* set limits */
1261#define Q_SETQLIM       Q_SETQUOTA
1262#else
1263 /* Alternate definitions, for Linux Affinity */
1264#define Q_SETQLIM       0x0400  /* set limits */
1265#define Q_SETQUOTA      0x0700  /* set limits and usage */
1266#endif
1267#define Q_SETUSE        0x0500  /* set usage */
1268#define Q_SYNC          0x0600  /* sync disk copy of a filesystems quotas */
1269
1270/* gpfs quota types */
1271#define GPFS_USRQUOTA     0
1272#define GPFS_GRPQUOTA     1
1273#define GPFS_FILESETQUOTA 2
1274
1275typedef struct gpfs_quotaInfo
1276{
1277  gpfs_off64_t blockUsage;      /* current block count in 1 KB units*/
1278  gpfs_off64_t blockHardLimit;  /* absolute limit on disk blks alloc */
1279  gpfs_off64_t blockSoftLimit;  /* preferred limit on disk blks */
1280  gpfs_off64_t blockInDoubt;    /* distributed shares + "lost" usage for blks */
1281  int          inodeUsage;      /* current # allocated inodes */
1282  int          inodeHardLimit;  /* absolute limit on allocated inodes */
1283  int          inodeSoftLimit;  /* preferred inode limit */
1284  int          inodeInDoubt;    /* distributed shares + "lost" usage for inodes */
1285  gpfs_uid_t   quoId;           /* uid, gid or fileset id */
1286  int          entryType;       /* entry type, not used */
1287  unsigned int blockGraceTime;  /* time limit for excessive disk use */
1288  unsigned int inodeGraceTime;  /* time limit for excessive inode use */
1289} gpfs_quotaInfo_t;
1290
1291
1292/*
1293 * NAME:        gpfs_quotactl
1294 *
1295 * FUNCTION:    Manipulate disk quotas
1296 * INPUT:       pathname: specifies the pathname of any file within the
1297 *                        mounted file system to which the command is to
1298 *                        be applied
1299 *              cmd: specifies a quota control command to be applied
1300 *                   to UID/GID/FILESETID id.
1301 *                   the cmd parameter can be constructed using QCMD(cmd, type)
1302 *                   macro defined in gpfs.h
1303 *                   of quota.
1304 *              id:  UID or GID or FILESETID that command applied to.
1305 *              bufferP: points to the address of an optional, command
1306 *                       specific, data structure that is copied in or out of
1307 *                       the system.
1308 *             
1309 * OUTPUT:      bufferP, if applicable.
1310 *
1311 * Returns:     0 success
1312 *              -1 failure
1313 *
1314 * Errno:       EACCESS
1315 *              EFAULT        An invalid bufferP parameter is supplied;
1316 *                            the associated structure could not be copied
1317 *                            in or out of the kernel
1318 *              EINVAL 
1319 *              ENOENT        No such file or directory
1320 *              EPERM         The quota control command is privileged and
1321 *                            the caller did not have root user authority
1322 *              EOPNOTSUPP
1323 *              E_NO_QUOTA_INST The file system does not support quotas
1324 */
1325
1326int 
1327gpfs_quotactl(char *pathname, int cmd, int id, void *bufferP);
1328
1329#ifdef __cplusplus
1330}
1331#endif
1332
1333#endif /* H_GPFS */
Note: See TracBrowser for help on using the repository browser.