sam_vsn_stat(3)

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:

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

    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 StorageTek SAM-FS and Sun 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 overflows 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 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).

SEE ALSO
sam_stat(3)

NOTES
The Sun StorageTek SAM-FS and the Sun 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 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 .