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 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 indicated 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() subroutines 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 sections 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 leading 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:

Table 1: Elements of the sam_section structure
Name	Data Type	Description
vsn[32];	char	The unique identifier of the volume that holds the section, a null-terminated string of up to 31 characters.
length;	u_longlong_t	The length of the section on the volume.
position;	u_longlong_t	The location of the start of the archive file that contains this section.
offset;	u_longlong_t	The location of this section relative to the start of the archive file.

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

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 component 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 component 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 program or script must retrieve the VSN information for the archive copy from the copy member of the sam_stat structure that was filled in when your program 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 segmented, 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 structures under the index segment_ord.

A struct sam_copy_s structure has the following members:

Table 2: Elements of the sam_copy_s structure
Name	Data Type	Description
position;	u_longlong_t	The location of the start of the archive file.
creation_time;	time_t	The time when the archive copy was created.
offset;	uint_t	The location of the copy relative to the start of the archive file.
flags;	ushort_t
n_vsns;	short
media[4];	char
vsn[32];	char

flags

Flags show the status of the archive copy (made, stale, damaged, etc.). The bit masks in ∕opt∕SUNWsamfs∕include∕stat.h resolve flags into copy status.

n_vsns

The number of VSNs used by the archived copy (greater than one if the copy overflows volumes).

media

The media type, a null-terminated string of up to 3 characters.

vsn

The unique identifier of the volume that holds the copy, a null-terminated string of up to 31 characters.

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).

NOTES

The StorageTek QFS and Oracle HSM file systems permit a maximum of MAX_VOLUMES sections per archive copy. Hence, instead of dynamically allocating a buffer of sam_vsn_stat structures, a more efficient 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 .