/* IBM_PROLOG_BEGIN_TAG */ /* This is an automatically generated prolog. */ /* */ /* */ /* */ /* Licensed Materials - Property of IBM */ /* */ /* (C) COPYRIGHT International Business Machines Corp. 1998,2007 */ /* All Rights Reserved */ /* */ /* US Government Users Restricted Rights - Use, duplication or */ /* disclosure restricted by GSA ADP Schedule Contract with IBM Corp. */ /* */ /* IBM_PROLOG_END_TAG */ /* @(#)42 1.1.5.1 src/avs/fs/mmfs/ts/util/gpfs.h, mmfs, avs_rgpfs24, rgpfs24s011a 3/13/07 10:16:05 */ /* * Library calls for GPFS interfaces */ #ifndef H_GPFS #define H_GPFS #ifdef __cplusplus extern "C" { #endif #include #include /* Define maximum length of the name for a GPFS named object, such as a snapshot, storage pool or fileset. The name is a null-terminated character string, which is not include in the max length */ #define GPFS_MAXNAMLEN 255 /* Define maximum length of the path to a GPFS named object such as a snapshot or fileset. If the absolute path name exceeds this limit, then use a relative path name. The path is a null-terminated character string, which is not included in the max length */ #define GPFS_MAXPATHLEN 1023 /* ASCII code for "GPFS" in the struct statfs f_type field */ #define GPFS_SUPER_MAGIC 0x47504653 /* GPFS inode attributes */ typedef unsigned int gpfs_mode_t; typedef unsigned int gpfs_uid_t; typedef unsigned int gpfs_gid_t; typedef unsigned int gpfs_ino_t; typedef unsigned int gpfs_gen_t; typedef unsigned int gpfs_dev_t; typedef unsigned int gpfs_mask_t; typedef unsigned int gpfs_pool_t; typedef long long gpfs_off64_t; typedef struct stat64 stat64_t; /* open source interfaces */ #include typedef struct gpfs_timestruc { unsigned int tv_sec; unsigned int tv_nsec; } gpfs_timestruc_t; /* Define a version number for the directory entry data to allow future changes in this structure. Careful callers should also use the d_reclen field for the size of the structure rather than sizeof, to allow some degree of forward compatibility */ #define GPFS_D_VERSION 1 typedef struct gpfs_direntx { int d_version; /* this struct's version */ unsigned short d_reclen; /* actual size of this struct including null terminated variable length d_name */ unsigned short d_type; /* Types are defined below */ gpfs_ino_t d_ino; /* File inode number */ gpfs_gen_t d_gen; /* Generation number for the inode */ char d_name[256]; /* null terminated variable length name */ } gpfs_direntx_t; /* File types for d_type field in gpfs_direntx_t */ #define GPFS_DE_OTHER 0 #define GPFS_DE_DIR 4 #define GPFS_DE_REG 8 #define GPFS_DE_LNK 10 /* Define a version number for the iattr data to allow future changes in this structure. Careful callers should also use the ia_reclen field for the size of the structure rather than sizeof, to allow some degree of forward compatibility */ #define GPFS_IA_VERSION 1 typedef struct gpfs_iattr { int ia_version; /* this struct version */ int ia_reclen; /* sizeof this structure */ int ia_checksum; /* validity check on iattr struct */ gpfs_mode_t ia_mode; /* access mode */ gpfs_uid_t ia_uid; /* owner uid */ gpfs_gid_t ia_gid; /* owner gid */ gpfs_ino_t ia_inode; /* file inode number */ gpfs_gen_t ia_gen; /* inode generation number */ short ia_nlink; /* number of links */ short ia_flags; /* Flags (defined below) */ int ia_blocksize; /* preferred block size for io */ gpfs_mask_t ia_mask; /* Initial attribute mask (not used) */ gpfs_off64_t ia_size; /* file size in bytes */ gpfs_off64_t ia_blocks; /* 512 byte blocks of disk held by file */ gpfs_timestruc_t ia_atime; /* time of last access */ gpfs_timestruc_t ia_mtime; /* time of last data modification */ gpfs_timestruc_t ia_ctime; /* time of last status change */ gpfs_dev_t ia_rdev; /* id of device */ unsigned int ia_xperm; /* extended attributes (defined below) */ int ia_modsnapid; unsigned int ia_filesetid; /* fileset ID */ unsigned int ia_datapoolid; /* storage pool ID for data */ } gpfs_iattr_t; /* Define flags for inode attributes */ #define GPFS_IAFLAG_SNAPDIR 0x0001 /* (obsolete) */ #define GPFS_IAFLAG_USRQUOTA 0x0002 /* inode is a user quota file */ #define GPFS_IAFLAG_GRPQUOTA 0x0004 /* inode is a group quota file */ #define GPFS_IAFLAG_ERROR 0x0008 /* error reading inode */ /* Define flags for inode replication attributes */ #define GPFS_IAFLAG_FILESET_ROOT 0x0010 /* root dir of a fileset */ #define GPFS_IAFLAG_NO_SNAP_RESTORE 0x0020 /* don't restore from snapshots */ #define GPFS_IAFLAG_FILESETQUOTA 0x0040 /* inode is a fileset quota file */ #define GPFS_IAFLAG_COMANAGED 0x0080 /* file data is co-managed */ #define GPFS_IAFLAG_ILLPLACED 0x0100 /* may not be properly placed */ #define GPFS_IAFLAG_REPLMETA 0x0200 /* metadata replication set */ #define GPFS_IAFLAG_REPLDATA 0x0400 /* data replication set */ #define GPFS_IAFLAG_EXPOSED 0x0800 /* may have data on suspended disks */ #define GPFS_IAFLAG_ILLREPLICATED 0x1000 /* may not be properly replicated */ #define GPFS_IAFLAG_UNBALANCED 0x2000 /* may not be properly balanced */ #define GPFS_IAFLAG_DATAUPDATEMISS 0x4000 /* has stale data blocks on unavailable disk */ #define GPFS_IAFLAG_METAUPDATEMISS 0x8000 /* has stale metadata on unavailable disk */ /* Define flags for extended attributes */ #define GPFS_IAXPERM_ACL 0x0001 /* file has acls */ #define GPFS_IAXPERM_XATTR 0x0002 /* file has extended attributes */ #define GPFS_IAXPERM_DMATTR 0x0004 /* file has dm attributes */ #define GPFS_IAXPERM_DOSATTR 0x0008 /* file has non-default dos attrs */ #define GPFS_IAXPERM_RPATTR 0x0010 /* file has restore policy attrs */ /* Define pointers to interface types */ typedef struct gpfs_fssnap_handle gpfs_fssnap_handle_t; typedef struct gpfs_iscan gpfs_iscan_t; typedef struct gpfs_ifile gpfs_ifile_t; typedef struct gpfs_restore gpfs_restore_t; typedef struct gpfs_fssnap_id { char opaque[48]; } gpfs_fssnap_id_t; /* Define extended return codes for gpfs backup & restore calls without an explicit return code will return the value in errno */ #define GPFS_ERRNO_BASE 190 #define GPFS_E_INVAL_FSSNAPID (GPFS_ERRNO_BASE+0) /* invalid fssnap id */ #define GPFS_E_INVAL_ISCAN (GPFS_ERRNO_BASE+1) /* invalid iscan pointer */ #define GPFS_E_INVAL_IFILE (GPFS_ERRNO_BASE+2) /* invalid ifile pointer */ #define GPFS_E_INVAL_IATTR (GPFS_ERRNO_BASE+3) /* invalid iattr structure */ #define GPFS_E_INVAL_RESTORE (GPFS_ERRNO_BASE+4) /* invalid restore pointer */ #define GPFS_E_INVAL_FSSNAPHANDLE (GPFS_ERRNO_BASE+5) /* invalid fssnap handle */ #define GPFS_E_INVAL_SNAPNAME (GPFS_ERRNO_BASE+6) /* invalid snapshot name */ #define GPFS_E_FS_NOT_RESTORABLE (GPFS_ERRNO_BASE+7) /* FS is not clean */ #define GPFS_E_RESTORE_NOT_ENABLED (GPFS_ERRNO_BASE+8) /* Restore was not enabled */ #define GPFS_E_RESTORE_STARTED (GPFS_ERRNO_BASE+9) /* Restore is running */ /* Define flags parameter for get/put file attributes. Used by gpfs_fgetattr, gpfs_fputattr, gpfs_fputattrwithpath and gpfs_iputattrwithpath */ #define GPFS_ATTRFLAG_DEFAULT 0 /* default behavior */ #define GPFS_ATTRFLAG_NO_PLACEMENT 1 /* exclude file placement attributes */ /* Define structure used by gpfs_statfspool */ typedef struct gpfs_statfspool_s { gpfs_off64_t f_blocks; /* total data blocks in pool */ gpfs_off64_t f_bfree; /* free blocks in pool */ gpfs_off64_t f_bavail; /* free blocks avail to non-superuser */ gpfs_off64_t f_mblocks; /* total metadata blocks in pool */ gpfs_off64_t f_mfree; /* free blocks avail for system metadata */ int f_bsize; /* optimal storage pool block size */ int f_files; /* total file nodes assigned to pool */ gpfs_pool_t f_poolid; /* storage pool id */ int f_fsize; /* fundamental file system block size */ unsigned int f_usage; /* data and/or metadata stored in pool */ int f_reserved[7];/* Current unused and set to zero */ } gpfs_statfspool_t; #define STATFSPOOL_USAGE_DATA 0x0001 /* Pool stores user data */ #define STATFSPOOL_USAGE_METADATA 0x0002 /* Pool stores system metadata */ /* NAME: gpfs_fstat(), gpfs_stat() * * FUNCTION: Get exact stat information for a file descriptor (or filename). * Forces all other nodes to flush dirty data and metadata to disk. * Returns: 0 Successful * -1 Failure * * Errno: ENOSYS function not available * EBADF Bad file desc * EINVAL Not a GPFS file */ int gpfs_fstat(int fileDesc, stat64_t *buffer); int gpfs_stat(char *pathname, /* File pathname */ stat64_t *buffer); /* NAME: gpfs_fgetattrs() * * FUNCTION: Retrieves all extended file attributes in opaque format. * This function together with gpfs_fputattrs is intended for * use by a backup program to save (gpfs_fgetattrs) and * restore (gpfs_fputattrs) all extended file attributes * (ACLs, dmapi attributes, ...) in one call. * * Input: flags Define behavior of get attributes * See flag definition above. * * Returns: 0 Successful * -1 Failure * * Errno: ENOSYS function not available * ENOSPC buffer too small to return all attributes * *attrSizeP will be set to the size necessary */ int gpfs_fgetattrs(int fileDesc, int flags, void *buffer, int bufferSize, int *attrSize); /* NAME: gpfs_fputattrs() * * FUNCTION: Sets all extended file attributes of a file * and sets the file's storage pool and data replication * to the values saved in the extended attributes. * The buffer passed in should contain extended attribute data * that was obtained by a previous call to gpfs_fgetattrs. * * Input: flags Define behavior of put attributes * See flag definition above. * * Returns: 0 Successful * -1 Failure * * Errno: ENOSYS function not available * EINVAL the buffer does not contain valid attribute data */ int gpfs_fputattrs(int fileDesc, int flags, void *buffer); /* NAME: gpfs_fputattrswithpathname() * * FUNCTION: Sets all extended file attributes of a file and * invokes the policy engine using the file's attributes * saved in the extended attributes to set the file's * storage pool and data replication. The caller should * include the full path to the file, including the file name, * to allow rule selection based on file name or path. * The buffer passed in should contain extended attribute data * that was obtained by a previous call to gpfs_fgetattrs. * The flags parameter must be zero (reserved for future use). * * Input: flags Define behavior of put attributes * See flag definition above. * * Returns: 0 Successful * -1 Failure * * Errno: ENOSYS function not available * EINVAL the buffer does not contain valid attribute data */ int gpfs_fputattrswithpathname(int fileDesc, int flags, void *buffer, const char *pathName); /* NAME: gpfs_get_fssnaphandle_by_path() * * FUNCTION: Get a volatile handle to uniquely identify a filesystem * and snapshot by the path to the file system and snapshot * * Input: pathName: path to a file or directory in a gpfs file system * or to one of its snapshots * * Returns: pointer to gpfs_fssnap_handle_t (Successful) * NULL and errno is set (Failure) * * Errno: ENOSYS function not available * ENOENT invalid pathname * see system calls open(), fstatfs(), and malloc() ERRORS */ gpfs_fssnap_handle_t * gpfs_get_fssnaphandle_by_path(const char *pathName); /* NAME: gpfs_get_fssnaphandle_by_name() * * FUNCTION: Get a volatile handle to uniquely identify a filesystem * and snapshot by the file system name and snapshot name. * * Input: fsName: unique name for gpfs file system (may be specified * as fsName or /dev/fsName) * snapName: name for snapshot within that file system * or NULL to access the active file system rather * than a snapshot within the file system. * * Returns: pointer to gpfs_fssnap_handle_t (Successful) * NULL and errno is set (Failure) * * Errno: ENOSYS function not available * ENOENT invalid file system name * GPFS_E_INVAL_SNAPNAME invalid snapshot name * see system calls open(), fstatfs(), and malloc() ERRORS */ gpfs_fssnap_handle_t * gpfs_get_fssnaphandle_by_name(const char *fsName, const char *snapName); /* NAME: gpfs_get_fssnaphandle_by_fssnapid() * * FUNCTION: Get a volatile handle to uniquely identify a filesystem * and snapshot by a fssnapId created from a previous handle. * * Input: fssnapId: unique id for a file system and snapshot * * Returns: pointer to gpfs_fssnaphandle_t (Successful) * NULL and errno is set (Failure) * * Errno: ENOSYS function not available * GPFS_E_INVAL_FSSNAPID invalid snapshot id * see system calls open(), fstatfs(), and malloc() ERRORS */ gpfs_fssnap_handle_t * gpfs_get_fssnaphandle_by_fssnapid(const gpfs_fssnap_id_t *fssnapId); /* NAME: gpfs_get_pathname_from_fssnaphandle() * * FUNCTION: Get the mountpoint and path to a file system * and snapshot identified by a fssnapHandle * * Input: fssnapHandle: ptr to file system & snapshot handle * * Returns: ptr to path name to the file system (Successful) * NULL and errno is set (Failure) * * Errno: ENOSYS function not available * GPFS_E_INVAL_FSSNAPHANDLE invalid fssnapHandle */ const char * gpfs_get_pathname_from_fssnaphandle(gpfs_fssnap_handle_t *fssnapHandle); /* NAME: gpfs_get_fsname_from_fssnaphandle() * * FUNCTION: Get the unique name for the file system * identified by a fssnapHandle * * Input: fssnapHandle: ptr to file system & snapshot handle * * Returns: ptr to name of the file system (Successful) * NULL and errno is set (Failure) * * Errno: ENOSYS function not available * GPFS_E_INVAL_FSSNAPHANDLE invalid fssnapHandle */ const char * gpfs_get_fsname_from_fssnaphandle(gpfs_fssnap_handle_t *fssnapHandle); /* NAME: gpfs_get_snapname_from_fssnaphandle() * * FUNCTION: Get the name for the snapshot * uniquely identified by a fssnapHandle * * Input: fssnapHandle: ptr to file system & snapshot handle * * Returns: ptr to name assigned to the snapshot (Successful) * NULL and errno is set (Failure) * * Errno: ENOSYS function not available * GPFS_E_INVAL_FSSNAPHANDLE invalid fssnaphandle * GPFS_E_INVAL_SNAPNAME snapshot has been deleted * * Notes: If the snapshot has been deleted from the file system * the snapId may still be valid, but the call will fail * with errno set to GPFS_E_INVAL_SNAPNAME. */ const char * gpfs_get_snapname_from_fssnaphandle(gpfs_fssnap_handle_t *fssnapHandle); /* NAME: gpfs_get_fssnapid_from_fssnaphandle() * * FUNCTION: Get a unique, non-volatile file system and snapshot id * for the file system and snapshot identified by a * volatile fssnap handle. * * Input: fssnapHandle: ptr to file system & snapshot handle * fssnapId: returned fssnapId uniquely identifying the * file system and snapshot being scanned * * Returns: 0 and fssnapId is set with id (Successful) * -1 and errno is set (Failure) * * Errno: GPFS_E_INVAL_FSSNAPHANDLE invalid fssnaphandle * EINVAL null ptr given for returned fssnapId * EFAULT size mismatch for fssnapId */ int gpfs_get_fssnapid_from_fssnaphandle(gpfs_fssnap_handle_t *fssnapHandle, gpfs_fssnap_id_t *fssnapId); /* NAME: gpfs_get_restore_fssnapid_from_fssnaphandle() * * FUNCTION: Get the unique, non-volatile file system and snapshot id * used for the last complete restore of a mirrored file * system. The file system must been a previous restore * target and ready for additional incremental restore. * * Input: fssnapHandle: ptr to file system & snapshot handle * fssnapId: returned fssnapId uniquely identifying the * last complete restored file system. * * Returns: 0 and fssnapId is set with id (Successful) * -1 and errno is set (Failure) * * Errno: GPFS_E_INVAL_FSSNAPHANDLE invalid fssnaphandle * EINVAL null ptr given for returned fssnapId * EFAULT size mismatch for fssnapId * EPERM caller must have superuser priviledges * ENOMEM unable to allocate memory for request * GPFS_E_FS_NOT_RESTORABLE fs is not clean for restore */ int gpfs_get_restore_fssnapid_from_fssnaphandle(gpfs_fssnap_handle_t *fssnapHandle, gpfs_fssnap_id_t *fssnapId); /* NAME: gpfs_free_fssnaphandle() * * FUNCTION: Free a fssnapHandle * * Input: fssnapHandle: ptr to file system & snapshot handle * * Returns: void * * Errno: None */ void gpfs_free_fssnaphandle(gpfs_fssnap_handle_t *fssnapHandle); /* NAME: gpfs_get_snapdirname() * * FUNCTION: Get the name of the directory containing snapshots. * * Input: fssnapHandle: handle for the file system * snapdirName: buffer into which the name of the snapshot * directory will be copied * bufLen: the size of the provided buffer * * Returns: 0 (Successful) * -1 and errno is set (Failure) * * Errno: ENOSYS function not available * EPERM caller must have superuser priviledges * ESTALE cached fs information was invalid * ENOMEM unable to allocate memory for request * GPFS_E_INVAL_FSSNAPHANDLE fssnapHandle is invalid * E2BIG buffer too small to return the snapshot directory name */ int gpfs_get_snapdirname(gpfs_fssnap_handle_t *fssnapHandle, char *snapdirName, int bufLen); /* NAME: gpfs_open_inodescan() * * FUNCTION: Open inode file for inode scan. * * Input: fssnapHandle: handle for file system and snapshot * to be scanned * prev_fssnapId: if NULL, all inodes of existing file will * be returned; if non-null, only returns inodes of files * that have changed since the specified previous snapshot * maxIno: if non-null, returns the maximum inode number * available in the inode file being scanned. * * Returns: pointer to gpfs_iscan_t (Successful) * NULL and errno is set (Failure) * * Errno: ENOSYS function not available * EINVAL bad parameters * EPERM caller must have superuser priviledges * ESTALE cached fs information was invalid * ENOMEM unable to allocate memory for request * GPFS_E_INVAL_FSSNAPHANDLE fssnapHandle is invalid * GPFS_E_INVAL_FSSNAPID prev_fssnapId is invalid * EDOM prev_fssnapId is from a different fs * ERANGE prev_fssnapId is same as or more recent than snapId * being scanned * see system calls dup() and malloc() ERRORS */ gpfs_iscan_t * gpfs_open_inodescan(gpfs_fssnap_handle_t *fssnapHandle, const gpfs_fssnap_id_t *prev_fssnapId, gpfs_ino_t *maxIno); /* NAME: gpfs_next_inode() * * FUNCTION: Get next inode from inode scan. Scan terminates before * the last inode specified or the last inode in the * inode file being scanned. * * Input: iscan: ptr to inode scan descriptor * termIno: scan terminates before this inode number * caller may specify maxIno from gpfs_open_inodescan() * or 0 to scan the entire inode file. * iattr: pointer to returned pointer to file's iattr. * * Returns: 0 and *iattr set to point to gpfs_iattr_t (Successful) * 0 and *iattr set to NULL for no more inodes before termIno * -1 and errno is set (Failure) * * Errno: ENOSYS function not available * EPERM caller must have superuser priviledges * ESTALE cached fs information was invalid * ENOMEM buffer too small * GPFS_E_INVAL_ISCAN bad parameters * * Notes: The data returned by gpfs_next_inode() is overwritten by * subsequent calls to gpfs_next_inode() or gpfs_seek_inode(). * * The termIno parameter provides a means to partition an * inode scan such that it may be executed on more than one node. */ int gpfs_next_inode(gpfs_iscan_t *iscan, gpfs_ino_t termIno, const gpfs_iattr_t **iattr); /* NAME: gpfs_seek_inode() * * FUNCTION: Seek to a given inode number. * * Input: iscan: ptr to inode scan descriptor * ino: next inode number to be scanned * * Returns: 0 Successful * -1 Failure and errno is set * * Errno: ENOSYS function not available * GPFS_E_INVAL_ISCAN bad parameters */ int gpfs_seek_inode(gpfs_iscan_t *iscan, gpfs_ino_t ino); /* NAME: gpfs_close_inodescan() * * FUNCTION: Close inode file. * * Input: iscan: ptr to inode scan descriptor * * Returns: void * * Errno: None */ void gpfs_close_inodescan(gpfs_iscan_t *iscan); /* NAME: gpfs_cmp_fssnapid() * * FUNCTION: Compare two fssnapIds for the same file system to * determine the order in which the two snapshots were taken. * The 'result' variable will be set as follows: * *result < 0: snapshot 1 was taken before snapshot 2 * *result == 0: snapshot 1 and 2 are the same * *result > 0: snapshot 1 was taken after snapshot 2 * * Input: fssnapId1: ptr to fssnapId 1 * fssnapId2: ptr to fssnapId id 2 * result: ptr to returned results * * Returns: 0 and *result is set as described above (Successful) * -1 and errno is set (Failure) * * Errno: ENOSYS function not available * GPFS_E_INVAL_FSSNAPID fssnapid1 or fssnapid2 is not a * valid snapshot id * EDOM the two snapshots cannot be compared because * they were taken from two different file systems. */ int gpfs_cmp_fssnapid(const gpfs_fssnap_id_t *fssnapId1, const gpfs_fssnap_id_t *fssnapId2, int *result); /* NAME: gpfs_iopen() * * FUNCTION: Open a file or directory by inode number. * * Input: fssnapHandle: handle for file system and snapshot * being scanned * ino: inode number * open_flags: O_RDONLY for gpfs_iread() * O_WRONLY for gpfs_iwrite() * O_CREAT create the file if it doesn't exist * O_TRUNC if the inode already exists delete it * caller may use GPFS_O_BACKUP to read files for backup * and GPFS_O_RESTORE to write files for restore * statxbuf: used only with O_CREAT/GPFS_O_BACKUP * all other cases set to NULL * symLink: used only with O_CREAT/GPFS_O_BACKUP for a symbolic link * all other cases set to NULL * * Returns: pointer to gpfs_ifile_t (Successful) * NULL and errno is set (Failure) * * Errno: ENOSYS function not available * EINVAL missing or bad parameter * EPERM caller must have superuser priviledges * ESTALE cached fs information was invalid * ENOMEM unable to allocate memory for request * EFORMAT invalid fs version number * EIO error reading original inode * GPFS_E_INVAL_IATTR iattr structure was corrupted * see dup() and malloc() ERRORS */ gpfs_ifile_t * gpfs_iopen(gpfs_fssnap_handle_t *fssnapHandle, gpfs_ino_t ino, int open_flags, const gpfs_iattr_t *statxbuf, const char *symLink); /* Define gpfs_iopen flags as used by the backup & restore by inode. The backup code will only read the source files. The restore code writes the target files & creates them if they don't already exist. The file length is set by the inode attributes. Consequently, to restore a user file it is unnecessary to include the O_TRUNC flag. */ #define GPFS_O_BACKUP (O_RDONLY) #define GPFS_O_RESTORE (O_WRONLY | O_CREAT) /* NAME: gpfs_iread() * * FUNCTION: Read file opened by gpfs_iopen. * * Input: ifile: pointer to gpfs_ifile_t from gpfs_iopen * buffer: buffer for data to be read * bufferSize: size of buffer (ie amount of data to be read) * In/Out offset: offset of where within the file to read * if successful, offset will be updated to the * next byte after the last one that was read * * Returns: number of bytes read (Successful) * -1 and errno is set (Failure) * * Errno: ENOSYS function not available * EISDIR file is a directory * EPERM caller must have superuser priviledges * ESTALE cached fs information was invalid * GPFS_E_INVAL_IFILE bad ifile parameters * see system call read() ERRORS */ int gpfs_iread(gpfs_ifile_t *ifile, void *buffer, int bufferSize, gpfs_off64_t *offset); /* NAME: gpfs_iwrite() * * FUNCTION: Write file opened by gpfs_iopen. * * Input: ifile: pointer to gpfs_ifile_t from gpfs_iopen * buffer: the data to be written * writeLen: how much to write * In/Out offset: offset of where within the file to write * if successful, offset will be updated to the * next byte after the last one that was written * * Returns: number of bytes written (Successful) * -1 and errno is set (Failure) * * Errno: ENOSYS function not available * EISDIR file is a directory * EPERM caller must have superuser priviledges * ESTALE cached fs information was invalid * GPFS_E_INVAL_IFILE bad ifile parameters * see system call write() ERRORS */ int gpfs_iwrite(gpfs_ifile_t *ifile, void *buffer, int writeLen, gpfs_off64_t *offset); /* NAME: gpfs_ireaddir() * * FUNCTION: Get next directory entry. * * Input: idir: pointer to gpfs_ifile_t from gpfs_iopen * dirent: pointer to returned pointer to directory entry * * Returns: 0 and pointer to gpfs_direntx set (Successful) * 0 and pointer to gpfs_direntx set to NULL (End of directory) * -1 and errno is set (Failure) * * Errno: ENOSYS function not available * ENOTDIR file is not a directory * EPERM caller must have superuser priviledges * ESTALE cached fs information was invalid * GPFS_E_INVAL_IFILE bad ifile parameter * ENOMEM unable to allocate memory for request * * Notes: The data returned by gpfs_ireaddir() is overwritten by * subsequent calls to gpfs_ireaddir(). */ int gpfs_ireaddir(gpfs_ifile_t *idir, const gpfs_direntx_t **dirent); /* NAME: gpfs_iwritedir() * * FUNCTION: Create a directory entry in a directory opened by gpfs_iopen. * * Input: idir: pointer to gpfs_ifile_t from gpfs_iopen * dirent: directory entry to be written * * Returns: 0 (Successful) * -1 and errno is set (Failure) * * Errno: ENOSYS function not available * GPFS_E_INVAL_IFILE bad file pointer * ENOTDIR file is not a directory * EPERM caller must have superuser priviledges * ESTALE cached fs information was invalid * ENOMEM unable to allocate memory for request * EFORMAT invalid dirent version number * see system call write() ERRORS */ int gpfs_iwritedir(gpfs_ifile_t *idir, const gpfs_direntx_t *dirent); /* NAME: gpfs_igetattrs() * * FUNCTION: Retrieves all extended file attributes in opaque format. * This function together with gpfs_iputattrs is intended for * use by a backup program to save (gpfs_igetattrs) and * restore (gpfs_iputattrs) all extended file attributes * (ACLs, dmapi attributes, ...) in one call. * * Input: ifile: pointer to gpfs_ifile_t from gpfs_iopen * buffer: pointer to buffer for returned attributes * bufferSize: size of buffer * attrSize: ptr to returned size of attributes * * Returns: 0 Successful * -1 Failure and errno is set * * Errno: ENOSYS function not available * EPERM caller must have superuser priviledges * ESTALE cached fs information was invalid * ENOSPC buffer too small to return all attributes * *attrSizeP will be set to the size necessary * GPFS_E_INVAL_IFILE bad ifile parameters */ int gpfs_igetattrs(gpfs_ifile_t *ifile, void *buffer, int bufferSize, int *attrSize); /* NAME: gpfs_iputattrs() * * FUNCTION: Sets all extended file attributes of a file. * The buffer passed in should contain extended attribute data * that was obtained by a previous call to gpfs_igetattrs. * * Input: ifile: pointer to gpfs_ifile_t from gpfs_iopen * buffer: pointer to buffer for returned attributes * * Returns: 0 Successful * -1 Failure and errno is set * * Errno: ENOSYS function not available * EINVAL the buffer does not contain valid attribute data * EPERM caller must have superuser priviledges * ESTALE cached fs information was invalid * GPFS_E_INVAL_IFILE bad ifile parameters */ int gpfs_iputattrs(gpfs_ifile_t *ifile, void *buffer); /* NAME: gpfs_igetfilesetname() * * FUNCTION: Retrieves the name of the fileset which contains this file. * The fileset name is a null-terminated string, with a * a maximum length of GPFS_MAXNAMLEN. * * Input: iscan: ptr to gpfs_iscan_t from gpfs_open_inodescan() * filesetId: ia_filesetId returned in an iattr from the iscan * buffer: pointer to buffer for returned fileset name * bufferSize: size of buffer * * Returns: 0 Successful * -1 Failure and errno is set * * Errno: ENOSYS function not available * EPERM caller must have superuser priviledges * ESTALE cached fs information was invalid * ENOSPC buffer too small to return fileset name * GPFS_E_INVAL_ISCAN bad iscan parameter */ int gpfs_igetfilesetname(gpfs_iscan_t *iscan, unsigned int filesetId, void *buffer, int bufferSize); /* NAME: gpfs_igetstoragepool() * * FUNCTION: Retrieves the name of the storage pool assigned for * this file's data. The storage pool name is a null-terminated * string, with a maximum length of GPFS_MAXNAMLEN. * * Input: iscan: ptr to gpfs_iscan_t from gpfs_open_inodescan() * dataPoolId: ia_dataPoolId returned in an iattr from the iscan * buffer: pointer to buffer for returned attributes * bufferSize: size of buffer * * Returns: 0 Successful * -1 Failure and errno is set * * Errno: ENOSYS function not available * EPERM caller must have superuser priviledges * ESTALE cached fs information was invalid * ENOSPC buffer too small to return all storage pool name * GPFS_E_INVAL_ISCAN bad iscan parameters */ int gpfs_igetstoragepool(gpfs_iscan_t *iscan, unsigned int dataPoolId, void *buffer, int bufferSize); /* NAME: gpfs_iclose() * * FUNCTION: Close file opened by inode and update dates. * * Input: ifile: pointer to gpfs_ifile_t from gpfs_iopen * * Returns: void * * Errno: ENOSYS function not available * EPERM caller must have superuser priviledges * ESTALE cached fs information was invalid */ void gpfs_iclose(gpfs_ifile_t *ifile); /* NAME: gpfs_ireadlink() * * FUNCTION: Read symbolic link by inode number. * * Input: fssnapHandle: handle for file system & snapshot being scanned * ino: inode number of link file to read * buffer: pointer to buffer for returned link data * bufferSize: size of the buffer * * Returns: number of bytes read (Successful) * -1 and errno is set (Failure) * * Errno: ENOSYS function not available * EPERM caller must have superuser priviledges * ESTALE cached fs information was invalid * GPFS_E_INVAL_FSSNAPHANDLE invalid fssnap handle * see system call readlink() ERRORS */ int gpfs_ireadlink(gpfs_fssnap_handle_t *fssnapHandle, gpfs_ino_t ino, char *buffer, int bufferSize); /* NAME: gpfs_sync_fs() * * FUNCTION: sync file system. * * Input: fssnapHandle: handle for file system being restored * * Returns: 0 all data flushed to disk (Successful) * -1 and errno is set (Failure) * * Errno: ENOSYS function not available * ENOMEM unable to allocate memory for request * EPERM caller must have superuser priviledges * ESTALE cached fs information was invalid * GPFS_E_INVAL_FSSNAPHANDLE invalid fssnapHandle */ int gpfs_sync_fs(gpfs_fssnap_handle_t *fssnapHandle); /* NAME: gpfs_enable_restore() * * FUNCTION: Mark file system as enabled for restore on/off * * Input: fssnapHandle: handle for file system to be enabled * or disabled for restore * on_off: flag set to 1 to enable restore * 0 to disable restore * * Returns: 0 (Successful) * -1 and errno is set (Failure) * * Errno: ENOSYS function not available * EINVAL bad parameters * GPFS_E_INVAL_FSSNAPHANDLE invalid fssnapHandle * EPERM caller must have superuser priviledges * ESTALE cached fs information was invalid * ENOMEM unable to allocate memory for request * E_FS_NOT_RESTORABLE fs is not clean * EALREADY fs already marked as requested * E_RESTORE_STARTED restore in progress * * Notes: EALREADY indicates enable/disable restore was already called * for this fs. The caller must decide if EALREADY represents an * error condition. */ int gpfs_enable_restore(gpfs_fssnap_handle_t *fssnapHandle, int on_off); /* NAME: gpfs_start_restore() * * FUNCTION: Start a restore session. * * Input: fssnapHandle: handle for file system to be restored * restore_flags: Flag to indicate the restore should be started * even if a prior restore has not completed. * old_fssnapId: fssnapId of last restored snapshot * new_fssnapId: fssnapId of snapshot being restored * * Returns: pointer to gpfs_restore_t (Successful) * NULL and errno is set (Failure) * * Errno: ENOSYS function not available * ENOMEM unable to allocate memory for request * EINVAL missing parameter * EPERM caller must have superuser priviledges * ESTALE cached fs information was invalid * EDOM restore fs does not match existing fs * ERANGE restore is missing updates * EFORMAT invalid fs version number * GPFS_E_INVAL_FSSNAPHANDLE invalid fssnaphandle * GPFS_E_INVAL_FSSNAPID bad fssnapId parameter * E_FS_NOT_RESTORABLE fs is not clean for restore * E_RESTORE_NOT_ENABLED fs is not enabled for restore * EALREADY Restore already in progress * * Note: EALREADY indicates start restore was already called for * this fs. This could be due to a prior restore process that failed * or it could be due to a concurrent restore process still running. * The caller must decide if EALREADY represents an error condition. */ gpfs_restore_t * gpfs_start_restore(gpfs_fssnap_handle_t *fssnapHandle, int restore_flags, const gpfs_fssnap_id_t *old_fssnapId, const gpfs_fssnap_id_t *new_fssnapId); #define GPFS_RESTORE_NORMAL 0 /* Restore not started if prior restore has not completed. */ #define GPFS_RESTORE_FORCED 1 /* Restore starts even if prior restore has not completed. */ /* NAME: gpfs_end_restore() * * FUNCTION: End a restore session. * * Input: restoreId: ptr to gpfs_restore_t * * Returns: 0 (Successful) * -1 and errno is set (Failure) * * Errno: ENOSYS function not available * EINVAL bad parameters * EPERM caller must have superuser priviledges * ESTALE cached fs information was invalid * GPFS_E_INVAL_RESTORE bad restoreId parameter * GPFS_E_FS_NOT_RESTORABLE fs is not clean for restore * GPFS_E_RESTORE_NOT_ENABLED fs is not enabled for restore * EALREADY Restore already ended * * Note: EALREADY indicates end restore was already called for * this fs. This could be due to a concurrent restore process that * already completed. The caller must decide if EALREADY represents * an error condition. */ int gpfs_end_restore(gpfs_restore_t *restoreId); /* NAME: gpfs_ireadx() * * FUNCTION: Block level incremental read on a file opened by gpfs_iopen * with a given incremental scan opened via gpfs_open_inodescan. * * Input: ifile: ptr to gpfs_file_t returned from gpfs_iopen() * iscan: ptr to gpfs_iscan_t from gpfs_open_inodescan() * buffer: ptr to buffer for returned data * bufferSize: size of buffer for returned data * offset: ptr to offset value * termOffset: read terminates before reading this offset * caller may specify ia_size for the file's gpfs_iattr_t * or 0 to scan the entire file. * hole: ptr to returned flag to indicate a hole in the file * * Returns: number of bytes read and returned in buffer * or size of hole encountered in the file. (Success) * -1 and errno is set (Failure) * * On input, *offset contains the offset in the file * at which to begin reading to find a difference same file * in a previous snapshot specified when the inodescan was opened. * On return, *offset contains the offset of the first * difference. * * On return, *hole indicates if the change in the file * was data (*hole == 0) and the data is returned in the * buffer provided. The function's value is the amount of data * returned. If the change is a hole in the file, * *hole != 0 and the size of the changed hole is returned * as the function value. * * A call with a NULL buffer pointer will query the next increment * to be read from the current offset. The *offset, *hole and * returned length will be set for the next increment to be read, * but no data will be returned. The bufferSize parameter is * ignored, but the termOffset parameter will limit the * increment returned. * * Errno: ENOSYS function not available * EINVAL missing or bad parameter * EISDIR file is a directory * EPERM caller must have superuser priviledges * ESTALE cached fs information was invalid * ENOMEM unable to allocate memory for request * EDOM fs snapId does match local fs * ERANGE previous snapId is more recent than scanned snapId * GPFS_E_INVAL_IFILE bad ifile parameter * GPFS_E_INVAL_ISCAN bad iscan parameter * see system call read() ERRORS * * Notes: The termOffset parameter provides a means to partition a * file's data such that it may be read on more than one node. */ gpfs_off64_t gpfs_ireadx(gpfs_ifile_t *ifile, /* in only */ gpfs_iscan_t *iscan, /* in only */ void *buffer, /* in only */ int bufferSize, /* in only */ gpfs_off64_t *offset, /* in/out */ gpfs_off64_t termOffset, /* in only */ int *hole); /* out only */ /* NAME: gpfs_iwritex() * * FUNCTION: Write file opened by gpfs_iopen. * If parameter hole == 0, then write data * addressed by buffer to the given offset for the * given length. If hole != 0, then write * a hole at the given offset for the given length. * * Input: ifile : ptr to gpfs_file_t returned from gpfs_iopen() * buffer: ptr to data buffer * writeLen: length of data to write * offset: offset in file to write data * hole: flag =1 to write a "hole" * =0 to write data * * Returns: number of bytes/size of hole written (Success) * -1 and errno is set (Failure) * * Errno: ENOSYS function not available * EINVAL missing or bad parameter * EISDIR file is a directory * EPERM caller must have superuser priviledges * ESTALE cached fs information was invalid * GPFS_E_INVAL_IFILE bad ifile parameter * see system call write() ERRORS */ gpfs_off64_t gpfs_iwritex(gpfs_ifile_t *ifile, /* in only */ void *buffer, /* in only */ gpfs_off64_t writeLen, /* in only */ gpfs_off64_t offset, /* in only */ int hole); /* in only */ /* NAME: gpfs_statfspool() * * FUNCTION: Obtain status information about the storage pools * * Input: pathname : path to any file in the file system * poolId : id of first pool to return * on return set to next poolId or -1 * to indicate there are no more pools. * options : option flags (currently not used) * nPools : number of stat structs requested or 0 * on return number of stat structs in buffer * or if nPools was 0 its value is the max number * of storage pools currently defined * buffer : ptr to return stat structures * bufferSize : sizeof stat buffer * * The user is expected to issue two or more calls. On the first * call the user should pass nPools set to 0 and gpfs will * return in nPools the total number of storage pools currently * defined for the file system indicated by the pathname * and it returns in poolId the id of the first storage pool. * The buffer parameter may be set to NULL for this call. * * The user may then allocate a buffer large enough to contain * a gpfs_statpool_t structure for each of the pools and issue * a second call to obtain stat information about each pool. * Parameter nPools should be set the number of pools requested. * On return, nPools will be set to the number of stat structs * contained in the buffer, and poolId will be set to the id * of the next storage pool or -1 to indicate there are no * additional storage pools defined. * * Alternatively, if the user has a valid poolId from a previous * call, the user may provide that poolId and a buffer large * enough for a single gpfs_statpool_t structure, and the call * will return the status for a single storage pool. * * * Returns: 0 Successful * -1 Failure * * Errno: Specific error indication * EINVAL */ int gpfs_statfspool(const char *pathname, /* in only: path to file system*/ gpfs_pool_t *poolId, /* in out: id of first pool to return on return set to next poolId or -1 when there are no more pools */ unsigned int options, /* in only: option flags */ int *nPools, /* in out: number of pool stats requested on return number of stat structs returned in buffer or if nPools was set to 0, the return value is the number of pools currently defined */ void *buffer, /* ptr to return stat structures */ int bufferSize); /* sizeof stat buffer or 0 */ /* NAME: gpfs_getpoolname() * * FUNCTION: Retrieves the name of the storage pool assigned for * this file's data. The storage pool name is a null-terminated * string, with a maximum length of GPFS_MAXNAMLEN. * * Input: pathname: path to any file in the file system * poolId: f_poolid returned in gpfs_statfspool_t * buffer: pointer to buffer for returned name * bufferSize: size of buffer * * Returns: 0 Successful * -1 Failure and errno is set * * Errno: ENOSYS function not available * ESTALE file system was unmounted * E_FORMAT_INCOMPAT file system does not support pools * E2BIG buffer too small to return storage pool name */ int gpfs_getpoolname(const char *pathname, gpfs_pool_t poolId, void *buffer, int bufferSize); /* GPFS QUOTACTL */ /* * Command definitions for the 'gpfs_quotactl' system call. * The commands are broken into a main command defined below * and a subcommand that is used to convey the type of * quota that is being manipulated (see above). */ #define SUBCMDMASK 0x00ff #define SUBCMDSHIFT 8 #define QCMD(cmd, type) (((cmd) << SUBCMDSHIFT) | ((type) & SUBCMDMASK)) #define Q_QUOTAON 0x0100 /* enable quotas */ #define Q_QUOTAOFF 0x0200 /* disable quotas */ #define Q_GETQUOTA 0x0300 /* get limits and usage */ #ifndef _LINUX_SOURCE_COMPAT /* Standard AIX definitions of quota commands */ #define Q_SETQUOTA 0x0400 /* set limits */ #define Q_SETQLIM Q_SETQUOTA #else /* Alternate definitions, for Linux Affinity */ #define Q_SETQLIM 0x0400 /* set limits */ #define Q_SETQUOTA 0x0700 /* set limits and usage */ #endif #define Q_SETUSE 0x0500 /* set usage */ #define Q_SYNC 0x0600 /* sync disk copy of a filesystems quotas */ /* gpfs quota types */ #define GPFS_USRQUOTA 0 #define GPFS_GRPQUOTA 1 #define GPFS_FILESETQUOTA 2 typedef struct gpfs_quotaInfo { gpfs_off64_t blockUsage; /* current block count in 1 KB units*/ gpfs_off64_t blockHardLimit; /* absolute limit on disk blks alloc */ gpfs_off64_t blockSoftLimit; /* preferred limit on disk blks */ gpfs_off64_t blockInDoubt; /* distributed shares + "lost" usage for blks */ int inodeUsage; /* current # allocated inodes */ int inodeHardLimit; /* absolute limit on allocated inodes */ int inodeSoftLimit; /* preferred inode limit */ int inodeInDoubt; /* distributed shares + "lost" usage for inodes */ gpfs_uid_t quoId; /* uid, gid or fileset id */ int entryType; /* entry type, not used */ unsigned int blockGraceTime; /* time limit for excessive disk use */ unsigned int inodeGraceTime; /* time limit for excessive inode use */ } gpfs_quotaInfo_t; /* * NAME: gpfs_quotactl * * FUNCTION: Manipulate disk quotas * INPUT: pathname: specifies the pathname of any file within the * mounted file system to which the command is to * be applied * cmd: specifies a quota control command to be applied * to UID/GID/FILESETID id. * the cmd parameter can be constructed using QCMD(cmd, type) * macro defined in gpfs.h * of quota. * id: UID or GID or FILESETID that command applied to. * bufferP: points to the address of an optional, command * specific, data structure that is copied in or out of * the system. * * OUTPUT: bufferP, if applicable. * * Returns: 0 success * -1 failure * * Errno: EACCESS * EFAULT An invalid bufferP parameter is supplied; * the associated structure could not be copied * in or out of the kernel * EINVAL * ENOENT No such file or directory * EPERM The quota control command is privileged and * the caller did not have root user authority * EOPNOTSUPP * E_NO_QUOTA_INST The file system does not support quotas */ int gpfs_quotactl(char *pathname, int cmd, int id, void *bufferP); #ifdef __cplusplus } #endif #endif /* H_GPFS */