1 /* */ 2 /* Copyright (C) 2001 International Business Machines */ 3 /* All rights reserved. */ 4 /* */ 5 /* This file is part of the GPFS user library. */ 6 /* */ 7 /* Redistribution and use in source and binary forms, with or without */ 8 /* modification, are permitted provided that the following conditions */ 9 /* are met: */ 10 /* */ 11 /* 1. Redistributions of source code must retain the above copyright notice, */ 12 /* this list of conditions and the following disclaimer. */ 13 /* 2. Redistributions in binary form must reproduce the above copyright */ 14 /* notice, this list of conditions and the following disclaimer in the */ 15 /* documentation and/or other materials provided with the distribution. */ 16 /* 3. The name of the author may not be used to endorse or promote products */ 17 /* derived from this software without specific prior written */ 18 /* permission. */ 19 /* */ 20 /* THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR */ 21 /* IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES */ 22 /* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. */ 23 /* IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, */ 24 /* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, */ 25 /* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; */ 26 /* OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, */ 27 /* WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR */ 28 /* OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF */ 29 /* ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ 30 /* */ 31 /* @(#)42 1.1.12.3 src/avs/fs/mmfs/ts/util/gpfs.h, mmfs, avs_rttn423, rttn423s001a 4/10/17 10:46:33 */ 32 /* 33 * Library calls for GPFS interfaces 34 */ 35 #ifndef H_GPFS 36 #define H_GPFS 37 38 #include <stddef.h> 39 40 /* Define GPFS_64BIT_INODES to map the default interface definitions 41 to 64-bit interfaces. Without this define, the 32-bit interface 42 is the default. Both interfaces are always present, but the 43 define sets the default. The actual mapping can be found near the 44 end of this header. */ 45 /* #define GPFS_64BIT_INODES 1 */ 46 47 #define NFS_IP_SIZE 32 48 49 #ifdef __cplusplus 50 extern "C" { 51 #endif 52 53 #if defined(WIN32) && defined(GPFSDLL) 54 55 /* The following errno values either are missing from Windows errno.h or 56 have a conflicting value. Other errno values (e.g. EPERM) are okay. */ 57 #define GPFS_EALREADY 37 /* Operation already in progress */ 58 #define GPFS_EOPNOTSUPP 45 /* Operation not supported */ 59 #define GPFS_EDQUOT 69 /* Disk quota exceeded */ 60 #define GPFS_ESTALE 9 /* No file system (mapped to EBADF) */ 61 #define GPFS_EFORMAT 19 /* Unformatted media (mapped to ENODEV) */ 62 63 /* specify the library calling convention */ 64 #define GPFS_API __stdcall 65 66 /* On Windows, this is a HANDLE as returned by CreateFile() */ 67 typedef void* gpfs_file_t; 68 69 #else /* not gpfs.dll on Windows */ 70 71 #define GPFS_API 72 /* On UNIX systems, this is a file descriptor as returned by open() */ 73 typedef int gpfs_file_t; 74 75 #endif 76 77 78 typedef unsigned int gpfs_uid_t; 79 typedef long long gpfs_off64_t; 80 typedef unsigned long long gpfs_uid64_t; 81 82 typedef struct gpfs_timestruc 83 { 84 unsigned int tv_sec; 85 unsigned int tv_nsec; 86 } gpfs_timestruc_t; 87 88 typedef struct gpfs_timestruc64 89 { 90 long long tv_sec; 91 unsigned int tv_nsec; 92 } gpfs_timestruc64_t; 93 94 #define GPFS_SLITE_SIZE_BIT 0x00000001 95 #define GPFS_SLITE_BLKSIZE_BIT 0x00000002 96 #define GPFS_SLITE_BLOCKS_BIT 0x00000004 97 #define GPFS_SLITE_ATIME_BIT 0x00000010 98 #define GPFS_SLITE_MTIME_BIT 0x00000020 99 #define GPFS_SLITE_CTIME_BIT 0x00000040 100 #define GPFS_SLITE_EXACT_BITS 0x00000077 101 102 /* Returns "1" if the attribute is requested to be accurate. 103 (On output, indicates the value returned in statbufP is accurate). */ 104 #define GPFS_SLITE(m) (0 == (m)) 105 #define GPFS_SLITE_SIZET(m) (0 != ((m) & GPFS_SLITE_SIZE_BIT)) 106 #define GPFS_SLITE_BLKSIZE(m) (0 != ((m) & GPFS_SLITE_BLKSIZE_BIT)) 107 #define GPFS_SLITE_BLOCKS(m) (0 != ((m) & GPFS_SLITE_BLOCKS_BIT)) 108 #define GPFS_SLITE_ATIME(m) (0 != ((m) & GPFS_SLITE_ATIME_BIT)) 109 #define GPFS_SLITE_MTIME(m) (0 != ((m) & GPFS_SLITE_MTIME_BIT)) 110 #define GPFS_SLITE_CTIME(m) (0 != ((m) & GPFS_SLITE_CTIME_BIT)) 111 #define GPFS_SLITE_EXACT(m) (GPFS_SLITE_EXACT_BITS == (m)) 112 113 /* Sets the litemask bit indicating that the attribute should be accurate */ 114 #define GPFS_S_SLITE(m) (m) = 0 115 #define GPFS_S_SLITE_SIZET(m) (m) |= GPFS_SLITE_SIZE_BIT 116 #define GPFS_S_SLITE_BLKSIZE(m) (m) |= GPFS_SLITE_BLKSIZE_BIT 117 #define GPFS_S_SLITE_BLOCKS(m) (m) |= GPFS_SLITE_BLOCKS_BIT 118 #define GPFS_S_SLITE_ATIME(m) (m) |= GPFS_SLITE_ATIME_BIT 119 #define GPFS_S_SLITE_MTIME(m) (m) |= GPFS_SLITE_MTIME_BIT 120 #define GPFS_S_SLITE_CTIME(m) (m) |= GPFS_SLITE_CTIME_BIT 121 #define GPFS_S_SLITE_EXACT(m) (m) |= GPFS_SLITE_EXACT_BITS 122 123 #define GPFS_STATLITE 0 124 #define GPFS_NOFOLLOW 1 125 126 /* Mapping of buffer for gpfs_getacl, gpfs_putacl. */ 127 typedef struct gpfs_opaque_acl 128 { 129 int acl_buffer_len; /* INPUT: Total size of buffer (including this field). 130 OUTPUT: Actual size of the ACL information. */ 131 unsigned short acl_version; /* INPUT: Set to zero. 132 OUTPUT: Current version of the returned ACL. */ 133 unsigned char acl_type; /* INPUT: Type of ACL: access (1) or default (2). */ 134 char acl_var_data[1]; /* OUTPUT: Remainder of the ACL information. */ 135 } gpfs_opaque_acl_t; 136 137 /* ACL types (acl_type field in gpfs_opaque_acl_t or gpfs_acl_t) */ 138 #define GPFS_ACL_TYPE_ACCESS 1 139 #define GPFS_ACL_TYPE_DEFAULT 2 140 #define GPFS_ACL_TYPE_NFS4 3 141 142 /* gpfs_getacl, gpfs_putacl flag indicating structures instead of the 143 opaque style data normally used. */ 144 #define GPFS_GETACL_STRUCT 0x00000020 145 #define GPFS_PUTACL_STRUCT 0x00000020 146 147 /* gpfs_getacl, gpfs_putacl flag indicating smbd is the caller */ 148 #define GPFS_ACL_SAMBA 0x00000040 149 150 /* Defined values for gpfs_aclVersion_t */ 151 #define GPFS_ACL_VERSION_POSIX 1 152 #define GPFS_ACL_VERSION_NFS4F 3 /* GPFS_ACL_VERSION_NFS4 plus V4FLAGS */ 153 #define GPFS_ACL_VERSION_NFS4 4 154 155 /* Values for gpfs_aclLevel_t */ 156 #define GPFS_ACL_LEVEL_BASE 0 /* compatible with all acl_version values */ 157 #define GPFS_ACL_LEVEL_V4FLAGS 1 /* requires GPFS_ACL_VERSION_NFS4 */ 158 159 /* Values for gpfs_aceType_t (ACL_VERSION_POSIX) */ 160 #define GPFS_ACL_USER_OBJ 1 161 #define GPFS_ACL_GROUP_OBJ 2 162 #define GPFS_ACL_OTHER 3 163 #define GPFS_ACL_MASK 4 164 #define GPFS_ACL_USER 5 165 #define GPFS_ACL_GROUP 6 166 167 /* Values for gpfs_acePerm_t (ACL_VERSION_POSIX) */ 168 #define ACL_PERM_EXECUTE 001 169 #define ACL_PERM_WRITE 002 170 #define ACL_PERM_READ 004 171 #define ACL_PERM_CONTROL 010 172 173 /* Values for gpfs_aceType_t (ACL_VERSION_NFS4) */ 174 #define ACE4_TYPE_ALLOW 0 175 #define ACE4_TYPE_DENY 1 176 #define ACE4_TYPE_AUDIT 2 177 #define ACE4_TYPE_ALARM 3 178 179 /* Values for gpfs_aceFlags_t (ACL_VERSION_NFS4) */ 180 #define ACE4_FLAG_FILE_INHERIT 0x00000001 181 #define ACE4_FLAG_DIR_INHERIT 0x00000002 182 #define ACE4_FLAG_NO_PROPAGATE 0x00000004 183 #define ACE4_FLAG_INHERIT_ONLY 0x00000008 184 #define ACE4_FLAG_SUCCESSFUL 0x00000010 185 #define ACE4_FLAG_FAILED 0x00000020 186 #define ACE4_FLAG_GROUP_ID 0x00000040 187 #define ACE4_FLAG_INHERITED 0x00000080 188 189 /* GPFS-defined flags. Placed in a separate ACL field to avoid 190 ever running into newly defined NFSv4 flags. */ 191 #define ACE4_IFLAG_SPECIAL_ID 0x80000000 192 193 /* Values for gpfs_aceMask_t (ACL_VERSION_NFS4) */ 194 #define ACE4_MASK_READ 0x00000001 195 #define ACE4_MASK_LIST_DIR 0x00000001 196 #define ACE4_MASK_WRITE 0x00000002 197 #define ACE4_MASK_ADD_FILE 0x00000002 198 #define ACE4_MASK_APPEND 0x00000004 199 #define ACE4_MASK_ADD_SUBDIR 0x00000004 200 #define ACE4_MASK_READ_NAMED 0x00000008 201 #define ACE4_MASK_WRITE_NAMED 0x00000010 202 #define ACE4_MASK_EXECUTE 0x00000020 203 204 /* The rfc doesn't provide a mask equivalent to "search" ("x" on a 205 * directory in posix), but it also doesn't say that its EXECUTE 206 * is to have this dual use (even though it does so for other dual 207 * use permissions such as read/list. Going to make the assumption 208 * here that the EXECUTE bit has this dual meaning... otherwise 209 * we're left with no control over search. 210 */ 211 #define ACE4_MASK_SEARCH 0x00000020 212 213 #define ACE4_MASK_DELETE_CHILD 0x00000040 214 #define ACE4_MASK_READ_ATTR 0x00000080 215 #define ACE4_MASK_WRITE_ATTR 0x00000100 216 #define ACE4_MASK_DELETE 0x00010000 217 #define ACE4_MASK_READ_ACL 0x00020000 218 #define ACE4_MASK_WRITE_ACL 0x00040000 219 #define ACE4_MASK_WRITE_OWNER 0x00080000 220 #define ACE4_MASK_SYNCHRONIZE 0x00100000 221 #define ACE4_MASK_ALL 0x001f01ff 222 223 /* Values for gpfs_uid_t (ACL_VERSION_NFS4) */ 224 #define ACE4_SPECIAL_OWNER 1 225 #define ACE4_SPECIAL_GROUP 2 226 #define ACE4_SPECIAL_EVERYONE 3 227 228 /* per-ACL flags imported from a Windows security descriptor object */ 229 #define ACL4_FLAG_OWNER_DEFAULTED 0x00000100 230 #define ACL4_FLAG_GROUP_DEFAULTED 0x00000200 231 #define ACL4_FLAG_DACL_PRESENT 0x00000400 232 #define ACL4_FLAG_DACL_DEFAULTED 0x00000800 233 #define ACL4_FLAG_SACL_PRESENT 0x00001000 234 #define ACL4_FLAG_SACL_DEFAULTED 0x00002000 235 #define ACL4_FLAG_DACL_UNTRUSTED 0x00004000 236 #define ACL4_FLAG_SERVER_SECURITY 0x00008000 237 #define ACL4_FLAG_DACL_AUTO_INHERIT_REQ 0x00010000 238 #define ACL4_FLAG_SACL_AUTO_INHERIT_REQ 0x00020000 239 #define ACL4_FLAG_DACL_AUTO_INHERITED 0x00040000 240 #define ACL4_FLAG_SACL_AUTO_INHERITED 0x00080000 241 #define ACL4_FLAG_DACL_PROTECTED 0x00100000 242 #define ACL4_FLAG_SACL_PROTECTED 0x00200000 243 #define ACL4_FLAG_RM_CONTROL_VALID 0x00400000 244 #define ACL4_FLAG_NULL_DACL 0x00800000 245 #define ACL4_FLAG_NULL_SACL 0x01000000 246 #define ACL4_FLAG_VALID_FLAGS 0x01ffff00 247 248 249 /* Externalized ACL defintions */ 250 typedef unsigned int gpfs_aclType_t; 251 typedef unsigned int gpfs_aclLen_t; 252 typedef unsigned int gpfs_aclLevel_t; 253 typedef unsigned int gpfs_aclVersion_t; 254 typedef unsigned int gpfs_aclCount_t; 255 typedef unsigned int gpfs_aclFlag_t; 256 257 typedef unsigned int gpfs_aceType_t; 258 typedef unsigned int gpfs_aceFlags_t; 259 typedef unsigned int gpfs_acePerm_t; 260 typedef unsigned int gpfs_aceMask_t; 261 262 /* A POSIX ACL Entry */ 263 typedef struct gpfs_ace_v1 264 { 265 gpfs_aceType_t ace_type; /* POSIX ACE type */ 266 gpfs_uid_t ace_who; /* uid/gid */ 267 gpfs_acePerm_t ace_perm; /* POSIX permissions */ 268 } gpfs_ace_v1_t; 269 270 /* An NFSv4 ACL Entry */ 271 typedef struct gpfs_ace_v4 272 { 273 gpfs_aceType_t aceType; /* Allow or Deny */ 274 gpfs_aceFlags_t aceFlags; /* Inherit specifications, etc. */ 275 gpfs_aceFlags_t aceIFlags; /* GPFS Internal flags */ 276 gpfs_aceMask_t aceMask; /* NFSv4 mask specification */ 277 gpfs_uid_t aceWho; /* User/Group identification */ 278 } gpfs_ace_v4_t; 279 280 /* when GPFS_ACL_VERSION_NFS4, and GPFS_ACL_LEVEL_V4FLAGS */ 281 typedef struct v4Level1_ext /* ACL extension */ 282 { 283 gpfs_aclFlag_t acl_flags; /* per-ACL flags */ 284 gpfs_ace_v4_t ace_v4[1]; 285 } v4Level1_t; 286 287 /* The GPFS ACL */ 288 typedef struct gpfs_acl 289 { 290 gpfs_aclLen_t acl_len; /* Total length of this ACL in bytes */ 291 gpfs_aclLevel_t acl_level; /* Reserved (must be zero) */ 292 gpfs_aclVersion_t acl_version; /* POSIX or NFS4 ACL */ 293 gpfs_aclType_t acl_type; /* Access, Default, or NFS4 */ 294 gpfs_aclCount_t acl_nace; /* Number of Entries that follow */ 295 union 296 { 297 gpfs_ace_v1_t ace_v1[1]; /* when GPFS_ACL_VERSION_POSIX */ 298 gpfs_ace_v4_t ace_v4[1]; /* when GPFS_ACL_VERSION_NFS4 */ 299 v4Level1_t v4Level1; /* when GPFS_ACL_LEVEL_V4FLAGS */ 300 }; 301 } gpfs_acl_t; 302 303 304 /* NAME: gpfs_getacl() 305 * 306 * FUNCTION: Retrieves the ACL information for a file. 307 * 308 * The aclP parameter must point to a buffer mapped by either: 309 * - gpfs_opaque_acl_t (when flags are zero). In this case, 310 * the opaque data that is intended to be used by a backup 311 * program (restoreed by passing this data back on a subsequent 312 * call to gpfs_putacl). 313 * - gpfs_acl_t (when GPFS_GETACL_STRUCT is specified). In this 314 * case, the data can be interpreted by the calling application 315 * (and may be modified and applied to the file by passing it 316 * to gpfs_putacl...along with the GPFS_PUTACL_STRUCT flag). 317 * 318 * On input, the first four bytes of the buffer must contain its 319 * total size. 320 * 321 * Returns: 0 Successful 322 * -1 Failure 323 * 324 * Errno: ENOSYS function not available 325 * ENOSPC buffer too small to return the entire ACL. 326 * Needed size is returned in the first four 327 * bytes of the buffer pointed to by aclP. 328 * EINVAL Invalid arguments 329 * ENOTDIR Not on directory 330 * ENOMEM Out of memory 331 */ 332 int GPFS_API 333 gpfs_getacl(const char *pathname, 334 int flags, 335 void *acl); 336 337 338 /* NAME: gpfs_putacl() 339 * 340 * FUNCTION: Sets the ACL information for a file. 341 * The buffer passed in should contain the ACL data 342 * that was obtained by a previous call to gpfs_getacl. 343 * 344 * Returns: 0 Successful 345 * -1 Failure 346 * 347 * Errno: ENOSYS function not available 348 * EINVAL Invalid arguments 349 * ENOTDIR Not on directory 350 * ENOMEM Out of memory 351 * EPERM Caller does not hold appropriate privilege 352 */ 353 int GPFS_API 354 gpfs_putacl(const char *pathname, 355 int flags, 356 void *acl); 357 358 359 /* NAME: gpfs_prealloc() 360 * 361 * FUNCTION: Preallocate disk storage for a file or directory, starting 362 * at the specified startOffset and covering at least the number 363 * of bytes requested by bytesToPrealloc. Allocations are rounded 364 * to block boundaries (block size can be found in st_blksize 365 * returned by fstat()), or possibly larger sizes. For files, the 366 * file descriptor must be open for write, but any existing data 367 * already present will not be modified. Reading the preallocated 368 * blocks will return zeros. For directories, the file descriptor 369 * may be open for read but the caller must have write permission, 370 * and existing entries are unaffected; startOffset must be zero. 371 * 372 * This function implements the behavior of mmchattr when invoked 373 * with --compact[=minimumEntries]. The minimumEntries value 374 * specifies both the lower bound on automatic compaction and the 375 * desired size for pre-allocation. It defaults to zero, meaning 376 * no pre-allocation and compact the directory as much as 377 * possible. The mapping between minimumEntries and the 378 * bytesToPrealloc is given by GPFS_PREALLOC_DIR_SLOT_SIZE, see 379 * below. 380 * 381 * Directory compaction (zero bytesToPrealloc) requires a file 382 * system supporting V2 directories (format version 1400, v4.1). 383 * Directories created before upgrading the file system to version 384 * 4.1, are upgraded from V1 to V2 by this operation even if no 385 * other change is made. Since v4.2.2, bytesToPrealloc may be 386 * nonzero effecting pre-allocation by setting a minimum 387 * compaction size. Prior to v4.2.2 the minimum size of any 388 * directory is zero. 389 * 390 * Returns: 0 Success 391 * -1 Failure 392 * 393 * Errno: ENOSYS No prealloc service available 394 * EBADF Bad file descriptor 395 * EINVAL Not a GPFS file 396 * EINVAL Not a regular file or directory 397 * EINVAL Directory pre-allocation not supported 398 * EINVAL startOffset or bytesToPrealloc < 0 399 * EACCES File not opened for writing 400 * EACCES Caller does not have write access to directory. 401 * EDQUOT Quota exceeded 402 * ENOSPC Not enough space on disk 403 * EPERM File is in a snapshot 404 */ 405 int GPFS_API 406 gpfs_prealloc(gpfs_file_t fileDesc, 407 gpfs_off64_t startOffset, 408 gpfs_off64_t bytesToPrealloc); 409 410 /* Directory entries are nominally (assuming compact names of 19 bytes or less) 411 32 bytes in size. This conversion factor is used in mapping between a 412 number of entries (for mmchattr) and a size when calling gpfs_prealloc. */ 413 #define GPFS_PREALLOC_DIR_SLOT_SIZE 32 /* for size => bytes per entry */ 414 415 416 typedef struct gpfs_winattr 417 { 418 gpfs_timestruc_t creationTime; 419 unsigned int winAttrs; /* values as defined below */ 420 } gpfs_winattr_t; 421 422 /* winAttrs values */ 423 #define GPFS_WINATTR_ARCHIVE 0x0001 424 #define GPFS_WINATTR_COMPRESSED 0x0002 425 #define GPFS_WINATTR_DEVICE 0x0004 426 #define GPFS_WINATTR_DIRECTORY 0x0008 427 #define GPFS_WINATTR_ENCRYPTED 0x0010 428 #define GPFS_WINATTR_HIDDEN 0x0020 429 #define GPFS_WINATTR_NORMAL 0x0040 430 #define GPFS_WINATTR_NOT_CONTENT_INDEXED 0x0080 431 #define GPFS_WINATTR_OFFLINE 0x0100 432 #define GPFS_WINATTR_READONLY 0x0200 433 #define GPFS_WINATTR_REPARSE_POINT 0x0400 434 #define GPFS_WINATTR_SPARSE_FILE 0x0800 435 #define GPFS_WINATTR_SYSTEM 0x1000 436 #define GPFS_WINATTR_TEMPORARY 0x2000 437 #define GPFS_WINATTR_HAS_STREAMS 0x4000 438 439 440 /* NAME: gpfs_get_winattrs() 441 * gpfs_get_winattrs_path() 442 * 443 * FUNCTION: Returns gpfs_winattr_t attributes 444 * 445 * Returns: 0 Success 446 * -1 Failure 447 * 448 * Errno: ENOENT file not found 449 * EBADF Bad file handle, not a GPFS file 450 * ENOMEM Memory allocation failed 451 * EACCESS Permission denied 452 * EFAULT Bad address provided 453 * EINVAL Not a regular file 454 * ENOSYS function not available 455 */ 456 int GPFS_API 457 gpfs_get_winattrs(gpfs_file_t fileDesc, gpfs_winattr_t *attrP); 458 459 int GPFS_API 460 gpfs_get_winattrs_path(const char *pathname, gpfs_winattr_t *attrP); 461 462 463 /* NAME: gpfs_set_winattrs() 464 * gpfs_set_winattrs_path() 465 * 466 * FUNCTION: Sets gpfs_winattr_t attributes (as specified by 467 * the flags). 468 * 469 * Returns: 0 Success 470 * -1 Failure 471 * 472 * Errno: ENOENT file not found 473 * EBADF Bad file handle, not a GPFS file 474 * ENOMEM Memory allocation failed 475 * EACCESS Permission denied 476 * EFAULT Bad address provided 477 * EINVAL Not a regular file 478 * ENOSYS function not available 479 */ 480 int GPFS_API 481 gpfs_set_winattrs(gpfs_file_t fileDesc, int flags, gpfs_winattr_t *attrP); 482 483 int GPFS_API 484 gpfs_set_winattrs_path(const char *pathname, int flags, gpfs_winattr_t *attrP); 485 486 /* gpfs_set_winattr flag values */ 487 #define GPFS_WINATTR_SET_CREATION_TIME 0x08 488 #define GPFS_WINATTR_SET_ATTRS 0x10 489 490 /* 491 * NAME: gpfs_set_times(), gpfs_set_times_path() 492 * 493 * FUNCTION: Sets file access time, modified time, change time, 494 * and/or creation time (as specified by the flags). 495 * 496 * Input: flagsfileDesc : file descriptor of the object to set 497 * pathname : path to a file or directory 498 * flag : define time value to set 499 * GPFS_SET_ATIME - set access time 500 * GPFS_SET_MTIME - set mod. time 501 * GPFS_SET_CTIME - set change time 502 * GPFS_SET_CREATION_TIME - set creation time 503 * GPFS_SET_TIME_NO_FOLLOW - don't follow links 504 * times : array to times 505 * 506 * Returns: 0 Successful 507 * -1 Failure 508 * 509 * Errno: ENOSYS function not available 510 * EBADF Not a GPFS File 511 * EINVAL invalid argument 512 * EACCES Permission denied 513 * EROFS Filesystem is read only 514 * ENOENT No such file or directory 515 */ 516 typedef gpfs_timestruc_t gpfs_times_vector_t[4]; 517 518 int GPFS_API 519 gpfs_set_times(gpfs_file_t fileDesc, int flags, gpfs_times_vector_t times); 520 521 int GPFS_API 522 gpfs_set_times_path(char *pathname, int flags, gpfs_times_vector_t times); 523 524 /* gpfs_set_times flag values */ 525 #define GPFS_SET_ATIME 0x01 526 #define GPFS_SET_MTIME 0x02 527 #define GPFS_SET_CTIME 0x04 528 #define GPFS_SET_CREATION_TIME 0x08 529 #define GPFS_SET_TIME_NO_FOLLOW 0x10 530 531 532 /* NAME: gpfs_set_share() 533 * 534 * FUNCTION: Acquire shares 535 * 536 * Input: fileDesc : file descriptor 537 * allow : share type being requested 538 * GPFS_SHARE_NONE, GPFS_SHARE_READ, 539 * GPFS_SHARE_WRITE, GPFS_SHARE_BOTH 540 * deny : share type to deny to others 541 * GPFS_DENY_NONE, GPFS_DENY_READ, 542 * GPFS_DENY_WRITE, GPFS_DENY_BOTH 543 * 544 * Returns: 0 Success 545 * -1 Failure 546 * 547 * Errno: EBADF Bad file handle 548 * EINVAL Bad argument given 549 * EFAULT Bad address provided 550 * ENOMEM Memory allocation failed 551 * EACCES share mode not available 552 * ENOSYS function not available 553 */ 554 555 /* allow/deny specifications */ 556 #define GPFS_SHARE_NONE 0 557 #define GPFS_SHARE_READ 1 558 #define GPFS_SHARE_WRITE 2 559 #define GPFS_SHARE_BOTH 3 560 #define GPFS_SHARE_ALL 3 561 #define GPFS_DENY_NONE 0 562 #define GPFS_DENY_READ 1 563 #define GPFS_DENY_WRITE 2 564 #define GPFS_DENY_BOTH 3 565 #define GPFS_DENY_DELETE 4 566 #define GPFS_DENY_ALL 7 567 568 int GPFS_API 569 gpfs_set_share(gpfs_file_t fileDesc, 570 unsigned int share, 571 unsigned int deny); 572 573 574 /* NAME: gpfs_set_lease() 575 * 576 * FUNCTION: Acquire leases for Samba 577 * 578 * Input: fileDesc : file descriptor 579 * leaseType : lease type being requested 580 * GPFS_LEASE_NONE GPFS_LEASE_READ, 581 * GPFS_LEASE_WRITE 582 * 583 * Returns: 0 Success 584 * -1 Failure 585 * 586 * Errno: EBADF Bad file handle 587 * EINVAL Bad argument given 588 * EFAULT Bad address provided 589 * ENOMEM Memory allocation failed 590 * EAGAIN lease not available 591 * EACCES permission denied 592 * EOPNOTSUPP unsupported leaseType 593 * ESTALE unmounted file system 594 * ENOSYS function not available 595 */ 596 597 /* leaseType specifications */ 598 #define GPFS_LEASE_NONE 0 599 #define GPFS_LEASE_READ 1 600 #define GPFS_LEASE_WRITE 2 601 602 int GPFS_API 603 gpfs_set_lease(gpfs_file_t fileDesc, 604 unsigned int leaseType); 605 606 607 /* NAME: gpfs_get_lease() 608 * 609 * FUNCTION: Returns the type of lease currently held 610 * 611 * Returns: GPFS_LEASE_READ 612 * GPFS_LEASE_WRITE 613 * GPFS_LEASE_NONE 614 * 615 * Returns: >= 0 Success 616 * -1 Failure 617 * 618 * Errno: EINVAL 619 */ 620 int GPFS_API 621 gpfs_get_lease(gpfs_file_t fileDesc); 622 623 624 /* NAME: gpfs_get_realfilename(), gpfs_get_realfilename_path() 625 * 626 * FUNCTION: Interface to get real name of a file. 627 * 628 * INPUT: File descriptor, pathname, buffer, bufferlength 629 * OUTPUT: Real file name stored in file system 630 * 631 * Returns: 0 Success 632 * -1 Failure 633 * 634 * Errno: EBADF Bad file handle 635 * EINVAL Not a regular file 636 * EFAULT Bad address provided 637 * ENOSPC buffer too small to return the real file name. 638 * Needed size is returned in buflen parameter. 639 * ENOENT File does not exist 640 * ENOMEM Memory allocation failed 641 * EACCESS Permission denied 642 * ENOSYS function not available 643 */ 644 int GPFS_API 645 gpfs_get_realfilename(gpfs_file_t fileDesc, 646 char *fileNameP, 647 int *buflen); 648 649 int GPFS_API 650 gpfs_get_realfilename_path(const char *pathname, 651 char *fileNameP, 652 int *buflen); 653 654 /* NAME: gpfs_ftruncate() 655 * 656 * FUNCTION: Interface to truncate a file. 657 * 658 * INPUT: File descriptor 659 * length 660 * Returns: 0 Successful 661 * -1 Failure 662 * 663 * Errno: ENOSYS function not available 664 * EBADF Bad file handle 665 * EBADF Not a GPFS file 666 * EINVAL Not a regular file 667 * ENOENT File does not exist 668 * ENOMEM Memory allocation failed 669 * EINVAL length < 0 670 * EACCESS Permission denied 671 */ 672 int GPFS_API 673 gpfs_ftruncate(gpfs_file_t fileDesc, gpfs_off64_t length); 674 675 #define GPFS_WIN_CIFS_REGISTERED 0x02000000 676 typedef struct cifsThreadData_t 677 { 678 unsigned int dataLength; /* Total buffer length */ 679 unsigned int share; /* gpfs_set_share declaration */ 680 unsigned int deny; /* gpfs_set_share specification */ 681 unsigned int lease; /* gpfs_set_lease lease type */ 682 unsigned int secInfoFlags; /* Future use. Must be zero */ 683 gpfs_uid_t sdUID; /* Owning user */ 684 gpfs_uid_t sdGID; /* Owning group */ 685 int shareLocked_fd; /* file descriptor with share locks */ 686 unsigned int aclLength ; /* Length of the following ACL */ 687 gpfs_acl_t acl; /* The initial ACL for create/mkdir */ 688 } cifsThreadData_t; 689 690 /* NAME: gpfs_register_cifs_export() 691 * 692 * FUNCTION: Register a CIFS export process. 693 * 694 * INPUT: implicit use of the process ids 695 * 696 * Returns: 0 Successful 697 * ENOSYS function not available 698 * EACCES cannot establish credentials 699 * ENOMEM temporary shortage of memory 700 * EINVAL prior process/thread registrations exist 701 * EBADF unable to allocate a file descriptor 702 */ 703 int GPFS_API 704 gpfs_register_cifs_export(void); 705 706 /* NAME: gpfs_unregister_cifs_export() 707 * 708 * FUNCTION: remove a registration for a CIFS export 709 * 710 * INPUT: implicit use of the process ids 711 * 712 * Returns: 0 Successful 713 * ENOSYS function not available 714 * EACCES cannot establish credentials 715 * ENOMEM temporary shortage of memory 716 */ 717 int GPFS_API 718 gpfs_unregister_cifs_export(void); 719 720 /* NAME: gpfs_register_cifs_buffer() 721 * 722 * FUNCTION: Register a CIFS thread/buffer combination 723 * 724 * INPUT: implicit use of the process and thread ids 725 * Address of a cifsThreadData_t structure that will include 726 * a GPFS ACL (GPFS_ACL_VERSION_NFS4/GPFS_ACL_LEVEL_V4FLAGS) 727 * that can be applied at file/dir creation. 728 * 729 * Returns: 0 Successful 730 * ENOSYS function not available 731 * EACCES cannot establish credentials 732 * ENOMEM unable to allocate required memory 733 * EINVAL no associated process registrion exists 734 * bad dataLength in buffer. 735 */ 736 int GPFS_API 737 gpfs_register_cifs_buffer(cifsThreadData_t *bufP); 738 739 /* NAME: gpfs_unregister_cifs_buffer() 740 * 741 * FUNCTION: remove a CIFS thread/buffer registration 742 * 743 * INPUT: implicit use of the process and thread ids 744 * 745 * Returns: 0 Successful 746 * ENOSYS function not available 747 * EACCES cannot establish credentials 748 * ENOMEM unable to allocate required memory 749 * EINVAL no associated process registrion exists 750 */ 751 int GPFS_API 752 gpfs_unregister_cifs_buffer(void); 753 754 /* NAME: gpfs_lib_init() 755 * 756 * FUNCTION: Open GPFS main module device file 757 * 758 * INPUT: Flags 759 * Returns: 0 Successful 760 * -1 Failure 761 * 762 * Errno: ENOSYS Function not available 763 */ 764 int GPFS_API 765 gpfs_lib_init(int flags); 766 767 /* NAME: gpfs_lib_term() 768 * 769 * FUNCTION: Close GPFS main module device file 770 * 771 * INPUT: Flags 772 * Returns: 0 Successful 773 * -1 Failure 774 * 775 * Errno: ENOSYS Function not available 776 */ 777 int GPFS_API 778 gpfs_lib_term(int flags); 779 780 /* Define maximum length of the name for a GPFS named object, such 781 as a snapshot, storage pool or fileset. The name is a null-terminated 782 character string, which is not include in the max length */ 783 #define GPFS_MAXNAMLEN 255 784 785 /* Define maximum length of the path to a GPFS named object 786 such as a snapshot or fileset. If the absolute path name exceeds 787 this limit, then use a relative path name. The path is a null-terminated 788 character string, which is not included in the max length */ 789 #define GPFS_MAXPATHLEN 1023 790 791 /* ASCII code for "GPFS" in the struct statfs f_type field */ 792 #define GPFS_SUPER_MAGIC 0x47504653 793 794 /* GPFS inode attributes 795 gpfs_uid_t - defined above 796 gpfs_uid64_t - defined above 797 gpfs_off64_t - defined above 798 799 gpfs_mode_t may include gpfs specific values including 0x02000000 800 To have a gpfs_mode_t be equivalent to a mode_t mask that value out. 801 */ 802 typedef unsigned int gpfs_mode_t; 803 typedef unsigned int gpfs_gid_t; 804 typedef unsigned long long gpfs_gid64_t; 805 typedef unsigned int gpfs_ino_t; 806 typedef unsigned long long gpfs_ino64_t; 807 typedef unsigned int gpfs_gen_t; 808 typedef unsigned long long gpfs_gen64_t; 809 typedef unsigned int gpfs_dev_t; 810 typedef unsigned int gpfs_mask_t; 811 typedef unsigned int gpfs_pool_t; 812 typedef unsigned int gpfs_snapid_t; 813 typedef unsigned long long gpfs_snapid64_t; 814 typedef unsigned long long gpfs_fsid64_t[2]; 815 typedef short gpfs_nlink_t; 816 typedef long long gpfs_nlink64_t; 817 818 819 #if defined(WIN32) || defined(_MS_SUA_) 820 typedef struct gpfs_stat64 821 { 822 gpfs_dev_t st_dev; /* id of device containing file */ 823 gpfs_ino64_t st_ino; /* file inode number */ 824 gpfs_mode_t st_mode; /* access mode */ 825 gpfs_nlink64_t st_nlink; /* number of links */ 826 unsigned int st_flags; /* flag word */ 827 gpfs_uid64_t st_uid; /* owner uid */ 828 gpfs_gid64_t st_gid; /* owner gid */ 829 gpfs_dev_t st_rdev; /* device id (if special file) */ 830 gpfs_off64_t st_size; /* file size in bytes */ 831 gpfs_timestruc64_t st_atime; /* time of last access */ 832 gpfs_timestruc64_t st_mtime; /* time of last data modification */ 833 gpfs_timestruc64_t st_ctime; /* time of last status change */ 834 int st_blksize; /* preferred block size for io */ 835 gpfs_off64_t st_blocks; /* 512 byte blocks of disk held by file */ 836 long long st_fsid; /* file system id */ 837 unsigned int st_type; /* file type */ 838 gpfs_gen64_t st_gen; /* inode generation number */ 839 gpfs_timestruc64_t st_createtime; /* time of creation */ 840 unsigned int st_attrs; /* Windows flags */ 841 } gpfs_stat64_t; 842 #else 843 typedef struct stat64 gpfs_stat64_t; 844 #endif 845 846 #if defined(WIN32) || defined(_MS_SUA_) 847 typedef struct gpfs_statfs64 848 { 849 gpfs_off64_t f_blocks; /* total data blocks in file system */ 850 gpfs_off64_t f_bfree; /* free block in fs */ 851 gpfs_off64_t f_bavail; /* free blocks avail to non-superuser */ 852 int f_bsize; /* optimal file system block size */ 853 gpfs_ino64_t f_files; /* total file nodes in file system */ 854 gpfs_ino64_t f_ffree; /* free file nodes in fs */ 855 gpfs_fsid64_t f_fsid; /* file system id */ 856 int f_fsize; /* fundamental file system block size */ 857 int f_sector_size; /* logical disk sector size */ 858 char f_fname[32]; /* file system name (usually mount pt.) */ 859 char f_fpack[32]; /* file system pack name */ 860 int f_name_max; /* maximum component name length for posix */ 861 } gpfs_statfs64_t; 862 #else 863 typedef struct statfs64 gpfs_statfs64_t; 864 #endif 865 866 /* Declarations for backwards compatibility. */ 867 typedef gpfs_stat64_t stat64_t; 868 typedef gpfs_statfs64_t statfs64_t; 869 870 871 /* Define a version number for the directory entry data to allow 872 future changes in this structure. Careful callers should also use 873 the d_reclen field for the size of the structure rather than sizeof, 874 to allow some degree of forward compatibility */ 875 #define GPFS_D_VERSION 1 876 877 typedef struct gpfs_direntx 878 { 879 int d_version; /* this struct's version */ 880 unsigned short d_reclen; /* actual size of this struct including 881 null terminated variable length d_name */ 882 unsigned short d_type; /* Types are defined below */ 883 gpfs_ino_t d_ino; /* File inode number */ 884 gpfs_gen_t d_gen; /* Generation number for the inode */ 885 char d_name[256]; /* null terminated variable length name */ 886 } gpfs_direntx_t; 887 888 889 #define GPFS_D64_VERSION 2 890 891 typedef struct gpfs_direntx64 892 { 893 int d_version; /* this struct's version */ 894 unsigned short d_reclen; /* actual size of this struct including 895 null terminated variable length d_name */ 896 unsigned short d_type; /* Types are defined below */ 897 gpfs_ino64_t d_ino; /* File inode number */ 898 gpfs_gen64_t d_gen; /* Generation number for the inode */ 899 unsigned int d_flags; /* Flags are defined below */ 900 char d_name[1028]; /* null terminated variable length name */ 901 /* (1020+null+7 byte pad to double word) */ 902 /* to handle up to 255 UTF-8 chars */ 903 } gpfs_direntx64_t; 904 905 /* File types for d_type field in gpfs_direntx_t */ 906 #define GPFS_DE_OTHER 0 907 #define GPFS_DE_FIFO 1 908 #define GPFS_DE_CHR 2 909 #define GPFS_DE_DIR 4 910 #define GPFS_DE_BLK 6 911 #define GPFS_DE_REG 8 912 #define GPFS_DE_LNK 10 913 #define GPFS_DE_SOCK 12 914 #define GPFS_DE_DEL 16 915 916 /* Define flags for gpfs_direntx64_t */ 917 #define GPFS_DEFLAG_NONE 0x0000 /* Default value, no flags set */ 918 #define GPFS_DEFLAG_JUNCTION 0x0001 /* DirEnt is a fileset junction */ 919 #define GPFS_DEFLAG_IJUNCTION 0x0002 /* DirEnt is a inode space junction */ 920 #define GPFS_DEFLAG_ORPHAN 0x0004 /* DirEnt is an orphan (pcache) */ 921 #define GPFS_DEFLAG_CLONE 0x0008 /* DirEnt is a clone child */ 922 923 /* Define a version number for the iattr data to allow future changes 924 in this structure. Careful callers should also use the ia_reclen field 925 for the size of the structure rather than sizeof, to allow some degree 926 of forward compatibility */ 927 #define GPFS_IA_VERSION 1 928 #define GPFS_IA64_VERSION 3 /* ver 3 adds ia_repl_xxxx bytes instead of ia_pad2 */ 929 #define GPFS_IA64_RESERVED 4 930 #define GPFS_IA64_UNUSED 8 931 932 typedef struct gpfs_iattr 933 { 934 int ia_version; /* this struct version */ 935 int ia_reclen; /* sizeof this structure */ 936 int ia_checksum; /* validity check on iattr struct */ 937 gpfs_mode_t ia_mode; /* access mode; see gpfs_mode_t comment */ 938 gpfs_uid_t ia_uid; /* owner uid */ 939 gpfs_gid_t ia_gid; /* owner gid */ 940 gpfs_ino_t ia_inode; /* file inode number */ 941 gpfs_gen_t ia_gen; /* inode generation number */ 942 gpfs_nlink_t ia_nlink; /* number of links */ 943 short ia_flags; /* Flags (defined below) */ 944 int ia_blocksize; /* preferred block size for io */ 945 gpfs_mask_t ia_mask; /* Initial attribute mask (not used) */ 946 unsigned int ia_pad1; /* reserved space */ 947 gpfs_off64_t ia_size; /* file size in bytes */ 948 gpfs_off64_t ia_blocks; /* 512 byte blocks of disk held by file */ 949 gpfs_timestruc_t ia_atime; /* time of last access */ 950 gpfs_timestruc_t ia_mtime; /* time of last data modification */ 951 gpfs_timestruc_t ia_ctime; /* time of last status change */ 952 gpfs_dev_t ia_rdev; /* id of device */ 953 unsigned int ia_xperm; /* extended attributes (defined below) */ 954 unsigned int ia_modsnapid; /* snapshot id of last modification */ 955 unsigned int ia_filesetid; /* fileset ID */ 956 unsigned int ia_datapoolid; /* storage pool ID for data */ 957 unsigned int ia_pad2; /* reserved space */ 958 } gpfs_iattr_t; 959 960 961 typedef struct gpfs_iattr64 962 { 963 int ia_version; /* this struct version */ 964 int ia_reclen; /* sizeof this structure */ 965 int ia_checksum; /* validity check on iattr struct */ 966 gpfs_mode_t ia_mode; /* access mode; see gpfs_mode_t comment */ 967 gpfs_uid64_t ia_uid; /* owner uid */ 968 gpfs_gid64_t ia_gid; /* owner gid */ 969 gpfs_ino64_t ia_inode; /* file inode number */ 970 gpfs_gen64_t ia_gen; /* inode generation number */ 971 gpfs_nlink64_t ia_nlink; /* number of links */ 972 gpfs_off64_t ia_size; /* file size in bytes */ 973 gpfs_off64_t ia_blocks; /* 512 byte blocks of disk held by file */ 974 gpfs_timestruc64_t ia_atime; /* time of last access */ 975 unsigned int ia_winflags; /* windows flags (defined below) */ 976 unsigned int ia_pad1; /* reserved space */ 977 gpfs_timestruc64_t ia_mtime; /* time of last data modification */ 978 unsigned int ia_flags; /* flags (defined below) */ 979 /* next four bytes were ia_pad2 */ 980 unsigned char ia_repl_data; /* data replication factor */ 981 unsigned char ia_repl_data_max; /* data replication max factor */ 982 unsigned char ia_repl_meta; /* meta data replication factor */ 983 unsigned char ia_repl_meta_max; /* meta data replication max factor */ 984 gpfs_timestruc64_t ia_ctime; /* time of last status change */ 985 int ia_blocksize; /* preferred block size for io */ 986 unsigned int ia_pad3; /* reserved space */ 987 gpfs_timestruc64_t ia_createtime; /* creation time */ 988 gpfs_mask_t ia_mask; /* initial attribute mask (not used) */ 989 int ia_pad4; /* reserved space */ 990 unsigned int ia_reserved[GPFS_IA64_RESERVED]; /* reserved space */ 991 unsigned int ia_xperm; /* extended attributes (defined below) */ 992 gpfs_dev_t ia_dev; /* id of device containing file */ 993 gpfs_dev_t ia_rdev; /* device id (if special file) */ 994 unsigned int ia_pcacheflags; /* pcache inode bits */ 995 gpfs_snapid64_t ia_modsnapid; /* snapshot id of last modification */ 996 unsigned int ia_filesetid; /* fileset ID */ 997 unsigned int ia_datapoolid; /* storage pool ID for data */ 998 gpfs_ino64_t ia_inode_space_mask; /* inode space mask of this file system */ 999 /* This value is saved in the iattr structure 1000 during backup and used during restore */ 1001 gpfs_off64_t ia_dirminsize; /* dir pre-allocation size in bytes */ 1002 unsigned int ia_unused[GPFS_IA64_UNUSED]; /* reserved space */ 1003 } gpfs_iattr64_t; 1004 1005 /* Define flags for inode attributes */ 1006 #define GPFS_IAFLAG_SNAPDIR 0x0001 /* (obsolete) */ 1007 #define GPFS_IAFLAG_USRQUOTA 0x0002 /* inode is a user quota file */ 1008 #define GPFS_IAFLAG_GRPQUOTA 0x0004 /* inode is a group quota file */ 1009 #define GPFS_IAFLAG_ERROR 0x0008 /* error reading inode */ 1010 /* Define flags for inode replication attributes */ 1011 #define GPFS_IAFLAG_FILESET_ROOT 0x0010 /* root dir of a fileset */ 1012 #define GPFS_IAFLAG_NO_SNAP_RESTORE 0x0020 /* don't restore from snapshots */ 1013 #define GPFS_IAFLAG_FILESETQUOTA 0x0040 /* inode is a fileset quota file */ 1014 #define GPFS_IAFLAG_COMANAGED 0x0080 /* file data is co-managed */ 1015 #define GPFS_IAFLAG_ILLPLACED 0x0100 /* may not be properly placed */ 1016 #define GPFS_IAFLAG_REPLMETA 0x0200 /* metadata replication set */ 1017 #define GPFS_IAFLAG_REPLDATA 0x0400 /* data replication set */ 1018 #define GPFS_IAFLAG_EXPOSED 0x0800 /* may have data on suspended disks */ 1019 #define GPFS_IAFLAG_ILLREPLICATED 0x1000 /* may not be properly replicated */ 1020 #define GPFS_IAFLAG_UNBALANCED 0x2000 /* may not be properly balanced */ 1021 #define GPFS_IAFLAG_DATAUPDATEMISS 0x4000 /* has stale data blocks on 1022 unavailable disk */ 1023 #define GPFS_IAFLAG_METAUPDATEMISS 0x8000 /* has stale metadata on 1024 unavailable disk */ 1025 1026 #define GPFS_IAFLAG_IMMUTABLE 0x00010000 /* Immutability */ 1027 #define GPFS_IAFLAG_INDEFRETENT 0x00020000 /* Indefinite retention */ 1028 #define GPFS_IAFLAG_SECUREDELETE 0x00040000 /* Secure deletion */ 1029 1030 #define GPFS_IAFLAG_TRUNCMANAGED 0x00080000 /* dmapi truncate event enabled */ 1031 #define GPFS_IAFLAG_READMANAGED 0x00100000 /* dmapi read event enabled */ 1032 #define GPFS_IAFLAG_WRITEMANAGED 0x00200000 /* dmapi write event enabled */ 1033 1034 #define GPFS_IAFLAG_APPENDONLY 0x00400000 /* AppendOnly only */ 1035 #define GPFS_IAFLAG_DELETED 0x00800000 /* inode has been deleted */ 1036 #ifdef ZIP 1037 #define GPFS_IAFLAG_ILLCOMPRESSED 0x01000000 /* may not be properly compressed */ 1038 #endif 1039 #define GPFS_IAFLAG_FPOILLPLACED 0x02000000 /* may not be properly placed per 1040 FPO attributes (bgf, wad, wadfg) */ 1041 1042 /* Define flags for window's attributes */ 1043 #define GPFS_IWINFLAG_ARCHIVE 0x0001 /* Archive */ 1044 #define GPFS_IWINFLAG_HIDDEN 0x0002 /* Hidden */ 1045 #define GPFS_IWINFLAG_NOTINDEXED 0x0004 /* Not content indexed */ 1046 #define GPFS_IWINFLAG_OFFLINE 0x0008 /* Off-line */ 1047 #define GPFS_IWINFLAG_READONLY 0x0010 /* Read-only */ 1048 #define GPFS_IWINFLAG_REPARSE 0x0020 /* Reparse point */ 1049 #define GPFS_IWINFLAG_SYSTEM 0x0040 /* System */ 1050 #define GPFS_IWINFLAG_TEMPORARY 0x0080 /* Temporary */ 1051 #define GPFS_IWINFLAG_COMPRESSED 0x0100 /* Compressed */ 1052 #define GPFS_IWINFLAG_ENCRYPTED 0x0200 /* Encrypted */ 1053 #define GPFS_IWINFLAG_SPARSE 0x0400 /* Sparse file */ 1054 #define GPFS_IWINFLAG_HASSTREAMS 0x0800 /* Has streams */ 1055 1056 /* Define flags for extended attributes */ 1057 #define GPFS_IAXPERM_ACL 0x0001 /* file has acls */ 1058 #define GPFS_IAXPERM_XATTR 0x0002 /* file has extended attributes */ 1059 #define GPFS_IAXPERM_DMATTR 0x0004 /* file has dm attributes */ 1060 #define GPFS_IAXPERM_DOSATTR 0x0008 /* file has non-default dos attrs */ 1061 #define GPFS_IAXPERM_RPATTR 0x0010 /* file has restore policy attrs */ 1062 1063 /* Define flags for pcache bits defined in the inode */ 1064 #define GPFS_ICAFLAG_CACHED 0x0001 /* "cached complete" */ 1065 #define GPFS_ICAFLAG_CREATE 0x0002 /* "created" */ 1066 #define GPFS_ICAFLAG_DIRTY 0x0004 /* "data dirty" */ 1067 #define GPFS_ICAFLAG_LINK 0x0008 /* "hard linked" */ 1068 #define GPFS_ICAFLAG_SETATTR 0x0010 /* "attr changed" */ 1069 #define GPFS_ICAFLAG_LOCAL 0x0020 /* "local" */ 1070 #define GPFS_ICAFLAG_APPEND 0x0040 /* "append" */ 1071 #define GPFS_ICAFLAG_STATE 0x0080 /* "has remote state" */ 1072 1073 /* Define pointers to interface types */ 1074 typedef struct gpfs_fssnap_handle gpfs_fssnap_handle_t; 1075 typedef struct gpfs_iscan gpfs_iscan_t; 1076 typedef struct gpfs_ifile gpfs_ifile_t; 1077 typedef struct gpfs_restore gpfs_restore_t; 1078 1079 typedef struct gpfs_fssnap_id 1080 { 1081 char opaque[48]; 1082 } gpfs_fssnap_id_t; 1083 1084 1085 /* Define extended return codes for gpfs backup & restore 1086 calls without an explicit return code will return the value in errno */ 1087 #define GPFS_NEW_ERRNO_BASE 185 1088 #define GPFS_E_INVAL_INUM (GPFS_NEW_ERRNO_BASE+0) /* invalid inode number */ 1089 1090 #define GPFS_ERRNO_BASE 190 1091 #define GPFS_E_INVAL_FSSNAPID (GPFS_ERRNO_BASE+0) /* invalid fssnap id */ 1092 #define GPFS_E_INVAL_ISCAN (GPFS_ERRNO_BASE+1) /* invalid iscan pointer */ 1093 #define GPFS_E_INVAL_IFILE (GPFS_ERRNO_BASE+2) /* invalid ifile pointer */ 1094 #define GPFS_E_INVAL_IATTR (GPFS_ERRNO_BASE+3) /* invalid iattr structure */ 1095 #define GPFS_E_INVAL_RESTORE (GPFS_ERRNO_BASE+4) /* invalid restore pointer */ 1096 #define GPFS_E_INVAL_FSSNAPHANDLE (GPFS_ERRNO_BASE+5) /* invalid fssnap handle */ 1097 #define GPFS_E_INVAL_SNAPNAME (GPFS_ERRNO_BASE+6) /* invalid snapshot name */ 1098 #define GPFS_E_FS_NOT_RESTORABLE (GPFS_ERRNO_BASE+7) /* FS is not clean */ 1099 #define GPFS_E_RESTORE_NOT_ENABLED (GPFS_ERRNO_BASE+8) /* Restore was not enabled */ 1100 #define GPFS_E_RESTORE_STARTED (GPFS_ERRNO_BASE+9) /* Restore is running */ 1101 #define GPFS_E_INVAL_XATTR (GPFS_ERRNO_BASE+10) /* invalid extended 1102 attribute pointer */ 1103 1104 /* Define flags parameter for get/put file attributes. 1105 Used by gpfs_fgetattr, gpfs_fputattr, gpfs_fputattrwithpath 1106 gpfs_igetattrsx, gpfs_iputattrsx 1107 and gpfs_lwe_getattrs, gpfs_lwe_putattrs 1108 */ 1109 #define GPFS_ATTRFLAG_DEFAULT 0x0000 /* default behavior */ 1110 #define GPFS_ATTRFLAG_NO_PLACEMENT 0x0001 /* exclude file placement attributes */ 1111 #define GPFS_ATTRFLAG_IGNORE_POOL 0x0002 /* saved poolid is not valid */ 1112 #define GPFS_ATTRFLAG_USE_POLICY 0x0004 /* use restore policy rules to 1113 determine poolid */ 1114 #define GPFS_ATTRFLAG_INCL_DMAPI 0x0008 /* Include dmapi attributes */ 1115 #define GPFS_ATTRFLAG_FINALIZE_ATTRS 0x0010 /* Finalize immutability attributes */ 1116 #define GPFS_ATTRFLAG_SKIP_IMMUTABLE 0x0020 /* Skip immutable attributes */ 1117 #define GPFS_ATTRFLAG_INCL_ENCR 0x0040 /* Include encryption attributes */ 1118 #define GPFS_ATTRFLAG_SKIP_CLONE 0x0080 /* Skip clone attributes */ 1119 #define GPFS_ATTRFLAG_MODIFY_CLONEPARENT 0x0100 /* Allow modification on clone parent */ 1120 #ifdef ZIP 1121 #define GPFS_ATTRFLAG_NO_COMPRESSED 0x0200 /* exclude "compressed" attribute */ 1122 #endif 1123 1124 /* Define structure used by gpfs_statfspool */ 1125 typedef struct gpfs_statfspool_s 1126 { 1127 gpfs_off64_t f_blocks; /* total data blocks in pool */ 1128 gpfs_off64_t f_bfree; /* free blocks in pool */ 1129 gpfs_off64_t f_bavail; /* free blocks avail to non-superuser */ 1130 gpfs_off64_t f_mblocks; /* total metadata blocks in pool */ 1131 gpfs_off64_t f_mfree; /* free blocks avail for system metadata */ 1132 int f_bsize; /* optimal storage pool block size */ 1133 int f_files; /* total file nodes assigned to pool */ 1134 gpfs_pool_t f_poolid; /* storage pool id */ 1135 int f_fsize; /* fundamental file system block size */ 1136 unsigned int f_usage; /* data and/or metadata stored in pool */ 1137 int f_replica; /* replica */ 1138 int f_bgf; /* block group factor */ 1139 int f_wad; /* write affinity depth */ 1140 int f_allowWriteAffinity; /* allow write affinity depth. 1 means yes */ 1141 int f_reserved[3];/* Current unused and set to zero */ 1142 } gpfs_statfspool_t; 1143 1144 #define STATFSPOOL_USAGE_DATA 0x0001 /* Pool stores user data */ 1145 #define STATFSPOOL_USAGE_METADATA 0x0002 /* Pool stores system metadata */ 1146 1147 1148 /* NAME: gpfs_fstat(), gpfs_stat() 1149 * 1150 * FUNCTION: Get exact stat information for a file descriptor (or filename). 1151 * Forces all other nodes to flush dirty data and metadata to disk. 1152 * Returns: 0 Successful 1153 * -1 Failure 1154 * 1155 * Errno: ENOSYS The gpfs_fstat() (or) gpfs_stat() subroutine is not supported 1156 * under the current file system format 1157 * EBADF The file descriptor is not valid. 1158 * EINVAL The file descriptor does not refer to a GPFS file or a 1159 * regular file. 1160 * ESTALE The cached file system information was not valid. 1161 */ 1162 int GPFS_API 1163 gpfs_fstat(gpfs_file_t fileDesc, 1164 gpfs_stat64_t *buffer); 1165 1166 int GPFS_API 1167 gpfs_stat(const char *pathname, /* File pathname */ 1168 gpfs_stat64_t *buffer); 1169 1170 /* NAME: gpfs_fstat_x(), gpfs_stat_x() 1171 * 1172 * FUNCTION: Returns extended stat() information with specified accuracy 1173 * for a file descriptor (or filename) 1174 * 1175 * Input: fileDesc : file descriptor or handle 1176 * pathname : path to a file or directory 1177 * iattrBufLen : length of iattr buffer 1178 * 1179 * In/Out: st_litemaskP: bitmask specification of required accuracy 1180 * iattr : buffer for returned stat information 1181 * 1182 * Returns: 0 Successful 1183 * -1 Failure 1184 * 1185 * Errno: ENOSYS function not available 1186 * ENOENT invalid pathname 1187 * EBADF Bad file desc 1188 * EINVAL Not a GPFS file 1189 * ESTALE cached fs information was invalid 1190 */ 1191 int GPFS_API 1192 gpfs_fstat_x(gpfs_file_t fileDesc, 1193 unsigned int *st_litemaskP, 1194 gpfs_iattr64_t *iattr, 1195 size_t iattrBufLen); 1196 1197 int GPFS_API 1198 gpfs_stat_x(const char *pathname, /* File pathname */ 1199 unsigned int *st_litemaskP, 1200 gpfs_iattr64_t *iattr, 1201 size_t iattrBufLen); 1202 1203 /* NAME: gpfs_statfs64() 1204 * 1205 * FUNCTION: Get information about the file system. 1206 * 1207 * Returns: 0 Successful 1208 * -1 Failure 1209 * 1210 * Errno: ENOSYS function not available 1211 * EBADF Bad file desc 1212 * EINVAL Not a GPFS file 1213 * ESTALE cached fs information was invalid 1214 */ 1215 int GPFS_API 1216 gpfs_statfs64(const char *pathname, /* File pathname */ 1217 gpfs_statfs64_t *buffer); 1218 1219 /* NAME: gpfs_statlite() 1220 * gpfs_lstatlite() - do not follow a symlink at the end of the path 1221 * 1222 * FUNCTION: Returns stat() information with specified accuracy 1223 * 1224 * Input: pathname : path to a file or directory 1225 * 1226 * In/Out: st_litemaskP: bitmask specification of required accuracy 1227 * statbufP : buffer for returned stat information 1228 * 1229 * Returns: 0 Successful 1230 * -1 Failure 1231 * 1232 * Errno: Specific error indication 1233 * EINVAL 1234 * 1235 */ 1236 int GPFS_API 1237 gpfs_statlite(const char *pathname, 1238 unsigned int *st_litemaskP, 1239 gpfs_stat64_t *statbufP); 1240 1241 int GPFS_API 1242 gpfs_lstatlite(const char *pathname, 1243 unsigned int *st_litemaskP, 1244 gpfs_stat64_t *statbufP); 1245 1246 1247 /* NAME: gpfs_fgetattrs() 1248 * 1249 * FUNCTION: Retrieves all extended file attributes in opaque format. 1250 * This function together with gpfs_fputattrs is intended for 1251 * use by a backup program to save (gpfs_fgetattrs) and 1252 * restore (gpfs_fputattrs) all extended file attributes 1253 * (ACLs, user attributes, ...) in one call. 1254 * 1255 * NOTE: This call does not return extended attributes used for 1256 * the Data Storage Management (XDSM) API (aka DMAPI). 1257 * 1258 * Input: flags Define behavior of get attributes 1259 * GPFS_ATTRFLAG_NO_PLACEMENT - file attributes for placement 1260 * are not saved, neither is the current storage pool. 1261 * GPFS_ATTRFLAG_IGNORE_POOL - file attributes for placement 1262 * are saved, but the current storage pool is not. 1263 * 1264 * Returns: 0 Successful 1265 * -1 Failure 1266 * 1267 * Errno: ENOSYS function not available 1268 * EINVAL Not a GPFS file 1269 * EINVAL invalid flags provided 1270 * ENOSPC buffer too small to return all attributes 1271 * *attrSizeP will be set to the size necessary 1272 */ 1273 int GPFS_API 1274 gpfs_fgetattrs(gpfs_file_t fileDesc, 1275 int flags, 1276 void *bufferP, 1277 int bufferSize, 1278 int *attrSizeP); 1279 1280 1281 /* NAME: gpfs_fputattrs() 1282 * 1283 * FUNCTION: Sets all extended file attributes of a file 1284 * and sets the file's storage pool and data replication 1285 * to the values saved in the extended attributes. 1286 * 1287 * If the saved storage pool is not valid or if the IGNORE_POOL 1288 * flag is set, then it will select the storage pool by matching 1289 * a PLACEMENT rule using the saved file attributes. 1290 * If it fails to match a placement rule or if there are 1291 * no placement rules installed it will assign the file 1292 * to the "system" storage pool. 1293 * 1294 * The buffer passed in should contain extended attribute data 1295 * that was obtained by a previous call to gpfs_fgetattrs. 1296 * 1297 * Input: flags Define behavior of put attributes 1298 * GPFS_ATTRFLAG_NO_PLACEMENT - file attributes are restored 1299 * but the storage pool and data replication are unchanged 1300 * GPFS_ATTRFLAG_IGNORE_POOL - file attributes are restored 1301 * but the storage pool and data replication are selected 1302 * by matching the saved attributes to a placement rule 1303 * instead of restoring the saved storage pool. 1304 * 1305 * Returns: 0 Successful 1306 * -1 Failure 1307 * 1308 * Errno: ENOSYS function not available 1309 * EINVAL Not a GPFS file 1310 * EINVAL the buffer does not contain valid attribute data 1311 * EINVAL invalid flags provided 1312 */ 1313 int GPFS_API 1314 gpfs_fputattrs(gpfs_file_t fileDesc, 1315 int flags, 1316 void *bufferP); 1317 1318 1319 /* NAME: gpfs_fputattrswithpathname() 1320 * 1321 * FUNCTION: Sets all extended file attributes of a file and invokes 1322 * the policy engine to match a RESTORE rule using the file's 1323 * attributes saved in the extended attributes to set the 1324 * file's storage pool and data replication. The caller should 1325 * include the full path to the file, including the file name, 1326 * to allow rule selection based on file name or path. 1327 * 1328 * If the file fails to match a RESTORE rule, or if there are 1329 * no RESTORE rules installed, then the storage pool and data 1330 * replication are selected as when calling gpfs_fputattrs(). 1331 * 1332 * The buffer passed in should contain extended attribute data 1333 * that was obtained by a previous call to gpfs_fgetattrs. 1334 * 1335 * pathName is a UTF-8 encoded string. On Windows, applications 1336 * can convert UTF-16 ("Unicode") to UTF-8 using the platforms 1337 * WideCharToMultiByte function. 1338 * 1339 * 1340 * Input: flags Define behavior of put attributes 1341 * GPFS_ATTRFLAG_NO_PLACEMENT - file attributes are restored 1342 * but the storage pool and data replication are unchanged 1343 * GPFS_ATTRFLAG_IGNORE_POOL - file attributes are restored 1344 * but if the file fails to match a RESTORE rule, it 1345 * ignore the saved storage pool and select a pool 1346 * by matching the saved attributes to a PLACEMENT rule. 1347 * GPFS_ATTRFLAG_SKIP_IMMUTABLE - Skip immutable/appendOnly flags 1348 * before restoring file data. Then use GPFS_ATTRFLAG_FINALIZE_ATTRS 1349 * to restore immutable/appendOnly flags after data is restored. 1350 * GPFS_ATTRFLAG_FINALIZE_ATTRS - file attributes that are restored 1351 * after data is retored. If file is immutable/appendOnly 1352 * call without this flag before restoring data 1353 * then call with this flag after restoring data 1354 * 1355 * Returns: 0 Successful 1356 * -1 Failure 1357 * 1358 * Errno: ENOSYS function not available 1359 * EINVAL Not a GPFS file 1360 * EINVAL the buffer does not contain valid attribute data 1361 * ENOENT invalid pathname 1362 * EINVAL invalid flags provided 1363 */ 1364 int GPFS_API 1365 gpfs_fputattrswithpathname(gpfs_file_t fileDesc, 1366 int flags, 1367 void *bufferP, 1368 const char *pathName); 1369 1370 1371 /* NAME: gpfs_get_fssnaphandle_by_path() 1372 * 1373 * FUNCTION: Get a volatile handle to uniquely identify a file system 1374 * and snapshot by the path to the file system and snapshot 1375 * 1376 * Input: pathName: path to a file or directory in a gpfs file system 1377 * or to one of its snapshots 1378 * 1379 * Returns: pointer to gpfs_fssnap_handle_t (Successful) 1380 * NULL and errno is set (Failure) 1381 * 1382 * Errno: ENOSYS function not available 1383 * EINVAL Not a GPFS file 1384 * ENOENT invalid pathname 1385 * see system calls open(), fstatfs(), and malloc() ERRORS 1386 */ 1387 gpfs_fssnap_handle_t * GPFS_API 1388 gpfs_get_fssnaphandle_by_path(const char *pathName); 1389 1390 1391 /* NAME: gpfs_get_fssnaphandle_by_name() 1392 * 1393 * FUNCTION: Get a volatile handle to uniquely identify a file system 1394 * and snapshot by the file system name and snapshot name. 1395 * 1396 * Input: fsName: unique name for gpfs file system (may be specified 1397 * as fsName or /dev/fsName) 1398 * snapName: name for snapshot within that file system 1399 * or NULL to access the active file system rather 1400 * than a snapshot within the file system. 1401 * 1402 * Returns: pointer to gpfs_fssnap_handle_t (Successful) 1403 * NULL and errno is set (Failure) 1404 * 1405 * Errno: ENOSYS function not available 1406 * ENOENT invalid file system name 1407 * GPFS_E_INVAL_SNAPNAME invalid snapshot name 1408 * see system calls open(), fstatfs(), and malloc() ERRORS 1409 */ 1410 gpfs_fssnap_handle_t * GPFS_API 1411 gpfs_get_fssnaphandle_by_name(const char *fsName, 1412 const char *snapName); 1413 1414 1415 /* NAME: gpfs_get_fssnaphandle_by_fssnapid() 1416 * 1417 * FUNCTION: Get a volatile handle to uniquely identify a file system 1418 * and snapshot by a fssnapId created from a previous handle. 1419 * 1420 * Input: fssnapId: unique id for a file system and snapshot 1421 * 1422 * Returns: pointer to gpfs_fssnap_handle_t (Successful) 1423 * NULL and errno is set (Failure) 1424 * 1425 * Errno: ENOSYS function not available 1426 * GPFS_E_INVAL_FSSNAPID invalid snapshot id 1427 * see system calls open(), fstatfs(), and malloc() ERRORS 1428 */ 1429 gpfs_fssnap_handle_t * GPFS_API 1430 gpfs_get_fssnaphandle_by_fssnapid(const gpfs_fssnap_id_t *fssnapId); 1431 1432 /* NAME: gpfs_get_fset_snaphandle_by_path() 1433 * 1434 * FUNCTION: Get a volatile handle to uniquely identify an inode space within a 1435 * filesyetsm and snapshot by the path to the file system and snapshot. 1436 * 1437 * Input: pathName: path to a file or directory in a gpfs file system 1438 * or to one of its snapshots 1439 * 1440 * Returns: pointer to gpfs_fssnap_handle_t (Successful) 1441 * NULL and errno is set (Failure) 1442 * 1443 * Errno: ENOSYS function not available 1444 * EINVAL Not a GPFS file 1445 * ENOENT invalid pathname 1446 * see system calls open(), fstatfs(), and malloc() ERRORS 1447 */ 1448 gpfs_fssnap_handle_t * GPFS_API 1449 gpfs_get_fset_snaphandle_by_path(const char *pathName); 1450 1451 /* NAME: gpfs_get_fset_snaphandle_by_name() 1452 * 1453 * FUNCTION: Get a volatile handle to uniquely identify an inode space within a 1454 * file system and snapshot by the independent fileset name, file system 1455 * name and snapshot name. 1456 * 1457 * Input: fsName: unique name for gpfs file system (may be specified 1458 * as fsName or /dev/fsName) 1459 * fsetName name of the independent fileset that owns the inode space 1460 * snapName: name for snapshot within that file system 1461 * or NULL to access the active file system rather 1462 * than a snapshot within the file system. 1463 * 1464 * Returns: pointer to gpfs_fssnap_handle_t (Successful) 1465 * NULL and errno is set (Failure) 1466 * 1467 * Errno: ENOSYS function not available 1468 * ENOENT invalid file system name 1469 * GPFS_E_INVAL_FSETNAME invalid fset nsmae 1470 * GPFS_E_INVAL_SNAPNAME invalid snapshot name 1471 * see system calls open(), fstatfs(), and malloc() ERRORS 1472 */ 1473 gpfs_fssnap_handle_t * GPFS_API 1474 gpfs_get_fset_snaphandle_by_name(const char *fsName, 1475 const char *fsetName, 1476 const char *snapName); 1477 1478 /* NAME: gpfs_get_fset_snaphandle_by_fset_snapid() 1479 * 1480 * FUNCTION: Get a volatile handle to uniquely identify a file system 1481 * and snapshot by a fssnapId created from a previous handle. 1482 * 1483 * Input: fssnapId: unique id for a file system and snapshot 1484 * 1485 * Returns: pointer to gpfs_fssnap_handle_t (Successful) 1486 * NULL and errno is set (Failure) 1487 * 1488 * Errno: ENOSYS function not available 1489 * GPFS_E_INVAL_FSSNAPID invalid snapshot id 1490 * see system calls open(), fstatfs(), and malloc() ERRORS 1491 */ 1492 gpfs_fssnap_handle_t * GPFS_API 1493 gpfs_get_fset_snaphandle_by_fset_snapid(const gpfs_fssnap_id_t *fsetsnapId); 1494 1495 /* NAME: gpfs_get_pathname_from_fssnaphandle() 1496 * 1497 * FUNCTION: Get the mountpoint and path to a file system 1498 * and snapshot identified by a fssnapHandle 1499 * 1500 * Input: fssnapHandle: ptr to file system & snapshot handle 1501 * 1502 * Returns: ptr to path name to the file system (Successful) 1503 * NULL and errno is set (Failure) 1504 * 1505 * Errno: ENOSYS function not available 1506 * GPFS_E_INVAL_FSSNAPHANDLE invalid fssnapHandle 1507 */ 1508 const char * GPFS_API 1509 gpfs_get_pathname_from_fssnaphandle(gpfs_fssnap_handle_t *fssnapHandle); 1510 1511 1512 /* NAME: gpfs_get_fsname_from_fssnaphandle() 1513 * 1514 * FUNCTION: Get the unique name for the file system 1515 * identified by a fssnapHandle 1516 * 1517 * Input: fssnapHandle: ptr to file system & snapshot handle 1518 * 1519 * Returns: ptr to name of the file system (Successful) 1520 * NULL and errno is set (Failure) 1521 * 1522 * Errno: ENOSYS function not available 1523 * GPFS_E_INVAL_FSSNAPHANDLE invalid fssnapHandle 1524 */ 1525 const char * GPFS_API 1526 gpfs_get_fsname_from_fssnaphandle(gpfs_fssnap_handle_t *fssnapHandle); 1527 1528 1529 /* NAME: gpfs_get_snapname_from_fssnaphandle() 1530 * 1531 * FUNCTION: Get the name for the snapshot 1532 * uniquely identified by a fssnapHandle 1533 * 1534 * Input: fssnapHandle: ptr to file system & snapshot handle 1535 * 1536 * Returns: ptr to name assigned to the snapshot (Successful) 1537 * NULL and errno is set (Failure) 1538 * 1539 * Errno: ENOSYS function not available 1540 * GPFS_E_INVAL_FSSNAPHANDLE invalid fssnaphandle 1541 * GPFS_E_INVAL_SNAPNAME snapshot has been deleted 1542 * 1543 * Notes: If the snapshot has been deleted from the file system 1544 * the snapId may still be valid, but the call will fail 1545 * with errno set to GPFS_E_INVAL_SNAPNAME. 1546 */ 1547 const char * GPFS_API 1548 gpfs_get_snapname_from_fssnaphandle(gpfs_fssnap_handle_t *fssnapHandle); 1549 1550 1551 /* NAME: gpfs_get_snapid_from_fssnaphandle() 1552 * 1553 * FUNCTION: Get the numeric id for the snapshot identified 1554 * by a fssnapHandle. The snapshots define an ordered 1555 * sequence of changes to each file. The file's iattr 1556 * structure defines the snapshot id in which the file 1557 * was last modified (ia_modsnapid). This numeric value 1558 * can be compared to the numeric snapid from a fssnaphandle 1559 * to determine if the file changed before or after the 1560 * snapshot identified by the fssnaphandle. 1561 * 1562 * Input: fssnapHandle: ptr to file system & snapshot handle 1563 * 1564 * Returns: Numeric id for the snapshot referred to by the fssnaphandle 1565 * 0 if the fssnaphandle does not refer to a snapshot 1566 * -1 and errno is set (Failure) 1567 * 1568 * Errno: ENOSYS function not available 1569 * GPFS_E_INVAL_FSSNAPHANDLE invalid fssnaphandle 1570 * 1571 * Notes: The snapshot need not be on-line to determine the 1572 * snapshot's numeric id. 1573 */ 1574 gpfs_snapid_t GPFS_API 1575 gpfs_get_snapid_from_fssnaphandle(gpfs_fssnap_handle_t *fssnapHandle); 1576 1577 gpfs_snapid64_t GPFS_API 1578 gpfs_get_snapid_from_fssnaphandle64(gpfs_fssnap_handle_t *fssnapHandle); 1579 1580 1581 /* NAME: gpfs_get_fssnapid_from_fssnaphandle() 1582 * 1583 * FUNCTION: Get a unique, non-volatile file system and snapshot id 1584 * for the file system and snapshot identified by a 1585 * volatile fssnap handle. 1586 * 1587 * Input: fssnapHandle: ptr to file system & snapshot handle 1588 * fssnapId: returned fssnapId uniquely identifying the 1589 * file system and snapshot being scanned 1590 * 1591 * Returns: 0 and fssnapId is set with id (Successful) 1592 * -1 and errno is set (Failure) 1593 * 1594 * Errno: GPFS_E_INVAL_FSSNAPHANDLE invalid fssnaphandle 1595 * EINVAL null ptr given for returned fssnapId 1596 * EFAULT size mismatch for fssnapId 1597 */ 1598 int GPFS_API 1599 gpfs_get_fssnapid_from_fssnaphandle(gpfs_fssnap_handle_t *fssnapHandle, 1600 gpfs_fssnap_id_t *fssnapId); 1601 1602 1603 /* NAME: gpfs_get_restore_fssnapid_from_fssnaphandle() 1604 * 1605 * FUNCTION: Get the unique, non-volatile file system and snapshot id 1606 * used for the last complete restore of a mirrored file 1607 * system. The file system must been a previous restore 1608 * target and ready for additional incremental restore. 1609 * 1610 * Input: fssnapHandle: ptr to file system & snapshot handle 1611 * fssnapId: returned fssnapId uniquely identifying the 1612 * last complete restored file system. 1613 * 1614 * Returns: 0 and fssnapId is set with id (Successful) 1615 * -1 and errno is set (Failure) 1616 * 1617 * Errno: GPFS_E_INVAL_FSSNAPHANDLE invalid fssnaphandle 1618 * EINVAL null ptr given for returned fssnapId 1619 * EFAULT size mismatch for fssnapId 1620 * EPERM caller must have superuser privilege 1621 * ENOMEM unable to allocate memory for request 1622 * GPFS_E_FS_NOT_RESTORABLE fs is not clean for restore 1623 */ 1624 int GPFS_API 1625 gpfs_get_restore_fssnapid_from_fssnaphandle(gpfs_fssnap_handle_t *fssnapHandle, 1626 gpfs_fssnap_id_t *fssnapId); 1627 1628 /* NAME: gpfs_free_fssnaphandle() 1629 * 1630 * FUNCTION: Free a fssnapHandle 1631 * 1632 * Input: fssnapHandle: ptr to file system & snapshot handle 1633 * 1634 * Returns: void 1635 * 1636 * Errno: None 1637 */ 1638 void GPFS_API 1639 gpfs_free_fssnaphandle(gpfs_fssnap_handle_t *fssnapHandle); 1640 1641 /* NAME: gpfs_get_snapdirname() 1642 * 1643 * FUNCTION: Get the name of the directory containing snapshots. 1644 * 1645 * Input: fssnapHandle: handle for the file system 1646 * snapdirName: buffer into which the name of the snapshot 1647 * directory will be copied 1648 * bufLen: the size of the provided buffer 1649 * 1650 * Returns: 0 (Successful) 1651 * -1 and errno is set (Failure) 1652 * 1653 * Errno: ENOSYS function not available 1654 * EPERM caller must have superuser privilege 1655 * ESTALE cached fs information was invalid 1656 * ENOMEM unable to allocate memory for request 1657 * GPFS_E_INVAL_FSSNAPHANDLE fssnapHandle is invalid 1658 * E2BIG buffer too small to return the snapshot directory name 1659 */ 1660 int GPFS_API 1661 gpfs_get_snapdirname(gpfs_fssnap_handle_t *fssnapHandle, 1662 char *snapdirName, 1663 int bufLen); 1664 1665 1666 /* NAME: gpfs_open_inodescan() 1667 * 1668 * FUNCTION: Open inode file for inode scan. 1669 * 1670 * Input: fssnapHandle: handle for file system and snapshot 1671 * to be scanned 1672 * prev_fssnapId: 1673 * if NULL, all inodes of existing file will be returned; 1674 * if non-null, only returns inodes of files that have changed 1675 * since the specified previous snapshot; 1676 * if specifies the same snapshot as the one referred by 1677 * fssnapHandle, only the snapshot inodes that have been 1678 * copied into this snap inode file are returned; 1679 * maxIno: if non-null, returns the maximum inode number 1680 * available in the inode file being scanned. 1681 * 1682 * Returns: pointer to gpfs_iscan_t (Successful) 1683 * NULL and errno is set (Failure) 1684 * 1685 * Errno: ENOSYS function not available 1686 * EINVAL bad parameters 1687 * EPERM caller must have superuser privilege 1688 * ESTALE cached fs information was invalid 1689 * ENOMEM unable to allocate memory for request 1690 * GPFS_E_INVAL_FSSNAPHANDLE fssnapHandle is invalid 1691 * GPFS_E_INVAL_FSSNAPID prev_fssnapId is invalid 1692 * EDOM prev_fssnapId is from a different fs 1693 * ERANGE prev_fssnapId is more recent than snapId 1694 * being scanned 1695 * see system calls dup() and malloc() ERRORS 1696 */ 1697 gpfs_iscan_t * GPFS_API 1698 gpfs_open_inodescan(gpfs_fssnap_handle_t *fssnapHandle, 1699 const gpfs_fssnap_id_t *prev_fssnapId, 1700 gpfs_ino_t *maxIno); 1701 1702 gpfs_iscan_t * GPFS_API 1703 gpfs_open_inodescan64(gpfs_fssnap_handle_t *fssnapHandle, 1704 const gpfs_fssnap_id_t *prev_fssnapId, 1705 gpfs_ino64_t *maxIno); 1706 1707 1708 /* NAME: gpfs_open_inodescan_with_xattrs() 1709 * 1710 * FUNCTION: Open inode file and extended attributes for an inode scan 1711 * 1712 * Input: fssnapHandle: handle for file system and snapshot 1713 * to be scanned 1714 * prev_fssnapId: if NULL, all inodes of existing file will 1715 * be returned; if non-null, only returns inodes of files 1716 * that have changed since the specified previous snapshot; 1717 * if specifies the same snapshot as the one referred by 1718 * fssnapHandle, only the snapshot inodes that have been 1719 * copied into this snap inode file are returned; 1720 * nxAttrs: count of extended attributes to be returned. 1721 * if nxAttrs is set to 0, call returns no extended 1722 * attributes, like gpfs_open_inodescan. 1723 * if nxAttrs is set to -1, call returns all extended attributes 1724 * xAttrList: pointer to array of pointers to names of extended 1725 * attribute to be returned. nxAttrList may be null if nxAttrs 1726 * is set to 0 or -1. 1727 * maxIno: if non-null, returns the maximum inode number 1728 * available in the inode file being scanned. 1729 * 1730 * Returns: pointer to gpfs_iscan_t (Successful) 1731 * NULL and errno is set (Failure) 1732 * 1733 * Errno: ENOSYS function not available 1734 * EINVAL bad parameters 1735 * EPERM caller must have superuser privilege 1736 * ESTALE cached fs information was invalid 1737 * ENOMEM unable to allocate memory for request 1738 * GPFS_E_INVAL_FSSNAPHANDLE fssnapHandle is invalid 1739 * GPFS_E_INVAL_FSSNAPID prev_fssnapId is invalid 1740 * EDOM prev_fssnapId is from a different fs 1741 * ERANGE prev_fssnapId is more recent than snapId 1742 * being scanned 1743 * see system calls dup() and malloc() ERRORS 1744 */ 1745 gpfs_iscan_t * GPFS_API 1746 gpfs_open_inodescan_with_xattrs(gpfs_fssnap_handle_t *fssnapHandle, 1747 const gpfs_fssnap_id_t *prev_fssnapId, 1748 int nxAttrs, 1749 const char *xattrsList[], 1750 gpfs_ino_t *maxIno); 1751 1752 gpfs_iscan_t * GPFS_API 1753 gpfs_open_inodescan_with_xattrs64(gpfs_fssnap_handle_t *fssnapHandle, 1754 const gpfs_fssnap_id_t *prev_fssnapId, 1755 int nxAttrs, 1756 const char *xattrList[], 1757 gpfs_ino64_t *maxIno); 1758 1759 1760 /* NAME: gpfs_next_inode() 1761 * 1762 * FUNCTION: Get next inode from inode scan. Scan terminates before 1763 * the last inode specified or the last inode in the 1764 * inode file being scanned. 1765 * 1766 * If the inode scan was opened to expressly look for inodes 1767 * in a snapshot, and not dittos, gets the next inode skipping 1768 * holes, if any. 1769 * 1770 * Input: iscan: ptr to inode scan descriptor 1771 * termIno: scan terminates before this inode number 1772 * caller may specify maxIno from gpfs_open_inodescan() 1773 * or 0 to scan the entire inode file. 1774 * iattr: pointer to returned pointer to file's iattr. 1775 * 1776 * Returns: 0 and *iattr set to point to gpfs_iattr_t (Successful) 1777 * 0 and *iattr set to NULL for no more inodes before termIno 1778 * -1 and errno is set (Failure) 1779 * 1780 * Errno: ENOSYS function not available 1781 * EPERM caller must have superuser privilege 1782 * ESTALE cached fs information was invalid 1783 * ENOMEM buffer too small 1784 * GPFS_E_INVAL_ISCAN bad parameters 1785 * GPFS_E_INVAL_FSSNAPID the snapshot id provided in the 1786 * gpfs iscan is not valid 1787 * 1788 * Notes: The data returned by gpfs_next_inode() is overwritten by 1789 * subsequent calls to gpfs_next_inode() or gpfs_seek_inode(). 1790 * 1791 * The termIno parameter provides a means to partition an 1792 * inode scan such that it may be executed on more than one node. 1793 */ 1794 int GPFS_API 1795 gpfs_next_inode(gpfs_iscan_t *iscan, 1796 gpfs_ino_t termIno, 1797 const gpfs_iattr_t **iattr); 1798 1799 int GPFS_API 1800 gpfs_next_inode64(gpfs_iscan_t *iscan, 1801 gpfs_ino64_t termIno, 1802 const gpfs_iattr64_t **iattr); 1803 1804 1805 /* NAME: gpfs_next_inode_with_xattrs() 1806 * 1807 * FUNCTION: Get next inode and its extended attributes from the inode scan. 1808 * The set of extended attributes returned were defined when 1809 * the inode scan was opened. The scan terminates before the last 1810 * inode specified or the last inode in the inode file being 1811 * scanned. 1812 * 1813 * If the inode scan was opened to expressly look for inodes 1814 * in a snapshot, and not dittos, gets the next inode skipping 1815 * holes, if any. 1816 * 1817 * Input: iscan: ptr to inode scan descriptor 1818 * termIno: scan terminates before this inode number 1819 * caller may specify maxIno from gpfs_open_inodescan() 1820 * or 0 to scan the entire inode file. 1821 * iattr: pointer to returned pointer to file's iattr. 1822 * xattrBuf: pointer to returned pointer to xattr buffer 1823 * xattrBufLen: returned length of xattr buffer 1824 * 1825 * 1826 * Returns: 0 and *iattr set to point to gpfs_iattr_t (Successful) 1827 * 0 and *iattr set to NULL for no more inodes before termIno 1828 * -1 and errno is set (Failure) 1829 * 1830 * Errno: ENOSYS function not available 1831 * EPERM caller must have superuser privilege 1832 * ESTALE cached fs information was invalid 1833 * EFAULT buffer data was overwritten 1834 * ENOMEM buffer too small 1835 * GPFS_E_INVAL_ISCAN bad parameters 1836 * GPFS_E_INVAL_XATTR bad parameters 1837 * 1838 * Notes: The data returned by gpfs_next_inode() is overwritten by 1839 * subsequent calls to gpfs_next_inode(), gpfs_seek_inode() 1840 * or gpfs_stat_inode(). 1841 * 1842 * The termIno parameter provides a means to partition an 1843 * inode scan such that it may be executed on more than one node. 1844 * 1845 * The returned values for xattrBuf and xattrBufLen must be 1846 * provided to gpfs_next_xattr() to obtain the extended attribute 1847 * names and values. The buffer used for the extended attributes 1848 * is overwritten by subsequent calls to gpfs_next_inode(), 1849 * gpfs_seek_inode() or gpfs_stat_inode(); 1850 * 1851 * The returned pointers to the extended attribute name and value 1852 * will be aligned to a double-word boundary. 1853 */ 1854 int GPFS_API 1855 gpfs_next_inode_with_xattrs(gpfs_iscan_t *iscan, 1856 gpfs_ino_t termIno, 1857 const gpfs_iattr_t **iattr, 1858 const char **xattrBuf, 1859 unsigned int *xattrBufLen); 1860 1861 int GPFS_API 1862 gpfs_next_inode_with_xattrs64(gpfs_iscan_t *iscan, 1863 gpfs_ino64_t termIno, 1864 const gpfs_iattr64_t **iattr, 1865 const char **xattrBuf, 1866 unsigned int *xattrBufLen); 1867 1868 1869 /* NAME: gpfs_next_xattr() 1870 * 1871 * FUNCTION: Iterate over the extended attributes buffer returned 1872 * by get_next_inode_with_xattrs to return the individual 1873 * attributes and their values. Note that the attribute names 1874 * are null-terminated strings, whereas the atttribute value 1875 * contains binary data. 1876 * 1877 * Input: iscan: ptr to inode scan descriptor 1878 * xattrBufLen: ptr to attribute buffer length 1879 * xattrBuf: ptr to the ptr to the attribute buffer 1880 * 1881 * Returns: 0 and *name set to point attribue name (Successful) 1882 * also sets: *valueLen to length of attribute value 1883 * *value to point to attribute value 1884 * *xattrBufLen to remaining length of buffer 1885 * **xattrBuf to index next attribute in buffer 1886 * 0 and *name set to NULL for no more attributes in buffer 1887 * also sets: *valueLen to 0 1888 * *value to NULL 1889 * *xattrBufLen to 0 1890 * **xattrBuf to NULL 1891 * -1 and errno is set (Failure) 1892 * 1893 * Errno: ENOSYS function not available 1894 * GPFS_E_INVAL_ISCAN invalid iscan parameter 1895 * GPFS_E_INVAL_XATTR invalid xattr parameters 1896 * 1897 * Notes: The caller is not allowed to modify the returned attribute 1898 * names or values. The data returned by gpfs_next_attribute() 1899 * may be overwritten by subsequent calls to gpfs_next_attribute() 1900 * or other gpfs library calls. 1901 */ 1902 int GPFS_API 1903 gpfs_next_xattr(gpfs_iscan_t *iscan, 1904 const char **xattrBuf, 1905 unsigned int *xattrBufLen, 1906 const char **name, 1907 unsigned int *valueLen, 1908 const char **value); 1909 1910 1911 1912 /* NAME: gpfs_seek_inode() 1913 * 1914 * FUNCTION: Seek to a given inode number. 1915 * 1916 * Input: iscan: ptr to inode scan descriptor 1917 * ino: next inode number to be scanned 1918 * 1919 * Returns: 0 Successful 1920 * -1 Failure and errno is set 1921 * 1922 * Errno: ENOSYS function not available 1923 * GPFS_E_INVAL_ISCAN bad parameters 1924 */ 1925 int GPFS_API 1926 gpfs_seek_inode(gpfs_iscan_t *iscan, 1927 gpfs_ino_t ino); 1928 1929 int GPFS_API 1930 gpfs_seek_inode64(gpfs_iscan_t *iscan, 1931 gpfs_ino64_t ino); 1932 1933 1934 #ifdef SNAPSHOT_ILM 1935 1936 /* define GPFS generated errno */ 1937 #define GPFS_E_HOLE_IN_IFILE 238 /* hole in inode file */ 1938 1939 #endif 1940 /* NAME: gpfs_stat_inode() 1941 * NAME: gpfs_stat_inode_with_xattrs() 1942 * 1943 * FUNCTION: Seek to the specified inode and get that inode and 1944 * its extended attributes from the inode scan. This is 1945 * simply a combination of gpfs_seek_inode and get_next_inode 1946 * but will only return the specified inode. 1947 * 1948 * Input: iscan: ptr to inode scan descriptor 1949 * ino: inode number to be returned 1950 * termIno: prefetch inodes up to this inode 1951 * caller may specify maxIno from gpfs_open_inodescan() 1952 * or 0 to allow prefetching over the entire inode file. 1953 * iattr: pointer to returned pointer to file's iattr. 1954 * xattrBuf: pointer to returned pointer to xattr buffer 1955 * xattrBufLen: returned length of xattr buffer 1956 * 1957 * Returns: 0 and *iattr set to point to gpfs_iattr_t (Successful) 1958 * 0 and *iattr set to NULL for no more inodes before termIno 1959 * or if requested inode does not exist. 1960 * -1 and errno is set (Failure) 1961 * 1962 * Errno: ENOSYS function not available 1963 * EPERM caller must have superuser privilege 1964 * ESTALE cached fs information was invalid 1965 * ENOMEM buffer too small 1966 * GPFS_E_INVAL_ISCAN bad parameters 1967 * GPFS_E_HOLE_IN_IFILE if we are expressly looking for inodes in 1968 * the snapshot file and this one has yet not 1969 * been copied into snapshot. 1970 * 1971 * Notes: The data returned by gpfs_next_inode() is overwritten by 1972 * subsequent calls to gpfs_next_inode(), gpfs_seek_inode() 1973 * or gpfs_stat_inode(). 1974 * 1975 * The termIno parameter provides a means to partition an 1976 * inode scan such that it may be executed on more than one node. 1977 * It is only used by this call to control prefetching. 1978 * 1979 * The returned values for xattrBuf and xattrBufLen must be 1980 * provided to gpfs_next_xattr() to obtain the extended attribute 1981 * names and values. The buffer used for the extended attributes 1982 * is overwritten by subsequent calls to gpfs_next_inode(), 1983 * gpfs_seek_inode() or gpfs_stat_inode(); 1984 */ 1985 int GPFS_API 1986 gpfs_stat_inode(gpfs_iscan_t *iscan, 1987 gpfs_ino_t ino, 1988 gpfs_ino_t termIno, 1989 const gpfs_iattr_t **iattr); 1990 1991 int GPFS_API 1992 gpfs_stat_inode64(gpfs_iscan_t *iscan, 1993 gpfs_ino64_t ino, 1994 gpfs_ino64_t termIno, 1995 const gpfs_iattr64_t **iattr); 1996 1997 int GPFS_API 1998 gpfs_stat_inode_with_xattrs(gpfs_iscan_t *iscan, 1999 gpfs_ino_t ino, 2000 gpfs_ino_t termIno, 2001 const gpfs_iattr_t **iattr, 2002 const char **xattrBuf, 2003 unsigned int *xattrBufLen); 2004 2005 int GPFS_API 2006 gpfs_stat_inode_with_xattrs64(gpfs_iscan_t *iscan, 2007 gpfs_ino64_t ino, 2008 gpfs_ino64_t termIno, 2009 const gpfs_iattr64_t **iattr, 2010 const char **xattrBuf, 2011 unsigned int *xattrBufLen); 2012 2013 2014 /* NAME: gpfs_close_inodescan() 2015 * 2016 * FUNCTION: Close inode file. 2017 * 2018 * Input: iscan: ptr to inode scan descriptor 2019 * 2020 * Returns: void 2021 * 2022 * Errno: None 2023 */ 2024 void GPFS_API 2025 gpfs_close_inodescan(gpfs_iscan_t *iscan); 2026 2027 2028 /* NAME: gpfs_cmp_fssnapid() 2029 * 2030 * FUNCTION: Compare two fssnapIds for the same file system to 2031 * determine the order in which the two snapshots were taken. 2032 * The 'result' variable will be set as follows: 2033 * *result < 0: snapshot 1 was taken before snapshot 2 2034 * *result == 0: snapshot 1 and 2 are the same 2035 * *result > 0: snapshot 1 was taken after snapshot 2 2036 * 2037 * Input: fssnapId1: ptr to fssnapId 1 2038 * fssnapId2: ptr to fssnapId id 2 2039 * result: ptr to returned results 2040 * 2041 * Returns: 0 and *result is set as described above (Successful) 2042 * -1 and errno is set (Failure) 2043 * 2044 * Errno: ENOSYS function not available 2045 * GPFS_E_INVAL_FSSNAPID fssnapid1 or fssnapid2 is not a 2046 * valid snapshot id 2047 * EDOM the two snapshots cannot be compared because 2048 * they were taken from two different file systems. 2049 */ 2050 int GPFS_API 2051 gpfs_cmp_fssnapid(const gpfs_fssnap_id_t *fssnapId1, 2052 const gpfs_fssnap_id_t *fssnapId2, 2053 int *result); 2054 2055 2056 /* NAME: gpfs_iopen() 2057 * 2058 * FUNCTION: Open a file or directory by inode number. 2059 * 2060 * Input: fssnapHandle: handle for file system and snapshot 2061 * being scanned 2062 * ino: inode number 2063 * open_flags: O_RDONLY for gpfs_iread() 2064 * O_WRONLY for gpfs_iwrite() 2065 * O_CREAT create the file if it doesn't exist 2066 * O_TRUNC if the inode already exists delete it 2067 * caller may use GPFS_O_BACKUP to read files for backup 2068 * and GPFS_O_RESTORE to write files for restore 2069 * statxbuf: used only with O_CREAT/GPFS_O_BACKUP 2070 * all other cases set to NULL 2071 * symLink: used only with O_CREAT/GPFS_O_BACKUP for a symbolic link 2072 * all other cases set to NULL 2073 * 2074 * Returns: pointer to gpfs_ifile_t (Successful) 2075 * NULL and errno is set (Failure) 2076 * 2077 * Errno: ENOSYS function not available 2078 * ENOENT file not existed 2079 * EINVAL missing or bad parameter 2080 * EPERM caller must have superuser privilege 2081 * ESTALE cached fs information was invalid 2082 * ENOMEM unable to allocate memory for request 2083 * EFORMAT invalid fs version number 2084 * EIO error reading original inode 2085 * ERANGE error ino is out of range, should use gpfs_iopen64 2086 * GPFS_E_INVAL_INUM reserved inode is not allowed to open 2087 * GPFS_E_INVAL_IATTR iattr structure was corrupted 2088 * see dup() and malloc() ERRORS 2089 */ 2090 gpfs_ifile_t * GPFS_API 2091 gpfs_iopen(gpfs_fssnap_handle_t *fssnapHandle, 2092 gpfs_ino_t ino, 2093 int open_flags, 2094 const gpfs_iattr_t *statxbuf, 2095 const char *symLink); 2096 2097 gpfs_ifile_t * GPFS_API 2098 gpfs_iopen64(gpfs_fssnap_handle_t *fssnapHandle, 2099 gpfs_ino64_t ino, 2100 int open_flags, 2101 const gpfs_iattr64_t *statxbuf, 2102 const char *symLink); 2103 2104 2105 /* Define gpfs_iopen flags as used by the backup & restore by inode. 2106 The backup code will only read the source files. 2107 The restore code writes the target files & creates them if they 2108 don't already exist. The file length is set by the inode attributes. 2109 Consequently, to restore a user file it is unnecessary to include 2110 the O_TRUNC flag. */ 2111 #define GPFS_O_BACKUP (O_RDONLY) 2112 #define GPFS_O_RESTORE (O_WRONLY | O_CREAT) 2113 2114 2115 /* NAME: gpfs_iread() 2116 * 2117 * FUNCTION: Read file opened by gpfs_iopen. 2118 * 2119 * Input: ifile: pointer to gpfs_ifile_t from gpfs_iopen 2120 * buffer: buffer for data to be read 2121 * bufferSize: size of buffer (ie amount of data to be read) 2122 * In/Out offset: offset of where within the file to read 2123 * if successful, offset will be updated to the 2124 * next byte after the last one that was read 2125 * 2126 * Returns: number of bytes read (Successful) 2127 * -1 and errno is set (Failure) 2128 * 2129 * Errno: ENOSYS function not available 2130 * EISDIR file is a directory 2131 * EPERM caller must have superuser privilege 2132 * ESTALE cached fs information was invalid 2133 * GPFS_E_INVAL_IFILE bad ifile parameters 2134 * see system call read() ERRORS 2135 */ 2136 int GPFS_API 2137 gpfs_iread(gpfs_ifile_t *ifile, 2138 void *buffer, 2139 int bufferSize, 2140 gpfs_off64_t *offset); 2141 2142 2143 /* NAME: gpfs_iwrite() 2144 * 2145 * FUNCTION: Write file opened by gpfs_iopen. 2146 * 2147 * Input: ifile: pointer to gpfs_ifile_t from gpfs_iopen 2148 * buffer: the data to be written 2149 * writeLen: how much to write 2150 * In/Out offset: offset of where within the file to write 2151 * if successful, offset will be updated to the 2152 * next byte after the last one that was written 2153 * 2154 * Returns: number of bytes written (Successful) 2155 * -1 and errno is set (Failure) 2156 * 2157 * Errno: ENOSYS function not available 2158 * EISDIR file is a directory 2159 * EPERM caller must have superuser privilege 2160 * ESTALE cached fs information was invalid 2161 * GPFS_E_INVAL_IFILE bad ifile parameters 2162 * see system call write() ERRORS 2163 */ 2164 int GPFS_API 2165 gpfs_iwrite(gpfs_ifile_t *ifile, 2166 void *buffer, 2167 int writeLen, 2168 gpfs_off64_t *offset); 2169 2170 2171 /* NAME: gpfs_ireaddir() 2172 * 2173 * FUNCTION: Get next directory entry. 2174 * 2175 * Input: idir: pointer to gpfs_ifile_t from gpfs_iopen 2176 * dirent: pointer to returned pointer to directory entry 2177 * 2178 * Returns: 0 and pointer to gpfs_direntx set (Successful) 2179 * 0 and pointer to gpfs_direntx set to NULL (End of directory) 2180 * -1 and errno is set (Failure) 2181 * 2182 * Errno: ENOSYS function not available 2183 * ENOTDIR file is not a directory 2184 * EPERM caller must have superuser privilege 2185 * ESTALE cached fs information was invalid 2186 * GPFS_E_INVAL_IFILE bad ifile parameter 2187 * ENOMEM unable to allocate memory for request 2188 * 2189 * Notes: The data returned by gpfs_ireaddir() is overwritten by 2190 * subsequent calls to gpfs_ireaddir(). 2191 */ 2192 int GPFS_API 2193 gpfs_ireaddir(gpfs_ifile_t *idir, 2194 const gpfs_direntx_t **dirent); 2195 2196 int GPFS_API 2197 gpfs_ireaddir64(gpfs_ifile_t *idir, 2198 const gpfs_direntx64_t **dirent); 2199 2200 2201 int GPFS_API 2202 gpfs_ireaddirx(gpfs_ifile_t *idir, 2203 gpfs_iscan_t *iscan, /* in only */ 2204 const gpfs_direntx_t **dirent); 2205 2206 int GPFS_API 2207 gpfs_ireaddirx64(gpfs_ifile_t *idir, 2208 gpfs_iscan_t *iscan, /* in only */ 2209 const gpfs_direntx64_t **dirent); 2210 2211 2212 /* NAME: gpfs_iwritedir() 2213 * 2214 * FUNCTION: Create a directory entry in a directory opened by gpfs_iopen. 2215 * 2216 * Input: idir: pointer to gpfs_ifile_t from gpfs_iopen 2217 * dirent: directory entry to be written 2218 * 2219 * Returns: 0 (Successful) 2220 * -1 and errno is set (Failure) 2221 * 2222 * Errno: ENOSYS function not available 2223 * GPFS_E_INVAL_IFILE bad file pointer 2224 * ENOTDIR file is not a directory 2225 * EPERM caller must have superuser privilege 2226 * ESTALE cached fs information was invalid 2227 * ENOMEM unable to allocate memory for request 2228 * EFORMAT invalid dirent version number 2229 * see system call write() ERRORS 2230 */ 2231 int GPFS_API 2232 gpfs_iwritedir(gpfs_ifile_t *idir, 2233 const gpfs_direntx_t *dirent); 2234 2235 int GPFS_API 2236 gpfs_iwritedir64(gpfs_ifile_t *idir, 2237 const gpfs_direntx64_t *dirent); 2238 2239 2240 /* NAME: gpfs_igetattrs() 2241 * 2242 * FUNCTION: Retrieves all extended file attributes in opaque format. 2243 * This function together with gpfs_iputattrs is intended for 2244 * use by a backup program to save (gpfs_igetattrs) and 2245 * restore (gpfs_iputattrs) all extended file attributes 2246 * (ACLs, user attributes, ...) in one call. 2247 * 2248 * NOTE: This call does not return extended attributes used for 2249 * the Data Storage Management (XDSM) API (aka DMAPI). 2250 * 2251 * Input: ifile: pointer to gpfs_ifile_t from gpfs_iopen 2252 * buffer: pointer to buffer for returned attributes 2253 * bufferSize: size of buffer 2254 * attrSize: ptr to returned size of attributes 2255 * 2256 * Returns: 0 Successful 2257 * -1 Failure and errno is set 2258 * 2259 * Errno: ENOSYS function not available 2260 * EPERM caller must have superuser privilege 2261 * ESTALE cached fs information was invalid 2262 * ENOSPC buffer too small to return all attributes 2263 * *attrSizeP will be set to the size necessary 2264 * GPFS_E_INVAL_IFILE bad ifile parameters 2265 */ 2266 int GPFS_API 2267 gpfs_igetattrs(gpfs_ifile_t *ifile, 2268 void *buffer, 2269 int bufferSize, 2270 int *attrSize); 2271 2272 /* NAME: gpfs_igetattrsx() 2273 * 2274 * FUNCTION: Retrieves all extended file attributes in opaque format. 2275 * This function together with gpfs_iputattrsx is intended for 2276 * use by a backup program to save (gpfs_igetattrsx) and 2277 * restore (gpfs_iputattrsx) all extended file attributes 2278 * (ACLs, user attributes, ...) in one call. 2279 * 2280 * NOTE: This call can optionally return extended attributes 2281 * used for the Data Storage Management (XDSM) API 2282 * (aka DMAPI). 2283 * 2284 * Input: ifile: pointer to gpfs_ifile_t from gpfs_iopen 2285 * flags Define behavior of get attributes 2286 * GPFS_ATTRFLAG_NO_PLACEMENT - file attributes for placement 2287 * are not saved, neither is the current storage pool. 2288 * GPFS_ATTRFLAG_IGNORE_POOL - file attributes for placement 2289 * are saved, but the current storage pool is not. 2290 * GPFS_ATTRFLAG_INCL_DMAPI - file attributes for dmapi are 2291 * included in the returned buffer 2292 * GPFS_ATTRFLAG_INCL_ENCR - file attributes for encryption 2293 * are included in the returned buffer 2294 * 2295 * buffer: pointer to buffer for returned attributes 2296 * bufferSize: size of buffer 2297 * attrSize: ptr to returned size of attributes 2298 * 2299 * Returns: 0 Successful 2300 * -1 Failure 2301 * 2302 * Errno: ENOSYS function not available 2303 * EINVAL Not a GPFS file 2304 * EINVAL invalid flags provided 2305 * ENOSPC buffer too small to return all attributes 2306 * *attrSizeP will be set to the size necessary 2307 */ 2308 int GPFS_API 2309 gpfs_igetattrsx(gpfs_ifile_t *ifile, 2310 int flags, 2311 void *buffer, 2312 int bufferSize, 2313 int *attrSize); 2314 2315 2316 /* NAME: gpfs_igetxattr() 2317 * 2318 * FUNCTION: Retrieves an extended file attributes from ifile which has been open 2319 * by gpfs_iopen(). 2320 * 2321 * NOTE: This call does not return extended attributes used for 2322 * the Data Storage Management (XDSM) API (aka DMAPI). 2323 * 2324 * Input: ifile: pointer to gpfs_ifile_t from gpfs_iopen 2325 * buffer: pointer to buffer for key and returned extended 2326 * attribute value 2327 * bufferSize: size of buffer, should be enough to save attribute value 2328 * attrSize: ptr to key length as input and ptr to the returned 2329 * size of attributes as putput. 2330 * 2331 * Returns: 0 Successful 2332 * -1 Failure and errno is set 2333 * 2334 * Errno: ENOSYS function not available 2335 * EPERM caller must have superuser priviledges 2336 * ESTALE cached fs information was invalid 2337 * ENOSPC buffer too small to return all attributes 2338 * *attrSize will be set to the size necessary 2339 * GPFS_E_INVAL_IFILE bad ifile parameters 2340 */ 2341 int GPFS_API 2342 gpfs_igetxattr(gpfs_ifile_t *ifile, 2343 void *buffer, 2344 int bufferSize, 2345 int *attrSize); 2346 2347 2348 /* NAME: gpfs_iputattrs() 2349 * 2350 * FUNCTION: Sets all extended file attributes of a file. 2351 * The buffer passed in should contain extended attribute data 2352 * that was obtained by a previous call to gpfs_igetattrs. 2353 * 2354 * NOTE: This call will not restore extended attributes 2355 * used for the Data Storage Management (XDSM) API 2356 * (aka DMAPI). They will be silently ignored. 2357 * 2358 * Input: ifile: pointer to gpfs_ifile_t from gpfs_iopen 2359 * buffer: pointer to buffer for returned attributes 2360 * 2361 * Returns: 0 Successful 2362 * -1 Failure and errno is set 2363 * 2364 * Errno: ENOSYS function not available 2365 * EINVAL the buffer does not contain valid attribute data 2366 * EPERM caller must have superuser privilege 2367 * ESTALE cached fs information was invalid 2368 * GPFS_E_INVAL_IFILE bad ifile parameters 2369 */ 2370 int GPFS_API 2371 gpfs_iputattrs(gpfs_ifile_t *ifile, 2372 void *buffer); 2373 2374 2375 /* NAME: gpfs_iputattrsx() 2376 * 2377 * FUNCTION: Sets all extended file attributes of a file. 2378 * 2379 * This routine can optionally invoke the policy engine 2380 * to match a RESTORE rule using the file's attributes saved 2381 * in the extended attributes to set the file's storage pool and 2382 * data replication as when calling gpfs_fputattrswithpathname. 2383 * When used with the policy the caller should include the 2384 * full path to the file, including the file name, to allow 2385 * rule selection based on file name or path. 2386 * 2387 * By default, the routine will not use RESTORE policy rules 2388 * for data placement. The pathName parameter will be ignored 2389 * and may be set to NULL. 2390 * 2391 * If the call does not use RESTORE policy rules, or if the 2392 * file fails to match a RESTORE rule, or if there are no 2393 * RESTORE rules installed, then the storage pool and data 2394 * replication are selected as when calling gpfs_fputattrs(). 2395 * 2396 * The buffer passed in should contain extended attribute data 2397 * that was obtained by a previous call to gpfs_fgetattrs. 2398 * 2399 * pathName is a UTF-8 encoded string. On Windows, applications 2400 * can convert UTF-16 ("Unicode") to UTF-8 using the platforms 2401 * WideCharToMultiByte function. 2402 * 2403 * NOTE: This call will restore extended attributes 2404 * used for the Data Storage Management (XDSM) API 2405 * (aka DMAPI) if they are present in the buffer. 2406 * 2407 * Input: ifile: pointer to gpfs_ifile_t from gpfs_iopen 2408 * flags Define behavior of put attributes 2409 * GPFS_ATTRFLAG_NO_PLACEMENT - file attributes are restored 2410 * but the storage pool and data replication are unchanged 2411 * GPFS_ATTRFLAG_IGNORE_POOL - file attributes are restored 2412 * but the storage pool and data replication are selected 2413 * by matching the saved attributes to a placement rule 2414 * instead of restoring the saved storage pool. 2415 * GPFS_ATTRFLAG_USE_POLICY - file attributes are restored 2416 * but the storage pool and data replication are selected 2417 * by matching the saved attributes to a RESTORE rule 2418 * instead of restoring the saved storage pool. 2419 * GPFS_ATTRFLAG_FINALIZE_ATTRS - file attributes that are restored 2420 * after data is retored. If file is immutable/appendOnly 2421 * call without this flag before restoring data 2422 * then call with this flag after restoring data 2423 * GPFS_ATTRFLAG_INCL_ENCR - file attributes for encryption 2424 * are restored. Note that this may result in the file's 2425 * File Encryption Key (FEK) being changed, and in this 2426 * case any prior content in the file is effectively lost. 2427 * This option should only be used when the entire file 2428 * content is restored after the attributes are restored. 2429 * 2430 * buffer: pointer to buffer for returned attributes 2431 * pathName: pointer to file path and file name for file 2432 * May be set to NULL. 2433 * 2434 * Returns: 0 Successful 2435 * -1 Failure and errno is set 2436 * 2437 * Errno: ENOSYS function not available 2438 * EINVAL the buffer does not contain valid attribute data 2439 * EINVAL invalid flags provided 2440 * EPERM caller must have superuser privilege 2441 * ESTALE cached fs information was invalid 2442 * GPFS_E_INVAL_IFILE bad ifile parameters 2443 */ 2444 int GPFS_API 2445 gpfs_iputattrsx(gpfs_ifile_t *ifile, 2446 int flags, 2447 void *buffer, 2448 const char *pathName); 2449 2450 2451 /* NAME: gpfs_igetfilesetname() 2452 * 2453 * FUNCTION: Retrieves the name of the fileset which contains this file. 2454 * The fileset name is a null-terminated string, with a 2455 * a maximum length of GPFS_MAXNAMLEN. 2456 * 2457 * Input: iscan: ptr to gpfs_iscan_t from gpfs_open_inodescan() 2458 * filesetId: ia_filesetId returned in an iattr from the iscan 2459 * buffer: pointer to buffer for returned fileset name 2460 * bufferSize: size of buffer 2461 * 2462 * Returns: 0 Successful 2463 * -1 Failure and errno is set 2464 * 2465 * Errno: ENOSYS function not available 2466 * EPERM caller must have superuser privilege 2467 * ESTALE cached fs information was invalid 2468 * ENOSPC buffer too small to return fileset name 2469 * GPFS_E_INVAL_ISCAN bad iscan parameter 2470 */ 2471 int GPFS_API 2472 gpfs_igetfilesetname(gpfs_iscan_t *iscan, 2473 unsigned int filesetId, 2474 void *buffer, 2475 int bufferSize); 2476 2477 2478 /* NAME: gpfs_igetstoragepool() 2479 * 2480 * FUNCTION: Retrieves the name of the storage pool assigned for 2481 * this file's data. The storage pool name is a null-terminated 2482 * string, with a maximum length of GPFS_MAXNAMLEN. 2483 * 2484 * Input: iscan: ptr to gpfs_iscan_t from gpfs_open_inodescan() 2485 * dataPoolId: ia_dataPoolId returned in an iattr from the iscan 2486 * buffer: pointer to buffer for returned attributes 2487 * bufferSize: size of buffer 2488 * 2489 * Returns: 0 Successful 2490 * -1 Failure and errno is set 2491 * 2492 * Errno: ENOSYS function not available 2493 * EPERM caller must have superuser privilege 2494 * ESTALE cached fs information was invalid 2495 * ENOSPC buffer too small to return all storage pool name 2496 * GPFS_E_INVAL_ISCAN bad iscan parameters 2497 */ 2498 int GPFS_API 2499 gpfs_igetstoragepool(gpfs_iscan_t *iscan, 2500 unsigned int dataPoolId, 2501 void *buffer, 2502 int bufferSize); 2503 2504 2505 /* NAME: gpfs_iclose() 2506 * 2507 * FUNCTION: Close file opened by inode and update dates. 2508 * 2509 * Input: ifile: pointer to gpfs_ifile_t from gpfs_iopen 2510 * 2511 * Returns: void 2512 */ 2513 void GPFS_API 2514 gpfs_iclose(gpfs_ifile_t *ifile); 2515 2516 2517 /* NAME: gpfs_ireadlink() 2518 * 2519 * FUNCTION: Read symbolic link by inode number. 2520 * 2521 * Input: fssnapHandle: handle for file system & snapshot being scanned 2522 * ino: inode number of link file to read 2523 * buffer: pointer to buffer for returned link data 2524 * bufferSize: size of the buffer 2525 * 2526 * Returns: number of bytes read (Successful) 2527 * -1 and errno is set (Failure) 2528 * 2529 * Errno: ENOSYS function not available 2530 * EPERM caller must have superuser privilege 2531 * ESTALE cached fs information was invalid 2532 * GPFS_E_INVAL_FSSNAPHANDLE invalid fssnap handle 2533 * see system call readlink() ERRORS 2534 */ 2535 int GPFS_API 2536 gpfs_ireadlink(gpfs_fssnap_handle_t *fssnapHandle, 2537 gpfs_ino_t ino, 2538 char *buffer, 2539 int bufferSize); 2540 2541 int GPFS_API 2542 gpfs_ireadlink64(gpfs_fssnap_handle_t *fssnapHandle, 2543 gpfs_ino64_t ino, 2544 char *buffer, 2545 int bufferSize); 2546 2547 2548 /* NAME: gpfs_sync_fs() 2549 * 2550 * FUNCTION: sync file system. 2551 * 2552 * Input: fssnapHandle: handle for file system being restored 2553 * 2554 * Returns: 0 all data flushed to disk (Successful) 2555 * -1 and errno is set (Failure) 2556 * 2557 * Errno: ENOSYS function not available 2558 * ENOMEM unable to allocate memory for request 2559 * EPERM caller must have superuser privilege 2560 * ESTALE cached fs information was invalid 2561 * GPFS_E_INVAL_FSSNAPHANDLE invalid fssnapHandle 2562 */ 2563 int GPFS_API 2564 gpfs_sync_fs(gpfs_fssnap_handle_t *fssnapHandle); 2565 2566 2567 /* NAME: gpfs_enable_restore() 2568 * 2569 * FUNCTION: Mark file system as enabled for restore on/off 2570 * 2571 * Input: fssnapHandle: handle for file system to be enabled 2572 * or disabled for restore 2573 * on_off: flag set to 1 to enable restore 2574 * 0 to disable restore 2575 * 2576 * Returns: 0 (Successful) 2577 * -1 and errno is set (Failure) 2578 * 2579 * Errno: ENOSYS function not available 2580 * EINVAL bad parameters 2581 * GPFS_E_INVAL_FSSNAPHANDLE invalid fssnapHandle 2582 * EPERM caller must have superuser privilege 2583 * ESTALE cached fs information was invalid 2584 * ENOMEM unable to allocate memory for request 2585 * E_FS_NOT_RESTORABLE fs is not clean 2586 * EALREADY fs already marked as requested 2587 * E_RESTORE_STARTED restore in progress 2588 * 2589 * Notes: EALREADY indicates enable/disable restore was already called 2590 * for this fs. The caller must decide if EALREADY represents an 2591 * error condition. 2592 */ 2593 int GPFS_API 2594 gpfs_enable_restore(gpfs_fssnap_handle_t *fssnapHandle, 2595 int on_off); 2596 2597 2598 /* NAME: gpfs_start_restore() 2599 * 2600 * FUNCTION: Start a restore session. 2601 * 2602 * Input: fssnapHandle: handle for file system to be restored 2603 * restore_flags: Flag to indicate the restore should be started 2604 * even if a prior restore has not completed. 2605 * old_fssnapId: fssnapId of last restored snapshot 2606 * new_fssnapId: fssnapId of snapshot being restored 2607 * 2608 * Returns: pointer to gpfs_restore_t (Successful) 2609 * NULL and errno is set (Failure) 2610 * 2611 * Errno: ENOSYS function not available 2612 * ENOMEM unable to allocate memory for request 2613 * EINVAL missing parameter 2614 * EPERM caller must have superuser privilege 2615 * ESTALE cached fs information was invalid 2616 * EDOM restore fs does not match existing fs 2617 * ERANGE restore is missing updates 2618 * EFORMAT invalid fs version number 2619 * GPFS_E_INVAL_FSSNAPHANDLE invalid fssnaphandle 2620 * GPFS_E_INVAL_FSSNAPID bad fssnapId parameter 2621 * E_FS_NOT_RESTORABLE fs is not clean for restore 2622 * E_RESTORE_NOT_ENABLED fs is not enabled for restore 2623 * EALREADY Restore already in progress 2624 * 2625 * Note: EALREADY indicates start restore was already called for 2626 * this fs. This could be due to a prior restore process that failed 2627 * or it could be due to a concurrent restore process still running. 2628 * The caller must decide if EALREADY represents an error condition. 2629 */ 2630 gpfs_restore_t * GPFS_API 2631 gpfs_start_restore(gpfs_fssnap_handle_t *fssnapHandle, 2632 int restore_flags, 2633 const gpfs_fssnap_id_t *old_fssnapId, 2634 const gpfs_fssnap_id_t *new_fssnapId); 2635 2636 #define GPFS_RESTORE_NORMAL 0 /* Restore not started if prior restore 2637 has not completed. */ 2638 #define GPFS_RESTORE_FORCED 1 /* Restore starts even if prior restore 2639 has not completed. */ 2640 2641 2642 /* NAME: gpfs_end_restore() 2643 * 2644 * FUNCTION: End a restore session. 2645 * 2646 * Input: restoreId: ptr to gpfs_restore_t 2647 * 2648 * Returns: 0 (Successful) 2649 * -1 and errno is set (Failure) 2650 * 2651 * Errno: ENOSYS function not available 2652 * EINVAL bad parameters 2653 * EPERM caller must have superuser privilege 2654 * ESTALE cached fs information was invalid 2655 * GPFS_E_INVAL_RESTORE bad restoreId parameter 2656 * GPFS_E_FS_NOT_RESTORABLE fs is not clean for restore 2657 * GPFS_E_RESTORE_NOT_ENABLED fs is not enabled for restore 2658 * EALREADY Restore already ended 2659 * 2660 * Note: EALREADY indicates end restore was already called for 2661 * this fs. This could be due to a concurrent restore process that 2662 * already completed. The caller must decide if EALREADY represents 2663 * an error condition. 2664 */ 2665 int GPFS_API 2666 gpfs_end_restore(gpfs_restore_t *restoreId); 2667 2668 2669 /* NAME: gpfs_ireadx() 2670 * 2671 * FUNCTION: Block level incremental read on a file opened by gpfs_iopen 2672 * with a given incremental scan opened via gpfs_open_inodescan. 2673 * 2674 * Input: ifile: ptr to gpfs_ifile_t returned from gpfs_iopen() 2675 * iscan: ptr to gpfs_iscan_t from gpfs_open_inodescan() 2676 * buffer: ptr to buffer for returned data 2677 * bufferSize: size of buffer for returned data 2678 * offset: ptr to offset value 2679 * termOffset: read terminates before reading this offset 2680 * caller may specify ia_size for the file's 2681 * gpfs_iattr_t or 0 to scan the entire file. 2682 * hole: ptr to returned flag to indicate a hole in the file 2683 * 2684 * Returns: number of bytes read and returned in buffer 2685 * or size of hole encountered in the file. (Success) 2686 * -1 and errno is set (Failure) 2687 * 2688 * On input, *offset contains the offset in the file 2689 * at which to begin reading to find a difference same file 2690 * in a previous snapshot specified when the inodescan was opened. 2691 * On return, *offset contains the offset of the first 2692 * difference. 2693 * 2694 * On return, *hole indicates if the change in the file 2695 * was data (*hole == 0) and the data is returned in the 2696 * buffer provided. The function's value is the amount of data 2697 * returned. If the change is a hole in the file, 2698 * *hole != 0 and the size of the changed hole is returned 2699 * as the function value. 2700 * 2701 * A call with a NULL buffer pointer will query the next increment 2702 * to be read from the current offset. The *offset, *hole and 2703 * returned length will be set for the next increment to be read, 2704 * but no data will be returned. The bufferSize parameter is 2705 * ignored, but the termOffset parameter will limit the 2706 * increment returned. 2707 * 2708 * Errno: ENOSYS function not available 2709 * EINVAL missing or bad parameter 2710 * EISDIR file is a directory 2711 * EPERM caller must have superuser privilege 2712 * ESTALE cached fs information was invalid 2713 * ENOMEM unable to allocate memory for request 2714 * EDOM fs snapId does match local fs 2715 * ERANGE previous snapId is more recent than scanned snapId 2716 * GPFS_E_INVAL_IFILE bad ifile parameter 2717 * GPFS_E_INVAL_ISCAN bad iscan parameter 2718 * see system call read() ERRORS 2719 * 2720 * Notes: The termOffset parameter provides a means to partition a 2721 * file's data such that it may be read on more than one node. 2722 */ 2723 gpfs_off64_t GPFS_API 2724 gpfs_ireadx(gpfs_ifile_t *ifile, /* in only */ 2725 gpfs_iscan_t *iscan, /* in only */ 2726 void *buffer, /* in only */ 2727 int bufferSize, /* in only */ 2728 gpfs_off64_t *offset, /* in/out */ 2729 gpfs_off64_t termOffset, /* in only */ 2730 int *hole); /* out only */ 2731 2732 2733 /* NAME: gpfs_ireadx_ext 2734 * 2735 * FUNCTION: gpfs_ireadx_ext is used to find different blocks between clone 2736 * child and parent files. Input and output are the same as 2737 * gpfs_ireadx. 2738 * 2739 * Returns: See gpfs_ireadx() 2740 */ 2741 gpfs_off64_t GPFS_API 2742 gpfs_ireadx_ext(gpfs_ifile_t *ifile, /* in only */ 2743 gpfs_iscan_t *iscan, /* in only */ 2744 void *buffer, /* in only */ 2745 int bufferSize, /* in only */ 2746 gpfs_off64_t *offset, /* in/out */ 2747 gpfs_off64_t termOffset, /* in only */ 2748 int *hole); 2749 2750 2751 /* NAME: gpfs_iwritex() 2752 * 2753 * FUNCTION: Write file opened by gpfs_iopen. 2754 * If parameter hole == 0, then write data 2755 * addressed by buffer to the given offset for the 2756 * given length. If hole != 0, then write 2757 * a hole at the given offset for the given length. 2758 * 2759 * Input: ifile : ptr to gpfs_ifile_t returned from gpfs_iopen() 2760 * buffer: ptr to data buffer 2761 * writeLen: length of data to write 2762 * offset: offset in file to write data 2763 * hole: flag =1 to write a "hole" 2764 * =0 to write data 2765 * 2766 * Returns: number of bytes/size of hole written (Success) 2767 * -1 and errno is set (Failure) 2768 * 2769 * Errno: ENOSYS function not available 2770 * EINVAL missing or bad parameter 2771 * EISDIR file is a directory 2772 * EPERM caller must have superuser privilege 2773 * ESTALE cached fs information was invalid 2774 * GPFS_E_INVAL_IFILE bad ifile parameter 2775 * see system call write() ERRORS 2776 */ 2777 gpfs_off64_t GPFS_API 2778 gpfs_iwritex(gpfs_ifile_t *ifile, /* in only */ 2779 void *buffer, /* in only */ 2780 gpfs_off64_t writeLen, /* in only */ 2781 gpfs_off64_t offset, /* in only */ 2782 int hole); /* in only */ 2783 2784 2785 /* NAME: gpfs_statfspool() 2786 * 2787 * FUNCTION: Obtain status information about the storage pools 2788 * 2789 * Input: pathname : path to any file in the file system 2790 * poolId : id of first pool to return 2791 * on return set to next poolId or -1 2792 * to indicate there are no more pools. 2793 * options : option flags (currently not used) 2794 * nPools : number of stat structs requested or 0 2795 * on return number of stat structs in buffer 2796 * or if nPools was 0 its value is the max number 2797 * of storage pools currently defined 2798 * buffer : ptr to return stat structures 2799 * bufferSize : sizeof stat buffer 2800 * 2801 * The user is expected to issue two or more calls. On the first 2802 * call the user should pass nPools set to 0 and gpfs will 2803 * return in nPools the total number of storage pools currently 2804 * defined for the file system indicated by the pathname 2805 * and it returns in poolId the id of the first storage pool. 2806 * The buffer parameter may be set to NULL for this call. 2807 * 2808 * The user may then allocate a buffer large enough to contain 2809 * a gpfs_statfspool_t structure for each of the pools and issue 2810 * a second call to obtain stat information about each pool. 2811 * Parameter nPools should be set the number of pools requested. 2812 * On return, nPools will be set to the number of stat structs 2813 * contained in the buffer, and poolId will be set to the id 2814 * of the next storage pool or -1 to indicate there are no 2815 * additional storage pools defined. 2816 * 2817 * Alternatively, if the user has a valid poolId from a previous 2818 * call, the user may provide that poolId and a buffer large 2819 * enough for a single gpfs_statfspool_t structure, and the call 2820 * will return the status for a single storage pool. 2821 * 2822 * 2823 * Returns: 0 Successful 2824 * -1 Failure 2825 * 2826 * Errno: Specific error indication 2827 * EINVAL 2828 */ 2829 int GPFS_API 2830 gpfs_statfspool(const char *pathname, /* in only: path to file system*/ 2831 gpfs_pool_t *poolId, /* in out: id of first pool to return 2832 on return set to next poolId 2833 or -1 when there are no more pools */ 2834 unsigned int options, /* in only: option flags */ 2835 int *nPools, /* in out: number of pool stats requested 2836 on return number of stat structs 2837 returned in buffer or if nPools was 2838 set to 0, the return value is the 2839 number of pools currently defined */ 2840 void *buffer, /* ptr to return stat structures */ 2841 int bufferSize); /* sizeof stat buffer or 0 */ 2842 2843 2844 /* NAME: gpfs_getpoolname() 2845 * 2846 * FUNCTION: Retrieves the name of the storage pool assigned for 2847 * this file's data. The storage pool name is a null-terminated 2848 * string, with a maximum length of GPFS_MAXNAMLEN. 2849 * 2850 * Input: pathname: path to any file in the file system 2851 * poolId: f_poolid returned in gpfs_statfspool_t 2852 * buffer: pointer to buffer for returned name 2853 * bufferSize: size of buffer 2854 * 2855 * Returns: 0 Successful 2856 * -1 Failure and errno is set 2857 * 2858 * Errno: ENOSYS function not available 2859 * ESTALE file system was unmounted 2860 * E_FORMAT_INCOMPAT file system does not support pools 2861 * E2BIG buffer too small to return storage pool name 2862 */ 2863 int GPFS_API 2864 gpfs_getpoolname(const char *pathname, 2865 gpfs_pool_t poolId, 2866 void *buffer, 2867 int bufferSize); 2868 2869 2870 /* /usr/src/linux/include/linux/fs.h includes /usr/src/linux/include/linux/quota.h 2871 which has conflicting definitions. */ 2872 #ifdef _LINUX_QUOTA_ 2873 #undef Q_SYNC 2874 #undef Q_GETQUOTA 2875 #undef Q_SETQUOTA 2876 #undef Q_QUOTAON 2877 #undef Q_QUOTAOFF 2878 #endif 2879 2880 2881 /* GPFS QUOTACTL */ 2882 2883 /* 2884 * Command definitions for the 'gpfs_quotactl' system call. 2885 * The commands are broken into a main command defined below 2886 * and a subcommand that is used to convey the type of 2887 * quota that is being manipulated (see above). 2888 */ 2889 2890 #define SUBCMDMASK 0x00ff 2891 #define SUBCMDSHIFT 8 2892 #define GPFS_QCMD(cmd, type) (((cmd) << SUBCMDSHIFT) | ((type) & SUBCMDMASK)) 2893 2894 #define Q_QUOTAON 0x0100 /* enable quotas */ 2895 #define Q_QUOTAOFF 0x0200 /* disable quotas */ 2896 #define Q_GETQUOTA 0x0300 /* get limits and usage */ 2897 #ifndef _LINUX_SOURCE_COMPAT 2898 /* Standard AIX definitions of quota commands */ 2899 #define Q_SETQUOTA 0x0400 /* set limits */ 2900 #define Q_SETQLIM Q_SETQUOTA 2901 #else 2902 /* Alternate definitions, for Linux Affinity */ 2903 #define Q_SETQLIM 0x0400 /* set limits */ 2904 #define Q_SETQUOTA 0x0700 /* set limits and usage */ 2905 #endif 2906 #define Q_SETUSE 0x0500 /* set usage */ 2907 #define Q_SYNC 0x0600 /* sync disk copy of a file systems quotas */ 2908 #define Q_SETGRACETIME 0x0900 /* set grace time */ 2909 #define Q_SETGRACETIME_ENHANCE 0x0800 /* set grace time and update all 2910 * quota entries */ 2911 #define Q_GETDQPFSET 0x0A00 /* get default quota per fileset */ 2912 #define Q_SETDQPFSET 0x0B00 /* set default quota per fileset */ 2913 #define Q_SETQUOTA_UPDATE_ET 0x0C00 /* this SETQUOTA needs to update entryType */ 2914 #define Q_GETDQPFSYS 0x0D00 /* get default quota per file system */ 2915 #define Q_SETDQPFSYS 0x0E00 /* set default quota per file system */ 2916 2917 /* gpfs quota types */ 2918 #define GPFS_USRQUOTA 0 2919 #define GPFS_GRPQUOTA 1 2920 #define GPFS_FILESETQUOTA 2 2921 2922 /* define GPFS generated errno */ 2923 #define GPFS_E_NO_QUOTA_INST 237 /* file system does not support quotas */ 2924 2925 typedef struct gpfs_quotaInfo 2926 { 2927 gpfs_off64_t blockUsage; /* current block count in 1 KB units*/ 2928 gpfs_off64_t blockHardLimit; /* absolute limit on disk blks alloc */ 2929 gpfs_off64_t blockSoftLimit; /* preferred limit on disk blks */ 2930 gpfs_off64_t blockInDoubt; /* distributed shares + "lost" usage for blks */ 2931 int inodeUsage; /* current # allocated inodes */ 2932 int inodeHardLimit; /* absolute limit on allocated inodes */ 2933 int inodeSoftLimit; /* preferred inode limit */ 2934 int inodeInDoubt; /* distributed shares + "lost" usage for inodes */ 2935 gpfs_uid_t quoId; /* uid, gid or fileset id */ 2936 int entryType; /* entry type, not used */ 2937 unsigned int blockGraceTime; /* time limit for excessive disk use */ 2938 unsigned int inodeGraceTime; /* time limit for excessive inode use */ 2939 } gpfs_quotaInfo_t; 2940 2941 2942 /* NAME: gpfs_quotactl() 2943 * 2944 * FUNCTION: Manipulate disk quotas 2945 * INPUT: pathname: specifies the pathname of any file within the 2946 * mounted file system to which the command is to 2947 * be applied 2948 * cmd: specifies a quota control command to be applied 2949 * to UID/GID/FILESETID id. The cmd parameter can be 2950 * constructed using GPFS_QCMD(cmd, type) macro defined 2951 * in gpfs.h 2952 * id: UID or GID or FILESETID that command applied to. 2953 * bufferP: points to the address of an optional, command 2954 * specific, data structure that is copied in or out of 2955 * the system. 2956 * 2957 * OUTPUT: bufferP, if applicable. 2958 * 2959 * Returns: 0 success 2960 * -1 failure 2961 * 2962 * Errno: EACCESS 2963 * EFAULT An invalid bufferP parameter is supplied; 2964 * the associated structure could not be copied 2965 * in or out of the kernel 2966 * EINVAL 2967 * ENOENT No such file or directory 2968 * EPERM The quota control command is privileged and 2969 * the caller did not have root user authority 2970 * EOPNOTSUPP 2971 * GPFS_E_NO_QUOTA_INST The file system does not support quotas 2972 */ 2973 int GPFS_API 2974 gpfs_quotactl(const char *pathname, 2975 int cmd, 2976 int id, 2977 void *bufferP); 2978 2979 2980 /* NAME: gpfs_getfilesetid() 2981 * 2982 * FUNCTION: Translate FilesetName to FilesetID 2983 * 2984 * INPUT: pathname: specifies the pathname of any file within the 2985 * mounted file system to which the command is to 2986 * be applied 2987 * name: name of the fileset 2988 * 2989 * OUTPUT: idP: points to the address of an integer that receives the ID 2990 * 2991 * Returns: 0 success 2992 * -1 failure 2993 * 2994 * Errno: EACCESS 2995 * EFAULT An invalid pointer is supplied; the associated 2996 * data could not be copied in or out of the kernel 2997 * EINVAL 2998 * ENOENT No such file, directory or fileset 2999 */ 3000 int GPFS_API 3001 gpfs_getfilesetid(const char *pathname, 3002 const char *name, 3003 int *idP); 3004 3005 3006 /* NAME: gpfs_clone_snap() 3007 * 3008 * FUNCTION: Create an immutable clone parent from a source file 3009 * 3010 * Input: sourcePathP: path to source file, which will be cloned 3011 * destPathP: path to destination file, to be created 3012 * 3013 * If destPathP is NULL, then the source file will be changed 3014 * in place into an immutable clone parent. 3015 * 3016 * Returns: 0 Successful 3017 * -1 Failure 3018 * 3019 * Errno: ENOSYS Function not available 3020 * ENOENT File does not exist 3021 * EACCESS Write access to target or source search permission denied 3022 * EINVAL Not a regular file or not a GPFS file system 3023 * EFAULT Input argument points outside accessible address space 3024 * ENAMETOOLONG Source or destination path name too long 3025 * ENOSPC Not enough space on disk 3026 * EISDIR Destination is a directory 3027 * EXDEV Source and destination aren't in the same file system 3028 * EROFS Destination is read-only 3029 * EPERM Invalid source file 3030 * EEXIST Destination file already exists 3031 * EBUSY Source file is open 3032 * EFORMAT File system does not support clones 3033 * EMEDIUMTYPE File system does not support clones 3034 */ 3035 int GPFS_API 3036 gpfs_clone_snap(const char *sourcePathP, const char *destPathP); 3037 3038 /* NAME: gpfs_clone_copy() 3039 * 3040 * FUNCTION: Create a clone copy of an immutable clone parent file 3041 * 3042 * Input: sourcePathP: path to immutable source file, to be cloned 3043 * destPathP: path to destination file, to be created 3044 * 3045 * Returns: 0 Successful 3046 * -1 Failure 3047 * 3048 * Errno: ENOSYS Function not available 3049 * ENOENT File does not exist 3050 * EACCESS Write access to target or source search permission denied 3051 * EINVAL Not a regular file or not a GPFS file system 3052 * EFAULT Input argument points outside accessible address space 3053 * ENAMETOOLONG Source or destination path name too long 3054 * ENOSPC Not enough space on disk 3055 * EISDIR Destination is a directory 3056 * EXDEV Source and destination aren't in the same file system 3057 * EROFS Destination is read-only 3058 * EPERM Invalid source or destination file 3059 * EEXIST Destination file already exists 3060 * EFORMAT File system does not support clones 3061 * EMEDIUMTYPE File system does not support clones 3062 */ 3063 int GPFS_API 3064 gpfs_clone_copy(const char *sourcePathP, const char *destPathP); 3065 3066 3067 /* NAME: gpfs_declone() 3068 * 3069 * FUNCTION: Copy blocks from clone parent(s) to child so that the 3070 * parent blocks are no longer referenced by the child. 3071 * 3072 * Input: fileDesc: File descriptor for file to be de-cloned 3073 * ancLimit: Ancestor limit (immediate parent only, or all) 3074 * nBlocks: Maximum number of GPFS blocks to copy 3075 * In/Out: offsetP: Pointer to starting offset within file (will be 3076 * updated to offset of next block to process or 3077 * -1 if no more blocks) 3078 * 3079 * Returns: 0 Successful 3080 * -1 Failure 3081 * 3082 * Errno: ENOSYS Function not available 3083 * EINVAL Invalid argument to function 3084 * EBADF Bad file descriptor or not a GPFS file 3085 * EPERM Not a regular file 3086 * EACCESS Write access to target file not permitted 3087 * EFAULT Input argument points outside accessible address space 3088 * ENOSPC Not enough space on disk 3089 */ 3090 3091 /* Values for ancLimit */ 3092 #define GPFS_CLONE_ALL 0 3093 #define GPFS_CLONE_PARENT_ONLY 1 3094 3095 int GPFS_API 3096 gpfs_declone(gpfs_file_t fileDesc, int ancLimit, gpfs_off64_t nBlocks, 3097 gpfs_off64_t *offsetP); 3098 3099 /* NAME: gpfs_clone_split() 3100 * 3101 * FUNCTION: Split a clone child file from its parent. Must call 3102 * gpfs_declone first, to remove all references. 3103 * 3104 * Input: fileDesc: File descriptor for file to be split 3105 * ancLimit: Ancestor limit (immediate parent only, or all) 3106 * 3107 * Returns: 0 Successful 3108 * -1 Failure 3109 * 3110 * Errno: ENOSYS Function not available 3111 * EINVAL Invalid argument to function 3112 * EBADF Bad file descriptor or not a GPFS file 3113 * EPERM Not a regular file or not a clone child 3114 * EACCESS Write access to target file not permitted 3115 */ 3116 int GPFS_API 3117 gpfs_clone_split(gpfs_file_t fileDesc, int ancLimit); 3118 3119 /* NAME: gpfs_clone_unsnap() 3120 * 3121 * FUNCTION: Change a clone parent with no children back into a 3122 * normal file. 3123 * 3124 * Input: fileDesc: File descriptor for file to be un-snapped 3125 * 3126 * Returns: 0 Successful 3127 * -1 Failure 3128 * 3129 * Errno: ENOSYS Function not available 3130 * EINVAL Invalid argument to function 3131 * EBADF Bad file descriptor or not a GPFS file 3132 * EPERM Not a regular file or not a clone parent 3133 * EACCESS Write access to target file not permitted 3134 */ 3135 int GPFS_API 3136 gpfs_clone_unsnap(gpfs_file_t fileDesc); 3137 3138 /* NAME: gpfs_get_fset_masks() 3139 * 3140 * FUNCTION: return bit masks governing "external" inode and inode-space numbering 3141 * 3142 * Input: fset_snaphandle: ptr to an fset snaphandle 3143 * Output: the bit masks and inodes per block factor. 3144 * 3145 * Returns: 0 Success 3146 * -1 Failure 3147 * 3148 * Errno: ENOSYS function not available 3149 * GPFS_E_INVAL_FSSNAPHANDLE invalid fssnapHandle 3150 */ 3151 int GPFS_API 3152 gpfs_get_fset_masks(gpfs_fssnap_handle_t* fset_snapHandle, 3153 gpfs_ino64_t* inodeSpaceMask, 3154 gpfs_ino64_t* inodeBlockMask, 3155 int* inodesPerInodeBlock); 3156 3157 3158 /* 3159 * API functions for Light Weight Event 3160 */ 3161 3162 /* 3163 * Define light weight event types 3164 */ 3165 typedef enum 3166 { 3167 GPFS_LWE_EVENT_UNKNOWN = 0, /* "Uknown event" */ 3168 GPFS_LWE_EVENT_FILEOPEN = 1, /* 'OPEN' - look at getInfo('OPEN_FLAGS') if you care */ 3169 GPFS_LWE_EVENT_FILECLOSE = 2, /* "File Close Event" 'CLOSE' */ 3170 GPFS_LWE_EVENT_FILEREAD = 3, /* "File Read Event" 'READ' */ 3171 GPFS_LWE_EVENT_FILEWRITE = 4, /* "File Write Event" 'WRITE' */ 3172 GPFS_LWE_EVENT_FILEDESTROY = 5, /* File is being destroyed 'DESTROY' */ 3173 GPFS_LWE_EVENT_FILEEVICT = 6, /* OpenFile object is being evicted from memory 'FILE_EVICT' */ 3174 GPFS_LWE_EVENT_BUFFERFLUSH = 7, /* Data buffer is being written to disk 'BUFFER_FLUSH' */ 3175 GPFS_LWE_EVENT_POOLTHRESHOLD = 8, /* Storage pool exceeded defined utilization 'POOL_THRESHOLD' */ 3176 GPFS_LWE_EVENT_FILEDATA = 9, /* "Read/Write/Trunc" event on open file */ 3177 GPFS_LWE_EVENT_FILERENAME = 10, /* Rename event on open file */ 3178 GPFS_LWE_EVENT_FILEUNLINK = 11, /* Unlink file event */ 3179 GPFS_LWE_EVENT_FILERMDIR = 12, /* Remove directory event */ 3180 GPFS_LWE_EVENT_EVALUATE = 13, /* Evaluate And Set Events */ 3181 3182 GPFS_LWE_EVENT_FILEOPEN_READ = 14, /* Open for Read Only - EVENT 'OPEN_READ' - deprecated, use 'OPEN' */ 3183 GPFS_LWE_EVENT_FILEOPEN_WRITE = 15, /* Open with Writing privileges - EVENT 'OPEN_WRITE' - deprecated, use 'OPEN' */ 3184 3185 GPFS_LWE_EVENT_FILEPOOL_CHANGE = 16, /* Open with Writing privileges - EVENT 'OPEN_WRITE' - deprecated, use 'OPEN' */ 3186 3187 GPFS_LWE_EVENT_MAX = 17, /* 1 greater than any of the above */ 3188 } gpfs_lwe_eventtype_t; 3189 3190 3191 /* Define light weight event response types */ 3192 typedef enum 3193 { 3194 GPFS_LWE_RESP_INVALID = 0, /* "Response Invalid/Unknown" */ 3195 GPFS_LWE_RESP_CONTINUE = 1, /* "Response Continue" */ 3196 GPFS_LWE_RESP_ABORT = 2, /* "Response Abort" */ 3197 GPFS_LWE_RESP_DONTCARE = 3 /* "Response DontCare" */ 3198 } gpfs_lwe_resp_t; 3199 3200 /* 3201 * Define light weight event inofrmation 3202 */ 3203 #define LWE_DATA_FS_NAME 0x00000001 /* "fsName" */ 3204 #define LWE_DATA_PATH_NAME 0x00000002 /* "pathName" */ 3205 #define LWE_DATA_PATH_NEW_NAME 0x00000004 /* "pathNewName" for reanem */ 3206 #define LWE_DATA_URL 0x00000008 /* "URL" */ 3207 #define LWE_DATA_INODE 0x00000010 /* "inode" */ 3208 #define LWE_DATA_OPEN_FLAGS 0x00000020 /* "openFlags" */ 3209 #define LWE_DATA_POOL_NAME 0x00000040 /* "poolName" */ 3210 #define LWE_DATA_FILE_SIZE 0x00000080 /* "fileSize" */ 3211 #define LWE_DATA_OWNER_UID 0x00000100 /* "ownerUserId" */ 3212 #define LWE_DATA_OWNER_GID 0x00000200 /* "ownerGroupId" */ 3213 #define LWE_DATA_ATIME 0x00000400 /* "atime" */ 3214 #define LWE_DATA_MTIME 0x00000800 /* "mtime" */ 3215 #define LWE_DATA_NOW_TIME 0x00001000 /* "nowTime" */ 3216 #define LWE_DATA_ELAPSED_TIME 0x00002000 /* "elapsedTime" */ 3217 #define LWE_DATA_CLIENT_UID 0x00004000 /* "clientUserId" */ 3218 #define LWE_DATA_CLIENT_GID 0x00008000 /* "clientGroupId" */ 3219 #define LWE_DATA_NFS_IP 0x00010000 /* "clientIp" */ 3220 #define LWE_DATA_PROCESS_ID 0x00020000 /* "processId" */ 3221 #define LWE_DATA_TARGET_POOL_NAME 0x00040000 /* "targetPoolName" */ 3222 #define LWE_DATA_BYTES_READ 0x00080000 /* "bytesRead" */ 3223 #define LWE_DATA_BYTES_WRITTEN 0x00100000 /* "bytesWritten" */ 3224 #define LWE_DATA_CLUSTER_NAME 0x00200000 /* "clusterName" */ 3225 #define LWE_DATA_NODE_NAME 0x00400000 /* "nodeName" */ 3226 3227 /* 3228 * Define light weight events 3229 */ 3230 #define LWE_EVENT_EVALUATED 0x00000001 /* policy was evaluated */ 3231 #define LWE_EVENT_FILEOPEN 0x00000002 /* "op_open" */ 3232 #define LWE_EVENT_FILECLOSE 0x00000004 /* "op_close" */ 3233 #define LWE_EVENT_FILEREAD 0x00000008 /* "op_read" */ 3234 #define LWE_EVENT_FILEWRITE 0x00000010 /* "op_write" */ 3235 #define LWE_EVENT_FILEDESTROY 0x00000020 /* "op_destroy" */ 3236 #define LWE_EVENT_FILEEVICT 0x00000040 /* "op_evict" OpenFile object is being evicted from memory 'FILE_EVICT' */ 3237 #define LWE_EVENT_BUFFERFLUSH 0x00000080 /* "op_buffer_flush" Data buffer is being written to disk 'BUFFER_FLUSH' */ 3238 #define LWE_EVENT_POOLTHRESHOLD 0x00000100 /* "op_pool_threshhold" Storage pool exceeded defined utilization 'POOL_THRESHOLD' */ 3239 #define LWE_EVENT_FILEDATA 0x00000200 /* "op_data" "Read/Write/Trunc" event on open file */ 3240 #define LWE_EVENT_FILERENAME 0x00000400 /* "op_rename" Rename event on open file */ 3241 #define LWE_EVENT_FILEUNLINK 0x00000800 /* "op_unlink" Unlink file event */ 3242 #define LWE_EVENT_FILERMDIR 0x00001000 /* "op_rmdir" Remove directory event */ 3243 #define LWE_EVENT_FILEOPEN_READ 0x00002000 /* "op_open_read" Open for Read Only - EVENT 'OPEN_READ' - deprecated, use 'OPEN' */ 3244 #define LWE_EVENT_FILEOPEN_WRITE 0x00004000 /* "op_open_write" Open with Writing privileges - EVENT 'OPEN_WRITE' - deprecated, use 'OPEN' */ 3245 #define LWE_EVENT_FILEPOOL_CHANGE 0x00008000 /* "op_pool_change" Open with Writing privileges - EVENT 'OPEN_WRITE' - deprecated, use 'OPEN' */ 3246 3247 /* 3248 * Defines for light weight sessions 3249 */ 3250 typedef unsigned long long gpfs_lwe_sessid_t; 3251 #define GPFS_LWE_NO_SESSION ((gpfs_lwe_sessid_t) 0) 3252 #define GPFS_LWE_SESSION_INFO_LEN 256 3253 3254 3255 /* 3256 * Define light weight token to identify access right 3257 */ 3258 typedef struct gpfs_lwe_token 3259 { 3260 unsigned long long high; 3261 unsigned long long low; 3262 3263 #ifdef __cplusplus 3264 bool operator == (const struct gpfs_lwe_token& rhs) const 3265 { return high == rhs.high && low == rhs.low; }; 3266 bool operator != (const struct gpfs_lwe_token& rhs) const 3267 { return high != rhs.high || low != rhs.low; }; 3268 #endif /* __cplusplus */ 3269 3270 } gpfs_lwe_token_t; 3271 3272 /* Define special tokens */ 3273 static const gpfs_lwe_token_t _gpfs_lwe_no_token = { 0, 0 }; 3274 #define GPFS_LWE_NO_TOKEN _gpfs_lwe_no_token 3275 3276 static const gpfs_lwe_token_t _gpfs_lwe_invalid_token = { 0, 1 }; 3277 #define GPFS_LWE_INVALID_TOKEN _gpfs_lwe_invalid_token 3278 3279 /* 3280 * Note: LWE data managers can set a file's off-line bit 3281 * or any of the managed bits visible to the policy language 3282 * by calling dm_set_region or dm_set_region_nosync 3283 * with a LWE session and LWE exclusive token. To set the bits 3284 * there must be * exactly one managed region with offset = -1 3285 * and size = 0. Any other values will return EINVAL. 3286 */ 3287 3288 /* LWE also provides light weight regions 3289 * that are set via policy rules. 3290 */ 3291 #define GPFS_LWE_MAX_REGIONS 2 3292 3293 /* LWE data events are generated from user access 3294 * to a LWE managed region. */ 3295 #define GPFS_LWE_DATAEVENT_NONE (0x0) 3296 #define GPFS_LWE_DATAEVENT_READ (0x1) 3297 #define GPFS_LWE_DATAEVENT_WRITE (0x2) 3298 #define GPFS_LWE_DATAEVENT_TRUNCATE (0x4) 3299 3300 3301 3302 /* 3303 * Define light weight event structure 3304 */ 3305 typedef struct gpfs_lwe_event { 3306 int eventLen; /* offset 0 */ 3307 gpfs_lwe_eventtype_t eventType; /* offset 4 */ 3308 gpfs_lwe_token_t eventToken; /* offset 8 <--- Must on DWORD */ 3309 int isSync; /* offset 16 */ 3310 int parmLen; /* offset 20 */ 3311 char* parmP; /* offset 24 <-- Must on DWORD */ 3312 } gpfs_lwe_event_t; 3313 3314 3315 3316 /* 3317 * Define light weight access rights 3318 */ 3319 #define GPFS_LWE_RIGHT_NULL 0 3320 #define GPFS_LWE_RIGHT_SHARED 1 3321 #define GPFS_LWE_RIGHT_EXCL 2 3322 3323 3324 /* Flag indicating whether to wait 3325 * when requesting a right or an event 3326 */ 3327 #define GPFS_LWE_FLAG_NONE 0 3328 #define GPFS_LWE_FLAG_WAIT 1 3329 3330 3331 3332 3333 3334 /* NAME: gpfs_lwe_create_session() 3335 * 3336 * FUNCTION: create a light weight event session 3337 * 3338 * Input: oldsid: existing session id, 3339 * Set to GPFS_LWE_NO_SESSION to start new session 3340 * - If a session with the same name and id already exists 3341 * it is not terminated, nor will outstanding events 3342 * be redelivered. This is typically used if a session 3343 * is shared between multiple processes. 3344 * Set to an existing session's id to resume that session 3345 * - If a session with the same name exists, that session 3346 * will be terminated. All pending/outstanding events 3347 * for the old session will be redelivered on the new one. 3348 * This is typically used to take over a session from a 3349 * failed/hung process. 3350 * sessinfop: session string, unique for each session 3351 * 3352 * Output: newsidp: session id for new session 3353 * 3354 * Returns: 0 Success 3355 * -1 Failure 3356 * 3357 * Errno: ENOSYS Function not available 3358 * EINVAL invalid parameters 3359 * ENFILE maximum number of sessions have already been created 3360 * ENOMEM insufficient memory to create new session 3361 * ENOENT session to resume does not exist 3362 * EEXIST session to resume exists with different id 3363 * EPERM Caller does not hold appropriate privilege 3364 */ 3365 int GPFS_API 3366 gpfs_lwe_create_session(gpfs_lwe_sessid_t oldsid, /* IN */ 3367 char *sessinfop, /* IN */ 3368 gpfs_lwe_sessid_t *newsidp); /* OUT */ 3369 3370 #define GPFS_MAX_LWE_SESSION_INFO_LEN 100 3371 3372 3373 3374 /* NAME: gpfs_lwe_destroy_session() 3375 * 3376 * FUNCTION: destroy a light weight event session 3377 * 3378 * Input: sid: id of the session to be destroyed 3379 * 3380 * Returns: 0 Success 3381 * -1 Failure 3382 * 3383 * Errno: ENOSYS Function not available 3384 * EINVAL sid invalid 3385 * EBUSY session is busy 3386 * EPERM Caller does not hold appropriate privilege 3387 */ 3388 int GPFS_API 3389 gpfs_lwe_destroy_session(gpfs_lwe_sessid_t sid); /* IN */ 3390 3391 3392 3393 3394 /* NAME: gpfs_lwe_getall_sessions() 3395 * 3396 * FUNCTION: fetch all lwe sessions 3397 * 3398 * Input: nelem: max number of elements 3399 * sidbufp: array of session id 3400 * nelemp: number of session returned in sidbufp 3401 * 3402 * Returns: 0 Success 3403 * -1 Failure 3404 * 3405 * Errno: ENOSYS Function not available 3406 * EINVAL pass in args invalid 3407 * E2BIG information is too large 3408 * EPERM Caller does not hold appropriate privilege 3409 */ 3410 int GPFS_API 3411 gpfs_lwe_getall_sessions(unsigned int nelem, /* IN */ 3412 gpfs_lwe_sessid_t *sidbufp, /* OUT */ 3413 unsigned int *nelemp); /* OUT */ 3414 3415 3416 /* NAME: gpfs_lw_query_session() 3417 * 3418 * FUNCTION: query session string by id 3419 * 3420 * Input: sid: id of session to be queryed 3421 * buflen: length of buffer 3422 * bufp: buffer to store sessions string 3423 * rlenp: returned length of bufp 3424 * 3425 * Returns: 0 Success 3426 * -1 Failure 3427 * 3428 * Errno: ENOSYS Function not available 3429 * EINVAL pass in args invalid 3430 * E2BIG information is too large 3431 * EPERM Caller does not hold appropriate privilege 3432 */ 3433 int GPFS_API 3434 gpfs_lwe_query_session(gpfs_lwe_sessid_t sid, /* IN */ 3435 size_t buflen, /* IN */ 3436 void *bufp, /* OUT */ 3437 size_t *rlenP); /* OUT */ 3438 3439 3440 /* NAME: gpfs_lwe_get_events() 3441 * 3442 * FUNCTION: get events from a light weight session 3443 * 3444 * Input: sid: id of the session 3445 * maxmsgs: max number of event to fetch, 3446 * 0 to fetch all possible 3447 * flags: GPFS_LWE_EV_WAIT: waiting for new events if event 3448 * queue is empty 3449 * buflen: length of the buffer 3450 * bufp: buffer to hold events 3451 * rlenp: returned length of bufp 3452 * 3453 * Returns: 0 Success 3454 * E2BIG information is too large 3455 * EINVAL pass in args invalid 3456 */ 3457 int GPFS_API 3458 gpfs_lwe_get_events(gpfs_lwe_sessid_t sid, /* IN */ 3459 unsigned int maxmsgs, /* IN */ 3460 unsigned int flags, /* IN */ 3461 size_t buflen, /* IN */ 3462 void *bufp, /* OUT */ 3463 size_t *rlenp); /* OUT */ 3464 3465 /* NAME: gpfs_lwe_respond_event() 3466 * 3467 * FUNCTION: response to a light weight event 3468 * 3469 * Input: sid: id of the session 3470 * token: token of the event 3471 * response: response to the event 3472 * reterror: return error to event callers 3473 * 3474 * Returns: 0 Success 3475 * EINVAL pass in args invalid 3476 * 3477 */ 3478 int GPFS_API 3479 gpfs_lwe_respond_event(gpfs_lwe_sessid_t sid, /* IN */ 3480 gpfs_lwe_token_t token, /* IN */ 3481 gpfs_lwe_resp_t response, /* IN */ 3482 int reterror); /* IN */ 3483 3484 3485 /* NAME: gpfs_lwe_request_right 3486 * 3487 * FUNCTION: Request an access right to a file using a dmapi handle 3488 * 3489 * Input: sid Id of lw session 3490 * hanp Pointer to dmapi handle 3491 * hlen Length of dmapi handle 3492 * right Shared or exclusive access requested 3493 * flags Caller will wait to acquire access if necessary 3494 * 3495 * Output: token Unique identifier for access right 3496 * 3497 * Returns: 0 Success 3498 * -1 Failure 3499 * 3500 * Errno: ENOSYS Function not available 3501 * ESTALE GPFS not available 3502 * EINVAL Invalid arguments 3503 * EFAULT Invalid pointer provided 3504 * EBADF Bad file 3505 * ENOMEM Uable to allocate memory for request 3506 * EPERM Caller does not hold appropriate privilege 3507 * EAGAIN flags parameter did not include WAIT 3508 * and process would be blocked 3509 * 3510 */ 3511 int GPFS_API 3512 gpfs_lwe_request_right(gpfs_lwe_sessid_t sid, /* IN */ 3513 void *hanp, /* IN */ 3514 size_t hlen, /* IN */ 3515 unsigned int right, /* IN */ 3516 unsigned int flags, /* IN */ 3517 gpfs_lwe_token_t *token); /* OUT */ 3518 3519 3520 /* NAME: gpfs_lwe_upgrade_right 3521 * 3522 * FUNCTION: Upgrade an access right from shared to exclusive 3523 * 3524 * This is a non-blocking call to upgrade an access right 3525 * from shared to exclusive. If the token already conveys 3526 * exclusive access this call returns imediately with sucess. 3527 * If another process also holds a shared access right 3528 * this call fails with EBUSY to avoid deadlocks. 3529 * 3530 * Input: sid Id of lw session 3531 * hanp Pointer to dmapi handle 3532 * hlen Length of dmapi handle 3533 * token Unique identifier for access right 3534 * 3535 * Output: None 3536 * 3537 * Returns: 0 Success 3538 * -1 Failure 3539 * 3540 * Errno: ENOSYS Function not available 3541 * ESTALE GPFS not available 3542 * EINVAL Invalid arguments 3543 * EINVAL The token is invalid 3544 * EFAULT Invalid pointer provided 3545 * EPERM Caller does not hold appropriate privilege 3546 * EPERM Token's right is not shared or exclusive 3547 * EBUSY Process would be blocked 3548 * 3549 */ 3550 int GPFS_API 3551 gpfs_lwe_upgrade_right(gpfs_lwe_sessid_t sid, /* IN */ 3552 void *hanp, /* IN */ 3553 size_t hlen, /* IN */ 3554 gpfs_lwe_token_t token); /* IN */ 3555 3556 3557 /* NAME: gpfs_lwe_downgrade_right 3558 * 3559 * FUNCTION: Downgrade an access right from exclusive to shared 3560 * 3561 * This reduces an access right from exclusive to shared 3562 * without dropping the exclusive right to acquire the shared. 3563 * The token must convey exclusive right before the call. 3564 * 3565 * Input: sid Id of lw session 3566 * hanp Pointer to dmapi handle 3567 * hlen Length of dmapi handle 3568 * token Unique identifier for access right 3569 * 3570 * Output: None 3571 * 3572 * Returns: 0 Success 3573 * -1 Failure 3574 * 3575 * Errno: ENOSYS Function not available 3576 * ESTALE GPFS not available 3577 * EINVAL Invalid arguments 3578 * EINVAL The token is invalid 3579 * EFAULT Invalid pointer provided 3580 * EPERM Caller does not hold appropriate privilege 3581 * EPERM Token's right is not exclusive 3582 * 3583 */ 3584 int GPFS_API 3585 gpfs_lwe_downgrade_right(gpfs_lwe_sessid_t sid, /* IN */ 3586 void *hanp, /* IN */ 3587 size_t hlen, /* IN */ 3588 gpfs_lwe_token_t token); /* IN */ 3589 3590 3591 /* NAME: gpfs_lwe_release_right 3592 * 3593 * FUNCTION: Release an access right conveyed by a token 3594 * 3595 * This releases the access right held by a token 3596 * and invalidates the token. Once the access right 3597 * is released the token cannot be reused. 3598 * 3599 * Input: sid Id of lw session 3600 * hanp Pointer to dmapi handle 3601 * hlen Length of dmapi handle 3602 * token Unique identifier for access right 3603 * 3604 * Output: None 3605 * 3606 * Returns: 0 Success 3607 * -1 Failure 3608 * 3609 * Errno: ENOSYS Function not available 3610 * ESTALE GPFS not available 3611 * EINVAL Invalid arguments 3612 * EINVAL The token is invalid 3613 * EFAULT Invalid pointer provided 3614 * EPERM Caller does not hold appropriate privilege 3615 */ 3616 int GPFS_API 3617 gpfs_lwe_release_right(gpfs_lwe_sessid_t sid, /* IN */ 3618 void *hanp, /* IN */ 3619 size_t hlen, /* IN */ 3620 gpfs_lwe_token_t token); /* IN */ 3621 3622 3623 /* NAME: gpfs_lwe_getattrs() 3624 * 3625 * FUNCTION: Retrieves all extended file attributes in opaque format. 3626 * This function together with gpfs_lwe_putattrs is intended for 3627 * use by a backup program to save (gpfs_lwe_getattrs) and 3628 * restore (gpfs_lwe_putattrs) all extended file attributes 3629 * (ACLs, user attributes, ...) in one call. 3630 * 3631 * NOTE: This call is the lwe equivalent of gpfs_igetattrsx 3632 * but uses a file handle to identify the file 3633 * and an existing LWE token for locking it. 3634 * 3635 * 3636 * Input: sid Id of lw session 3637 * hanp Pointer to dmapi handle 3638 * hlen Length of dmapi handle 3639 * token Unique identifier for access right 3640 * flags Define behavior of get attributes 3641 * GPFS_ATTRFLAG_NO_PLACEMENT - file attributes for placement 3642 * are not saved, neither is the current storage pool. 3643 * GPFS_ATTRFLAG_IGNORE_POOL - file attributes for placement 3644 * are saved, but the current storage pool is not. 3645 * GPFS_ATTRFLAG_INCL_DMAPI - file attributes for dmapi are 3646 * included in the returned buffer 3647 * GPFS_ATTRFLAG_INCL_ENCR - file attributes for encryption 3648 * are included in the returned buffer 3649 * 3650 * buffer: pointer to buffer for returned attributes 3651 * bufferSize: size of buffer 3652 * attrSize: ptr to returned size of attributes 3653 * 3654 * Returns: 0 Successful 3655 * -1 Failure 3656 * 3657 * Errno: ENOSYS function not available 3658 * EINVAL Not a GPFS file 3659 * EINVAL invalid flags provided 3660 * ENOSPC buffer too small to return all attributes 3661 * *attrSizeP will be set to the size necessary 3662 */ 3663 int GPFS_API 3664 gpfs_lwe_getattrs(gpfs_lwe_sessid_t sid, 3665 void *hanp, 3666 size_t hlen, 3667 gpfs_lwe_token_t token, 3668 int flags, 3669 void *buffer, 3670 int bufferSize, 3671 int *attrSize); 3672 3673 3674 /* NAME: gpfs_lwe_putattrs() 3675 * 3676 * FUNCTION: Sets all extended file attributes of a file. 3677 * 3678 * This routine can optionally invoke the policy engine 3679 * to match a RESTORE rule using the file's attributes saved 3680 * in the extended attributes to set the file's storage pool and 3681 * data replication as when calling gpfs_fputattrswithpathname. 3682 * When used with the policy the caller should include the 3683 * full path to the file, including the file name, to allow 3684 * rule selection based on file name or path. 3685 * 3686 * By default, the routine will not use RESTORE policy rules 3687 * for data placement. The pathName parameter will be ignored 3688 * and may be set to NULL. 3689 * 3690 * If the call does not use RESTORE policy rules, or if the 3691 * file fails to match a RESTORE rule, or if there are no 3692 * RESTORE rules installed, then the storage pool and data 3693 * replication are selected as when calling gpfs_fputattrs(). 3694 * 3695 * The buffer passed in should contain extended attribute data 3696 * that was obtained by a previous call to gpfs_fgetattrs. 3697 * 3698 * pathName is a UTF-8 encoded string. On Windows, applications 3699 * can convert UTF-16 ("Unicode") to UTF-8 using the platforms 3700 * WideCharToMultiByte function. 3701 * 3702 * NOTE: This call is the lwe equivalent of gpfs_iputaattrsx 3703 * but uses a file handle to identify the file 3704 * and an existing LWE token for locking it. 3705 * 3706 * 3707 * Input: sid Id of lw session 3708 * hanp Pointer to dmapi handle 3709 * hlen Length of dmapi handle 3710 * token Unique identifier for access right 3711 * flags Define behavior of put attributes 3712 * GPFS_ATTRFLAG_NO_PLACEMENT - file attributes are restored 3713 * but the storage pool and data replication are unchanged 3714 * GPFS_ATTRFLAG_IGNORE_POOL - file attributes are restored 3715 * but the storage pool and data replication are selected 3716 * by matching the saved attributes to a placement rule 3717 * instead of restoring the saved storage pool. 3718 * GPFS_ATTRFLAG_USE_POLICY - file attributes are restored 3719 * but the storage pool and data replication are selected 3720 * by matching the saved attributes to a RESTORE rule 3721 * instead of restoring the saved storage pool. 3722 * GPFS_ATTRFLAG_FINALIZE_ATTRS - file attributes that are restored 3723 * after data is retored. If file is immutable/appendOnly 3724 * call without this flag before restoring data 3725 * then call with this flag after restoring data 3726 * GPFS_ATTRFLAG_INCL_ENCR - file attributes for encryption 3727 * are restored. Note that this may result in the file's 3728 * File Encryption Key (FEK) being changed, and in this 3729 * case any prior content in the file is effectively lost. 3730 * This option should only be used when the entire file 3731 * content is restored after the attributes are restored. 3732 * 3733 * buffer: pointer to buffer for returned attributes 3734 * pathName: pointer to file path and file name for file 3735 * May be set to NULL. 3736 * 3737 * Returns: 0 Successful 3738 * -1 Failure and errno is set 3739 * 3740 * Errno: ENOSYS function not available 3741 * EINVAL the buffer does not contain valid attribute data 3742 * EINVAL invalid flags provided 3743 * EPERM caller must have superuser privilege 3744 * ESTALE cached fs information was invalid 3745 * GPFS_E_INVAL_IFILE bad ifile parameters 3746 */ 3747 int GPFS_API 3748 gpfs_lwe_putattrs(gpfs_lwe_sessid_t sid, 3749 void *hanp, 3750 size_t hlen, 3751 gpfs_lwe_token_t token, 3752 int flags, 3753 void *buffer, 3754 const char *pathName); 3755 3756 3757 3758 const char* GPFS_API 3759 gpfs_get_fspathname_from_fsname(const char* fsname_or_path); 3760 /* Check that fsname_or_path refers to a GPFS file system and find the path to its root 3761 Return a strdup()ed copy of the path -OR- NULL w/errno 3762 */ 3763 3764 int GPFS_API 3765 /* experimental */ 3766 gpfs_qos_getstats( 3767 const char *fspathname, /* in only: path to file system*/ 3768 unsigned int options, /* in only: option flags: 0=begin at specified qip, 1=begin after qip */ 3769 unsigned int qosid, /* in only: 0 or a specific qosid at which to start or continue */ 3770 gpfs_pool_t poolid, /* in only: -1 or a specific poolid at which to start or continue */ 3771 unsigned int mqips, /* in only: max number of qip=(qosid,poolid) histories to retrieve */ 3772 unsigned int nslots, /* in only: max number of time slots of history to retrieve */ 3773 void *bufferP, /* ptr to return stat structures */ 3774 unsigned int bufferSize); /* sizeof stat buffer or 0 */ 3775 3776 int GPFS_API 3777 /* experimental */ 3778 gpfs_qos_control( 3779 const char *fspathname, /* in only: path to file system*/ 3780 void *bufferP, /* in/out control/get/set structs */ 3781 unsigned int bufferSize); 3782 3783 int GPFS_API 3784 gpfs_qos_set( 3785 const char *fspathname, 3786 const char *classname, /* "gold", "silver", or .. "1" or "2" .. */ 3787 int id, /* process id or pgrp or userid */ 3788 int which, /* process, pgrp or user */ 3789 double* qshareP); /* return the share, percentage or when negative IOP limit */ 3790 /* if id==0 then getpid() or getpgrp() or getuid() 3791 if which==0 or 1 then process, if 2 process then group, if 3 then userid 3792 Return -1 on error, with errno= 3793 ENOSYS if QOS is not available in the currently installed GPFS software. 3794 ENOENT if classname is not recognized. 3795 ENXIO if QOS throttling is not active 3796 (but classname is recognized and *qshareP has configured value) 3797 */ 3798 3799 /* For the given process get QOS info */ 3800 int GPFS_API 3801 gpfs_qos_get( 3802 const char *fspathname, 3803 int *classnumP, 3804 char classname[18], /* "gold", "silver", or .. "1" or "2" .. */ 3805 int id, /* process id or pgrp or userid */ 3806 int which, /* process, pgrp or user */ 3807 double* qshareP); /* return the share, percentage or when negative IOP limit */ 3808 3809 /* given classname, set *classnumP and set *qshareP 3810 Return -1 on error, with errno= 3811 ENOSYS if QOS is not available in the currently installed GPFS software. 3812 ENOENT if classname is not recognized. 3813 ENXIO if QOS throttling is not active 3814 (but classname is recognized, *classnumP and *qshareP have configured values) 3815 */ 3816 int GPFS_API 3817 gpfs_qos_lkupName( 3818 const char *fspathname, 3819 int *classnumP, 3820 const char *classname, 3821 double* qshareP); 3822 3823 /* given classnumber, find name and share (similar to above), but start with number instead of name */ 3824 int GPFS_API 3825 gpfs_qos_lkupVal( 3826 const char *fspathname, 3827 int val, 3828 char classname[18], 3829 double* qshareP); 3830 3831 int GPFS_API 3832 gpfs_ioprio_set(int,int,int); /* do not call directly */ 3833 3834 int GPFS_API 3835 gpfs_ioprio_get(int,int); /* do not call directly */ 3836 3837 3838 /* NAME: gpfs_enc_file_rewrap_key() 3839 * 3840 * FUNCTION: Re-wrap the File Encryption Key (FEK) for the file, 3841 * replacing the usage of the original (second parameter) 3842 * Master Encryption Key (MEK) with the new key provided as 3843 * the third parameter. The content of the file remains intact. 3844 * 3845 * If the FEK is not currently being wrapped with the MEK 3846 * identified by the second parameter then no action is taken. 3847 * 3848 * This function is normally invoked before the original MEK is 3849 * removed. 3850 * 3851 * The file may be opened in read-only mode for this function 3852 * to perform the key rewrap. 3853 * 3854 * Superuser privilege is required to invoke this API. 3855 * 3856 * INPUT: fileDesc: File descriptor for file whose key is to be rewrapped 3857 * orig_key_p: Key ID for the key (MEK) to be replaced 3858 * new_key_p: Key ID for the new key (MEK) to be used 3859 * 3860 * OUTPUT: N/A 3861 * 3862 * Returns: 0 success 3863 * -1 failure 3864 * 3865 * Errno: 3866 * EACCESS Existing or new key cannot be retrieved 3867 * The new key is already being used to wrap the 3868 * file's FEK 3869 * EBADF Bad file descriptor 3870 * EINVAL Arguments are invalid: key format is incorrect 3871 * EFAULT An invalid pointer is supplied; the associated 3872 * data could not be copied in or out of the kernel 3873 * E2BIG Key IDs provided are too long 3874 * ENOSYS Function not available (cluster or file system not 3875 * enabled for encryption) 3876 * EPERM File is in a snapshot 3877 * Caller must have superuser privilege 3878 */ 3879 3880 /* The Key ID is a string comprised of the key ID and the remote key 3881 server RKM ID, separated by ':' */ 3882 typedef const char *gpfs_enc_key_id_t; /* "<KEY ID> : <KMS ID>" */ 3883 3884 int GPFS_API 3885 gpfs_enc_file_rewrap_key(gpfs_file_t fileDesc, 3886 gpfs_enc_key_id_t orig_key_p, 3887 gpfs_enc_key_id_t new_key_p); 3888 3889 3890 /* NAME: gpfs_enc_get_algo() 3891 * 3892 * FUNCTION: Retrieve a string describing the encryption algorithm, key 3893 * length, Master Encryption Key(s) ID, and wrapping and combining 3894 * mechanisms used for the file. 3895 * 3896 * INPUT: fileDesc: File descriptor for file whose encryption 3897 * algorithm is being retrieved 3898 * encryption_xattrP: content of the gpfs.Encryption 3899 * extended attribute, retrieved by a call to 3900 * gpfs_fcntl (with structure type GPFS_FCNTL_GET_XATTR) 3901 * xattr_len: length of the data in encryption_xattrP 3902 * algo_txt_size: space reserved by the caller for algo_txtP 3903 * 3904 * OUTPUT: algo_txtP: NULL-terminated string describing the 3905 * encryption for the file 3906 * 3907 * Returns: 0 success 3908 * -1 failure 3909 * 3910 * Errno: 3911 * ENOENT File not found 3912 * EBADF Bad file handle, not a GPFS file 3913 * EACCESS Permission denied 3914 * EFAULT Bad address provided 3915 * EINVAL Not a regular file 3916 * EINVAL Invalid values for xattr_len or algo_txt_size 3917 * EINVAL Invalid content of encryption extended attribute 3918 * ENOSYS Function not available 3919 * E2BIG Output string does not fit in algo_txtP 3920 */ 3921 3922 int GPFS_API 3923 gpfs_enc_get_algo(gpfs_file_t fileDesc, 3924 const char *encryption_xattrP, 3925 int xattr_len, 3926 char *algo_txtP, 3927 int algo_txt_size); 3928 3929 3930 /* NAME: gpfs_init_trace() 3931 * 3932 * FUNCTION: Initialize the GPFS trace facility and start to use it. 3933 * Must be called before calling gpfs_add_trace(). 3934 * 3935 * Returns: 0 Success 3936 * -1 Failure 3937 * 3938 * Errno: ENOENT file not found 3939 * ENOMEM Memory allocation failed 3940 * EACCESS Permission denied 3941 * ENFILE Too many open files 3942 * ENOSYS Function not available 3943 */ 3944 int GPFS_API 3945 gpfs_init_trace(void); 3946 3947 /* NAME: gpfs_query_trace() 3948 * 3949 * FUNCTION: Query and cache the latest settings of GPFS trace facility. 3950 * Generally this should be called by the notification handler 3951 * for the "traceConfigChanged" event, which is invoked when 3952 * something changes in the configuration of the trace facility. 3953 * 3954 * Returns: 0 Success 3955 * -1 Failure 3956 * 3957 * Errno: ENOENT file not found 3958 * ENOMEM Memory allocation failed 3959 * EACCESS Permission denied 3960 * ENFILE Too many open files 3961 * ENOSYS Function not available 3962 */ 3963 int GPFS_API 3964 gpfs_query_trace(void); 3965 3966 /* NAME: gpfs_add_trace() 3967 * 3968 * FUNCTION: write the logs into GPFS trace driver. When the user specified 3969 * parameter "level" is less than or equal to the GPFS trace level, 3970 * the log message pointed to by parameter "msg" would be written to 3971 * GPFS trace buffer, and user can use mmtracectl command to cut 3972 * the GPFS trace buffer into a file to observe. Must be called after 3973 * the call to gpfs_init_trace(). Also ensure the gpfs_query_trace() 3974 * is called properly to update the gpfs trace level cached in 3975 * application, otherwise, the trace may miss to write down to 3976 * GPFS trace driver. 3977 * 3978 * Input: level: the level for this trace generation. When the level 3979 * is less than or equal to the GPFS trace level, this 3980 * trace record would be written to GPFS trace buffer. 3981 * msg: the message string that would be put into GPFS trace buffer. 3982 * 3983 * Returns: None. 3984 */ 3985 void GPFS_API 3986 gpfs_add_trace(int level, const char *msg); 3987 3988 /* NAME: gpfs_fini_trace() 3989 * 3990 * FUNCTION: Stop using GPFS trace facility. This should be paired with 3991 * gpfs_init_trace(), and must be called after the last 3992 * gpfs_add_trace(). 3993 * 3994 * Returns: None. 3995 */ 3996 3997 void gpfs_fini_trace(void); 3998 3999 /* 4000 * When GPFS_64BIT_INODES is defined, use the 64-bit interface definitions as 4001 * the default. 4002 */ 4003 4004 #ifdef GPFS_64BIT_INODES 4005 #undef GPFS_D_VERSION 4006 #define GPFS_D_VERSION GPFS_D64_VERSION 4007 #undef GPFS_IA_VERSION 4008 #define GPFS_IA_VERSION GPFS_IA64_VERSION 4009 4010 #define gpfs_ino_t gpfs_ino64_t 4011 #define gpfs_gen_t gpfs_gen64_t 4012 #define gpfs_uid_t gpfs_uid64_t 4013 #define gpfs_gid_t gpfs_gid64_t 4014 #define gpfs_snapid_t gpfs_snapid64_t 4015 #define gpfs_nlink_t gpfs_nlink64_t 4016 #define gpfs_timestruc_t gpfs_timestruc64_t 4017 #define gpfs_direntx_t gpfs_direntx64_t 4018 #define gpfs_direntx gpfs_direntx64 4019 #define gpfs_iattr_t gpfs_iattr64_t 4020 4021 #define gpfs_get_snapid_from_fssnaphandle gpfs_get_snapid_from_fssnaphandle64 4022 #define gpfs_open_inodescan gpfs_open_inodescan64 4023 #define gpfs_open_inodescan_with_xattrs gpfs_open_inodescan_with_xattrs64 4024 #define gpfs_next_inode gpfs_next_inode64 4025 #define gpfs_next_inode_with_xattrs gpfs_next_inode_with_xattrs64 4026 #define gpfs_seek_inode gpfs_seek_inode64 4027 #define gpfs_stat_inode gpfs_stat_inode64 4028 #define gpfs_stat_inode_with_xattrs gpfs_stat_inode_with_xattrs64 4029 #define gpfs_iopen gpfs_iopen64 4030 #define gpfs_ireaddir gpfs_ireaddir64 4031 #define gpfs_ireaddirx gpfs_ireaddirx64 4032 #define gpfs_iwritedir gpfs_iwritedir64 4033 #define gpfs_ireadlink gpfs_ireadlink64 4034 #endif 4035 4036 #define gpfs_icreate gpfs_icreate64 4037 4038 #ifdef __cplusplus 4039 } 4040 #endif 4041 4042 #endif /* H_GPFS */ 4043