Skip Navigation Links | |
Exit Print View | |
Sun QFS and Sun Storage Archive Manager 5.3 Reference Manual Sun QFS and Sun Storage Archive Manager 5.3 Information Library |
1. User Commands (Man Pages Section 1)
2. Maintenance Commands (Man Pages Section 1M)
3. Library Functions (Man Pages Section 3)
4. Library Functions (Man Pages Section 3X)
5. File Formats (Man Pages Section 4)
NAME sam_stat, sam_lstat, sam_segment_stat - Gets file or segment status SYNOPSIS cc [flag ...] file ... -L/opt/SUNWsamfs/lib -R/opt/SUNWsamfs/lib -lsam [library ...] #include "/opt/SUNWsamfs/include/stat.h" int sam_stat(const char *path, struct sam_stat *buf, size_t bufsize); int sam_lstat(const char *path, struct sam_stat *buf, size_t bufsize); int sam_segment_stat(const char *path, struct sam_stat *buf, size_t bufsize); AVAILABILITY SUNWqfs SUNWsamfs DESCRIPTION The sam_stat() function returns file system attributes for the file to which path points. The sam_segment_stat() function works with segmented files. It returns attributes for the file segments to which path points. The sam_lstat() function returns file attributes similar to sam_stat(). The difference is that if file is a symbolic link, sam_lstat() returns information about the link, while sam_stat() returns information about the file or the file's segments that the link references. If these functions succeed, they write file attributes to the structure, or to the array of structures, to which buf points. If they are returning information about a segmented file, they write information about the first file segment to the first structure in the array of structures. They write information about the second file segment to the second structure in the array of structures, etc. Note that when sam_stat() and sam_lstat() are executed on a segmented file, the functions return information about the index inode. The sam_stat and sam_lstat functions are supported in Sun QFS and SAM-QFS environments. The sam_segment_stat function is supported in Sun QFS and SAM-QFS environments. OPTIONS These functions accept the following arguments: path Specifies the path to the file. This is the file or segmented file for which the file status is to be obtained. Read, write, or execute permission of the named file is not required, but all directories listed in the path leading to the file must be searchable. buf Specifies a pointer to a structure into which information is placed concerning the file. The functions use one sam_stat structure from this argument for each single file or file segment. The length of buf, in bytes, must be sized as follows: bytes = number_of_segments * sizeof(struct sam_stat) The number_of_segments is 1 for a nonsegmented file (used by sam_stat and sam_lstat). The number_of_segments is greater than 1 for a segmented file (used by sam_segment_stat). For an unsegmented file, buf must be a sam_struct structure. For a segmented file, buf must be an array of sam_struct structures. bufsize Specifies the length of the user's buffer, in bytes, to which buf points. STRUCTURE CONTENTS Table 1 and Table 2 show the content of the structure pointed to by buf. TABLE 1. Members of struct sam_stat That Contain POSIX Standard File Attributes Data Type Field Name Description ulong_t st_mode File mode (see mknod(2) ulong_t st_ino Inode number ulong_t st_dev ID of device containing the file ulong_t st_nlink Number of links ulong_t st_uid Numeric user ID of the file's owner ulong_t st_gid Numeric group ID of the file's owner u_longlong_t st_size File size in bytes time_t st_atime Time of last access time_t st_mtime Time of last data modification time_t st_ctime Time of last file status change The following list describes Table 1's fields in more detail. st_mode The mode of the file as described in mknod(2). In addition to the modes described in mknod(2), the mode of a file may also be S_IFLNK if the file is a symbolic link. Note that S_IFLNK can be returned only by sam_lstat(). st_ino This field uniquely identifies the file in a given file system. The pair st_ino and st_dev uniquely identifies regular files. st_dev This field uniquely identifies the file system that contains the file. st_nlink This field should be used only by administrative commands. st_uid The numeric user ID of the file's owner. st_gid The numeric group ID of the file's owner. st_size For regular files, this is the address of the end of the file. st_atime Time when file data was last accessed. Changed by the following functions: creat, mknod, pipe, utime, and read. st_mtime Time when data was last modified. Changed by the following functions: creat, mknod, pipe, utime, and write. st_ctime Time when file status was last changed. Changed by the following functions: chmod, chown, creat, link, mknod, pipe, unlink, utime, and write. TABLE 2. Members of struct sam_stat That Contain Sun QFS and SAM-QFS File Attributes Data Type Field Name Description uint_t old_attr Backward compatible, see attr time_t attribute_time Time attributes last changed time_t creation_time Time inode created time_t residence_time Time file changed residence struct sam_copy_s copy[MAX_ARCHIVE] Array of archive copy information uchar_t cs_algo Checksum algorithm indicator uchar_t flags Flags: staging, stage err, etc. uchar_t stripe_width Stripe width set by setfa -s or -h uchar_t stripe_group Stripe group set by setfa -g or -o ulong_t gen Inode generation number ulong_t partial_size Partial size in kilobytes dev_t rdev ID of device if S_IFBLK or S_IFCHR u_longlong_t st_blocks Block count in 512 byte blocks ulong_t segment_size Segment size in megabytes ulong_t segment_number Number of this segment uint_t stage_ahead Number of segment to stage ahead uint_t admin_id admin ID; inherited from directory uint_t allocahead Allocate ahead set by setfa -A uint_t obj_depth Stripe depth (KB) set by setfa -v u_longlong_t csum_val[2] 128 checksum value time_t rperiod_start_time Time WORM retention period started uint_t rperiod_duration WORM retention period duration u_longlong_t attr File attributes The following list describes Table 2's fields in more detail. attr Attributes assigned to the file by Sun QFS and SAM-QFS functions and operations. attribute_time Time when the Sun QFS and SAM-QFS attributes last changed. Changed by the following functions: sam_archive, sam_release, and sam_stage. Also changed by the automatic archive, release, and stage operations. creation_time Time when the inode was created for the file. residence_time Time when the file changed residency. Changed by the release and stage operations. cs_algo Indicates the algorithm that is used when calculating the data verification value (checksum) for the file. For more information, see ssum(1). flags Flags containing miscellaneous additional information about the file. Includes a bit that indicates that a stage is pending or is in progress on the file. Also includes a bit that indicates that the last attempt to stage the file failed. gen The inode generation number. RETURN VALUES Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and errno is set to indicate the error. ERRORS The sam_stat() and sam_lstat() functions fail if one or more of the following are true: EACCES Search permission is denied for a component of the path prefix. EFAULT Either buf or path points to an illegal address. EINTR A signal was caught during sam_stat() or sam_lstat() function processing. ELOOP Too many symbolic links were encountered in translating path. EMULTIHOP Components of path require hopping to multiple remote machines and the file system does not allow it. ENAMETOOLONG The length of the path argument exceeds {PATH_MAX}, or the length of path exceeds {NAME_MAX} while {_POSIX_NO_TRUNC} is in effect. ENOENT The named file does not exist or is the null pathname. ENOLINK path points to a remote machine, and the link to that machine is no longer active. ENOTDIR A component of the path prefix is not a directory. EOVERFLOW A component is too large to store in the structure to which buf points. EXAMPLES This example uses sam_segment_stat to obtain the status of a segmented file. struct sam_stat file_info; struct sam_stat *data_seg_info_ptr; int number_of_data_segments; int result; /* * Initialize file_info to be all zero bits: */ memset((void *) "file_info, 0, sizeof(struct sam_stat)); /* * Stat the file using the regular sam_stat function: */ result = sam_stat(path, "file_info, sizeof(struct sam_stat)); if (result != 0) { fprintf(stderr, "Error failed to sam stat the file, %s.\n", path); exit -70; } if (SS_ISSEGMENT_F(file_info.attr)) { /* * File is segmented, how many data segments does it have? */ /* * Determine how many complete (full) segments it has: */ number_of_data_segments = file_info.st_size / (file_info.segment_size * 1048576); /* * Determine if it has one data segment that isn't "full": */ if (file_info.st_size > number_of_data_segments * file_info.segment_size * 1048576) { number_of_data_segments++; } } else { /* * File isn't segmented */ number_of_data_segments = 1; } /* * Allocate enough memory to hold all of the stat information for each * data segment: */ data_seg_info_ptr = (struct sam_stat *) malloc(number_of_data_segments * sizeof(struct sam_stat)); if (data_seg_info_ptr == NULL) { fprintf(stderr, "Error failed to allocate memory for data segment stat operation.\n"); exit -80; } /* * Initialize file_info to be all zero bits: */ memset((void *) data_seg_info_ptr, 0, number_of_data_segments * sizeof(struct sam_stat)); if (SS_ISSEGMENT_F(file_info.attr)) { /* * Use sam_segment_stat to get the stat information for all of the * data segments of the file. */ result = sam_segment_stat(path, data_seg_info_ptr, number_of_data_segments * sizeof(struct sam_stat)); } else { /* * File is not segmented, just use the stat information from the * sam_stat call */ memcpy((void *) data_seg_info_ptr, (void *)file_info, sizeof(struct sam_stat)); } if (!SS_ISSEGMENT_F(file_info.attr)) { number_of_data_segments = 1; data_seg_info_ptr = "file_info_ptr; } /* * data_seg_info_ptr now points to an array of sam_stat structures. * There is one sam_stat structure for each data segment and they are * indexed 0 through number_of_data_segments - 1. * * Do not forget to deallocate the memory buffer pointed to by * data_seg_info_ptr using free. */ SEE ALSO ssum(1). mknod(2), stat(2).