| 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 |
| 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_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
QFS and SAM-QFS environments. The sam_segment_stat function
is supported in Sun QFS and 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 QFS and SAM-QFS File Attributes
Data Type Field Name Description
uint_t old_attr Backward compatible, see attr
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 or -h
uchar_t stripe_group Stripe group set by setfa -g or -o
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 set by setfa -A
uint_t obj_depth Stripe depth (KB) set by setfa -v
u_longlong_t csum_val[2] 128 checksum value
time_t rperiod_start_time Time WORM retention period started
uint_t rperiod_duration WORM retention period duration
u_longlong_t attr File attributes
The following list describes Table 2's fields in more
detail.
attr Attributes assigned to the file by Sun QFS and
SAM-QFS functions and operations.
attribute_time
Time when the Sun QFS and 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).
|