NAME

sam_stat, sam_lstat, sam_fstat, 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"

sam_stat(const int char *path, struct sam_stat *buf, size_t bufsize);

sam_lstat(const int char *path, struct sam_stat *buf, size_t bufsize);

sam_fstat(const int int fd, struct sam_stat *buf, size_t bufsize);

sam_segment_stat(const int 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_fstat() function returns file system attributes for the file to which the open file descriptor fd 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, sam_lstat, and sam_segment_stat functions are supported in StorageTek QFS and Oracle HSM environments. The sam_fstat function is supported in Solaris StorageTek QFS and Oracle HSM environments.

If the file has a message-digest set using an extended algorithm, the hash value must retrieved separately using the sam_getdigest (3x) function.

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.

fd

Specifies the file descriptor on which to get stat information. (sam_fstat only)

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: Elements of the sam_stat structure that contain standard, POSIX file attributes
Name	Type	Description
st_mode	ulong_t	File mode (see `mknod` (2)
st_ino	ulong_t	Inode number
st_dev	ulong_t	ID of device containing the file
st_nlink	ulong_t	Number of links
st_uid	ulong_t	Numeric user ID of the file's owner
st_gid	ulong_t	Numeric group ID of the file's owner
st_size	u_longlong_t	File size in bytes
st_atime	time_t	Time of last access
st_mtime	time_t	Time of last data modification
st_ctime	time_t	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.

.ce 2 TABLE 2. Members of struct sam_stat That Contain StorageTek QFS and Oracle HSM File Attributes

Name	Type	Description
old_attr	uint_t	Backward compatible, see attr
attribute_time	time_t	Time attributes last changed
creation_time	time_t	Time inode created
residence_time	time_t	Time file changed residence
copy[MAX_ARCHIVE]	struct sam_copy_s	Array of archive copy information
cs_algo	uchar_t	Checksum algorithm indicator
flags	uchar_t	Flags: staging, stage err, etc.
stripe_width	uchar_t	Stripe width set by setfa -s or -h
stripe_group	uchar_t	Stripe group set by setfa -g or -o
gen	ulong_t	Inode generation number
partial_size	ulong_t	Partial size in kilobytes
rdev	dev_t	ID of device if S_IFBLK or S_IFCHR
st_blocks	u_longlong_t	Block count in 512 byte blocks
segment_size	ulong_t	Segment size in megabytes
segment_number	ulong_t	Number of this segment
stage_ahead	uint_t	Number of segment to stage ahead
admin_id	uint_t	admin ID; inherited from directory
allocahead	uint_t	Allocate ahead set by setfa -A
obj_depth	uint_t	Stripe depth (KB) set by setfa -v
csum_val[2]	u_longlong_t	128 checksum value
rperiod_start_time	time_t	Time WORM retention period started
rperiod_duration	uint_t	WORM retention period duration
attr	u_longlong_t	File attributes

The following list describes Table 2's fields in more detail.

attr

Attributes assigned to the file by StorageTek QFS and Oracle HSM functions and operations.

attribute_time

Time when the StorageTek QFS and Oracle HSM 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.
 *∕