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_vsn_stat, sam_segment_vsn_stat - Gets VSN status for an archive copy that overflows VSNs SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsam [library ... ] #include </opt/SUNWsamfs/include/stat.h> int sam_vsn_stat(const char *path, int copy, struct sam_section *buf, size_t bufsize); int sam_segment_vsn_stat(const char *path, int copy, int segment_ord, struct sam_section *buf, size_t bufsize); DESCRIPTION The sam_vsn_stat() function obtains information about the VSNs for the archive copy indicated by copy of path, where path points to a non-segmented file. If sam_vsn_stat() is called and path points to a segmented file, then VSN information about the archive copy of the segmented file's index inode is returned. The sam_segment_vsn_stat() function obtains information about the VSNs for the archive copy indicated by copy of the data segment indicated by segment_ord of the segmented file pointed to by path. sam_vsn_stat() and sam_segment_vsn_stat() obtain information about the VSNs for the indicated archive copy when the indi- cated archive copy uses multiple VSNs. sam_vsn_stat() and sam_segment_vsn_stat() fail if called to obtain VSN stat information for an archive copy that only uses one VSN. Use the sam_stat() or sam_segment_stat() sub- routines to determine the number of VSNs used by a given archive copy and to get VSN information for archive copies that only use one VSN. sam_vsn_stat() places VSN information for all of the sec- tions that comprise the overflowed archive copy into buf. Read, write, or execute permission of the named file is not required, but all directories listed in the path name lead- ing to the file must be searchable. copy is the archive copy number (0, 1, 2 or 3). segment_ord is the data segment number (0, ..., n_segs - 1) where n_segs is the current number of data segments that comprise the file pointed to by path. buf is a pointer to a sam_section structure into which VSN information is placed concerning the file's archive copy. bufsize is the length of the user's buffer to which buf points. sam_vsn_stat and sam_segment_vsn_stat place VSN information for each overflowed section that comprises the archive copy into buf. Hence, bufsize should be at least sizeof(struct sam_vsn_stat) * n_vsns bytes, where n_vsns is the number of VSNs used by the archived copy. The contents of the structure pointed to by buf include the following struct sam_section members: char vsn[32]; u_longlong_t length; u_longlong_t position; u_longlong_t offset; vsn The VSN of the section. This is a null-terminated string with a maximum of 31 characters. length The length of the section on the volume. position The position of the start of the archive file that contains this section. offset The offset of this file on the archive file. RETURN VALUES Upon successful completion, a value of 0 is returned. Oth- erwise, a value of -1 is returned and errno is set to indi- cate the error. ERRORS sam_vsn_stat() and sam_segment_vsn_stat() fail if one or more of the following are true: EACCES Search permission is denied for a com- ponent of the path prefix. EFAULT buf or path points to an illegal address. EINTR A signal was caught during the sam_vsn_stat() function. 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 a path com- ponent 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 pointed to by buf. USAGE sam_vsn_stat Call sam_stat to get the number of VSNs used for the archive copy. The call to sam_stat will write the number of VSNs used by the archive copy in your struct sam_stat buffer in the member copy[copy].n_vsns. If the archive copy uses only one VSN (the number of VSNs is 1), then your pro- gram or script must retrieve the VSN information for the archive copy from the copy member of the sam_stat struc- ture that was filled in when your pro- gram or script called sam_stat. The copy member of the sam_stat structure is of type struct sam_copy_s. sam_segment_vsn_stat Call sam_stat to determine whether the file pointed to by path is segmented. If the file pointed to by path is not segmented, then use sam_vsn_stat to obtain VSN information as detailed above. If the file pointed to by path is seg- mented, then call sam_segment_stat to get the number of VSNs used for the archive copy indicated by copy of the data segment indicated by segment_ord. The call to sam_segment_stat will write the number of VSNs used by the archive copy of the indicated data segment in your array of sam_stat structures in the member located in sam_stat_buff_array[segment_ord].copy[copy].n_vsns. If the archive copy uses only one VSN (the number of VSNs is 1), then your program or script must retrieve the VSN information for the archive copy from the copy member of the element in the array of sam_stat structures that was filled in when your program or script called sam_segment_stat. The copy member of the sam_stat structure is of type struct sam_copy_s and is found in the array of sam_stat struc- tures under the index segment_ord. A struct sam_copy_s structure has the following members: u_longlong_t position; time_t creation_time; uint_t offset; ushort_t flags; short n_vsns; char media[4]; char vsn[32]; position Location of the archive file creation_time Time that the archive copy was created offset Location of the copy in the archive file flags Sun QFS and SAM-QFS archive copy status flags. These indicate whether the archive copy has been made, is stale, is damaged, etc. See /opt/SUNWsamfs/include/stat.h for bit masks which can be applied to these flags to resolve the state and status of the archive copy. n_vsns Number of VSNs used by the archived copy. Will be 1 in case of no overflow, will be greater than one if the archive copy over- flows volumes. media Media type. This is a null-terminated string with a maximum of 3 characters. vsn The VSN of the copy. This is a null- terminated string with a maximum of 31 char- acters. If the archive copy uses more than one VSN (the number of VSNs is greater than 1), then your program or script must call sam_vsn_stat or sam_segment_vsn_stat to retrieve the VSN information for all of the sections that comprise the archive copy. Do not call sam_vsn_stat or sam_segment_vsn_stat if the archive copy uses only one VSN (does not overflow). SEE ALSO sam_stat(3) NOTES The Sun QFS and SAM-QFS file systems permit a maximum of MAX_VOLUMES sections per archive copy. Hence, instead of dynamically allocating a buffer of structures, a more effi- cient method is to to declare a static array with MAX_VOLUMES number of elements. The constant MAX_VOLUMES is declared in the following include file: /opt/SUNWsamfs/include/rminfo.h .