JavaScript is required to for searching.
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
search filter icon
search icon

Document Information

Preface

1.  User Commands (Man Pages Section 1)

2.  Maintenance Commands (Man Pages Section 1M)

3.  Library Functions (Man Pages Section 3)

intro_libsam(3)

intro_libsamrpc(3)

qfs_listio(3)

sam_advise(3)

sam_archive(3)

sam_audit(3)

sam_cancelstage(3)

sam_chmed(3)

sam_clear_request(3)

sam_closecat(3)

sam_damage(3)

sam_devstat(3)

sam_devstr(3)

sam_errno(3)

sam_exarchive(3)

sam_export(3)

sam_getcatalog(3)

sam_getfsdata(3)

sam_getfsdisks(3)

sam_import(3)

sam_load(3)

sam_lstat(3)

sam_mig_create_file(3)

sam_mig_mount_media(3)

sam_mig_rearchive(3)

sam_mig_release_device(3)

sam_mig_stage_end(3)

sam_mig_stage_error(3)

sam_mig_stage_file(3)

sam_mig_stage_write(3)

sam_move(3)

sam_odlabel(3)

sam_opencat(3)

sam_readrminfo(3)

sam_rearch(3)

sam_release(3)

sam_request(3)

sam_restore_copy(3)

sam_restore_file(3)

sam_segment(3)

sam_segment_stat(3)

sam_segment_vsn_stat(3)

sam_set_fs_contig(3)

sam_set_fs_thresh(3)

sam_set_state(3)

sam_setfa(3)

sam_settings(3)

sam_ssum(3)

sam_stage(3)

sam_stat(3)

sam_tplabel(3)

sam_unarchive(3)

sam_undamage(3)

sam_unload(3)

sam_unrearch(3)

sam_vsn_stat(3)

usam_mig_cancel_stage_req(3)

usam_mig_initialize(3)

usam_mig_stage_file_req(3)

4.  Library Functions (Man Pages Section 3X)

5.  File Formats (Man Pages Section 4)

6.  Standards, Environment, and Macros (Man Pages Section 5)

7.  Device and Network Interfaces (Man Pages Section 7)

sam_segment_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 indi-
     cated 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() sub-
     routines  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  sec-
     tions 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 lead-
     ing 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.   Oth-
     erwise,  a value of -1 is returned and errno is set to indi-
     cate 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  com-
                         ponent 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 com-
                         ponent    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 pro-
                           gram or script must retrieve  the  VSN
                           information  for the archive copy from
                           the copy member of the sam_stat struc-
                           ture that was filled in when your pro-
                           gram 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 seg-
                           mented,  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  struc-
                           tures 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  QFS  and  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  over-
                    flows 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 char-
                    acters.

     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 QFS and 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  effi-
     cient   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 .