sam_stat(3)

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 StorageTek QFS, Sun StorageTek SAM-FS, and Sun SAM-QFS environments. The sam_segment_stat function is supported in Sun StorageTek SAM-FS and Sun 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 StorageTek QFS, Sun StorageTek SAM-FS, and Sun SAM-QFS File Attributes

Data Type | Field Name | Description
uint_t | attr | File attributes
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
uchar_t | stripe_group | Stripe group set by setfa -g
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 size set by setfa -A
u_longlong_t | csum_val[2] | 128 checksum value

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

attr
    Attributes assigned to the file by Sun StorageTek QFS, Sun StorageTek SAM-FS, and Sun SAM-QFS functions and operations.

attribute_time
    Time when the Sun StorageTek QFS, Sun StorageTek SAM-FS, and Sun 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).